[user@localhost ~]$./puniconf_
./home ./about ./plugins ./plugin_API ./screenshots ./download ./old_source

./puniconf

puniconf is a GUI configuration shell, written in Perl, for the many *nix flavors of OS's. It does nothing on its own, but accomplishes configuration tasks by means of plugins.
This document contains information related to the creation of plugins for puniconf.

Requirements

In order to run puniconf, you need:

Requirement Tested with? How to find out what version you have Use
Perl v5.8.3 built for i386-linux-thread-multi perl -v Core Language Interpreter
Gtk+ libraries v2.4.0 pkg-config --modversion gtk+-2.0 Core GUI C Libraries
Gtk2-Perl module v1.051 perl -MGtk2 -e 'print $Gtk2::VERSION, "\n"' Perl interface to Gtk-2.0 libraries
Glade-2.0 v2.3.6 pkg-config --modversion libglade-2.0 Glade GUI Designer, C Libraries (glade designer comes with libglade)
Gtk2::GladeXML Perl module v1.00 perl -MGtk2::GladeXML -e 'print $Gtk2::GladeXML::VERSION, "\n"' Perl interface to Glade-2.0 libraries
Religion Perl module v1.04 (modified) [comes with puniconf] Used to catch die() and warn()
Devel::Size Perl module v0.58 perl -MDevel::Size -e 'print $Devel::Size::VERSION, "\n"' Used to get variable information (to optimize puniconf)

Testing

The specs on the machine I used are as follows:

Machine: Hewlett Packard Pavilion 6630
Processor: 500MHz Celeron (Mendocino)
Memory: 316Mb physical / 300Mb swap
Video Card: XFXForce nVidiaGeForce MX 4000 w/64Mb on-board memory

Synopsis


Universal Methods:
			puniconf::doError	($msg,$fmsg,$level,$eval)
$window		=	puniconf::getWindow
$tb		=	puniconf::getToolBar
$mb		=	puniconf::getMenu
$nb		=	puniconf::getNoteBook
$errWin		=	puniconf::getErrWindow
$helpWin	=	puniconf::getHelpWindow
$sb		=	puniconf::getStatusBar
$tb		=	puniconf::getBuffer
			puniconf::err		($errMsg [, $tagName])
			puniconf::clearErr
			puniconf::showErr
			puniconf::showStatus	( $msg )
			puniconf::addTbItem	( $widget1,$tooltip1,$privatetip1,... )
			puniconf::addMenu	( $menuTitle,$menu )
$box		=	puniconf::stockTab	( $label,$iconStr,$ttip )
$filename	=	puniconf::getFileSave	( $title )
$filename	=	puniconf::getFileOpen	( $title )
$filename	=	puniconf::getFolderOpen	( $title )

$Plugin Implemented Methods:
$widget		=	$Plugin->new
$widget		=	$Plugin->getLabel
			$Plugin->setMenu
			$Plugin->getToolbarItems
			$Plugin->Open
			$Plugin->Save
			$Plugin->Focus
$icon		=	$Plugin->getIcon
			$Plugin->getHelp		($buffer)


Description


There are several things to keep in mind while writing a plugin.

Note

All warn() calls are redirected to a dialog box, as well as to STDERR. The dialog box allows you to cut and paste the error if you want.

Note

If a function is not coded into your plugin, a warning will be issued, and puniconf will keep running as usual. However, please try to code all methods. If you don't want to use them, leave them empty or display a message to the user, with puniconf::showStatus( $msg ).

Note

Please try to maintain an OOP (Object-Oriented Perl) approach when writing your plugin. The main NoteBook is the object that handles your plugin. In order to call methods in your plugin, the method $notes->get_nth_page($notes->get_current_page()) is used to get your plugin as an object. Use the example plugin at the end of this API as a template for your plugin.

Note

It will keep things easier for you and me if you use the example plugin at the end of this API as a template for your plugin.

Note

Every Gtk2::TextView throughout puniconf uses a common Gtk2::TextBuffer. Using this buffer, you can insert named tags with the $buffer->insert_with_tags_by_name() If you want to know all the tag names, see the source for GUI/TextBuffer.pm. You can also set your buffers to the same, with
$myTextView->set_buffer( puniconf::getBuffer()).

Note

Place your plugin in the plugins/ directory in the main puniconf directory.

Note

The best way to set up the plugins is by changing the user to root if the plugins writes to root-owned files. Use the command 'chown root: plugins/myplugin.pm'. and change the permissions so only root can read: 'chmod 400 plugins/myplugin.pm'. puniconf will use only plugins it can open. FIX: if i ever move to the GtkPlug interface, you will only need to run those plugins you want.

Note

The memory requirements of puniconf seem to be due to Perl-Gtk2 libs. The demo app that comes with it is just under 8Mb, with no demos running. puniconf takes up about 12Mb with no plugins. As a general rule, allow 1Mb for every plugin running. I am working on lowering the footprint.

puniconf is a GUI configuration shell for the many *nix flavors of OS's. It consists of six (4) main UI elements and three (3) windows. The central element is the main notebook. It houses the plugins and controls other UI events. When a tab is clicked, the plugin that is then viewed, is said to be 'active'. When a plugin becomes active, several events happen. The plugin's Focus() method is invoked. Then the old active plugin's toolbar buttons are erased from the toolbar, and the active plugin's getToolbarItems() method is called, which displays the plugin's toolbar buttons, if any. Using this method, the common toolbar buttons remain, while plugin-specific buttons are visible only when that plugin is visible.
The main application window consists of a menu bar with three menus. The first menu is the File menu. This menu has Open, Close, Save, and Quit. These menus do nothing more than call the Open(), Close(), and Save() methods from the active plugin, and quit puniconf. The next menu is the plugin menu. It consists of one submenu for every plugin available. It is up to the plugin programmer to decide what menuitems to add here. The last menu is a simple Help menu that you find in any application, with one exception: you can browse each plugin's Help and About information from the respective dialogs.
The next UI element is the Toolbar. It contains Open, Save, and Quit buttons, which do the same as the menu items of the same name.
The final element in the main window is the status bar. It is used to display short status messages to the user, using puniconf::showStatus($msg).
The next window of importance is the Error, or Output, window. This window is used to display long status messages, or any other long output, to the user. For example, if you had a bit of code that iterated over a directory and changed certain files in it, and wanted to display which files were changed, you would output that to this window. Use puniconf::err($errMsg) to write to the buffer, puniconf::showErr() to show the window, and puniconf::clearErr() to clear the text in the window.
The last window is the Help window. When the user selects Help from the Help menu, a window is displayed with 2 columns. Select the plugin from the list on the left, and the plugin's help will be displayed on the right. Simple, huh?

puniconf::doError

puniconf::doError	($msg,$fmsg,$level,$eval)

Used to catch warn() and die() events. When you call warn() or die() in your plugin, this method is invoked, and a message dialog displays the message. This is pretty much an internal method, but you can use at your own risk.

Parameters:
none
Returns:
$msg:
$fmsg: The message to show.
$level:
$eval:

puniconf::getWindow

$window = puniconf::getWindow	

This is just an accessor method. It returns the main puniconf window.
This is an internal method, listed here for completeness.

Parameters:
none
Returns:
$window : a Gtk2::Window

puniconf::getToolBar

$tb = puniconf::getToolBar	

This is just an accessor method. It returns the main puniconf Toolbar.
This is an internal method, listed here for completeness. If you want to add buttons to the toolbar, use the method puniconf::toolbarAdd() from within getToolbarItems().

Parameters:
none
Returns:
$tb : a Gtk2::Toolbar

puniconf::getMenu

$mb = puniconf::getMenu	

This is just an accessor method. It returns the main puniconf MenuBar.
This is an internal method, listed here for completeness. Please use puniconf::addMenu() to add a menu to the Plugins menu.

Parameters:
none
Returns:
$mb : a Gtk2::MenuBar

puniconf::getNoteBook

$nb = puniconf::getNoteBook	

This is just an accessor method. It returns the main puniconf NoteBook. All plugins are displayed in a tab in this NoteBook.
This is an internal method, listed here for completeness. You should not have to use this method, as every plugin is a Gtk2::Widget which is added to the Notebook with new().

Parameters:
none
Returns:
$nb : a Gtk2::NoteBook

puniconf::getErrWindow

$errWin = puniconf::getErrWindow	

This is just an accessor method. It returns a window that is used for reporting various output events. Use the method puniconf::err($msg) to write to the text widget, and puniconf::showErr() to show the window.

Parameters:
none
Returns:
$errWin : a Gtk2::Window

puniconf::getHelpWindow

$helpWin = puniconf::getHelpWindow	

This is just an accessor method. It returns a window that is used to display help to the user. The window consists of 2 parts: a list of all available plugins, and a Gtk2::TextView to display the help.
Please don't use this method, instead place getHelp($buffer) to write to the TextView. This window appears when the user selects the menu Help->About.

Parameters:
none
Returns:
$helpWin : a Gtk2::Window

puniconf::getStatusBar

$statusBar = puniconf::getStatusBar	

This is just an accessor method. It returns the main statusbar.
Please use puniconf::showStatus ($msg) if you want to display status text to the user.

Parameters:
none
Returns:
$statusBar : a Gtk2::Statusbar

puniconf::getBuffer

$textBuffer = puniconf::getBuffer	

This method return a Gtk2::TextBuffer that is already tagged for easier use. You can use this to assign a TextBuffer to a Gtk2::TextView with $myTextView->set_buffer(puniconf::getBuffer()), then use $myTextView->get_buffer()->insert_with_tags_by_name ($iter, $msg, "$tag"), where $msg is the text to insert, and $tag is one of the following:

helpheading, helptopic, helptopicbody, italic, bold, big, xx-small, x-large, monospace, blue_foreground, red_background, background_stipple, foreground_stipple, big_gap_before_line, big_gap_after_line, double_spaced_line, not_editable, word_wrap, char_wrap, no_wrap, center, right_justify, wide_margins, strikethrough, underline, double_underline, superscript, subscript

Most of the preceeding styles were taken directly from the Gtk2-Perl demo.

Parameters:
none
Returns:
$textBuffer : a Gtk2::TextBuffer

puniconf::err

puniconf::err	( $errMsg [, $tagName] )

This method is used to write to the Error Window. It takes twe parameters - the text to display and the named tag to display it in. If the tag name is omitted, it will display as normal text. (See the listing of tag names under puniconf::getBuffer.)

Parameters:
$errMsg : the string to display
$tagName [optional] : the named tag with which to display $errMsg
Returns:
none

puniconf::clearErr

puniconf::clearErr()

This method clears the Error Window.

Parameters:
none
Returns:
none

puniconf::showErr

puniconf::showErr()

This method displays the Error Window.

Parameters:
none
Returns:
none

puniconf::showStatus

puniconf::showStatus ( $msg )

This method displays a very short status message in the Status Bar.

Parameters:
$msg the text to display
Returns:
none

puniconf::addTbItem

puniconf::addTbItem ( $widget1, $tooltip1, $privatetip1, ... )

This method adds buttons to the ToolBar. You can pass more than one button to add at a time. The first (fourth, seventh, etc.) parameter is the Gtk2::Widget to add. The second (fifth, eighth, etc.) is the tooltip text. The third is the private tooltip text or '' (for internal use). Usually, set the second and third to the same variable.
See the example on how to add a stock toolbar button.

Parameters:
$widget1 a Gtk2::Widget
$tooltip1 the text to display in the tooltip
$privatetip1
Returns:
none

puniconf::addMenu

puniconf::addMenu ( $menuTitle, $menu )

This method adds a menu to the Plugins Menu. The menus are added as submenus, so please do not try to create a complex heirarchical menu for your plugin.

Parameters:
$menuTitle the title of the menu
$menu a Gtk2::Mwnu
Returns:
none

puniconf::stockTab

$box = puniconf::stockTab ( $label,$iconStr,$ttip )

This method is used to simplify icon creation for the labels in the main NoteBook. This method is very useful when coding the getLabel() method in your plugin. It only works for stock icons.

Parameters:
$label The label text for the tab.
$iconStr The name of a stock icon.
$ttip The ToolTip text to be displayed when the cursor is over the tab.
Returns:
$box A Gtk2::HBox

puniconf::getFileOpen

$filename = puniconf::getFileOpen ( $title )

This method displays a File Selection Dialog and returns the path to the file selected.

Parameters:
$title The title for the File Selection Window.
Returns:
$filename The path to the file selected.

puniconf::getFileSave

$filename = puniconf::getFileSave ( $title )

This method displays a File Save Dialog and returns the path to the file selected.

Parameters:
$title The title for the File Selection Window.
Returns:
$filename The path to the file selected.

puniconf::getFolderOpen

$filename = puniconf::getFolderOpen ( $title )

This method displays a Folder Selection Dialog and returns the path to the folder selected.

Parameters:
$title The title for the File Selection Window.
Returns:
$filename The path to the folder selected.

Plugin->new

sub new {
	my $self = new Gtk2::Widget;
	...
	bless $self;
	return $self;
}	

This method is used to create your plugin. It MUST be a Gtk2::Widget, as it is added as a page to the main Notebook. Set up all UI elements and such here. A good widget to return is a subclass of Gtk2::Container.

Parameters:
none
Returns:
$self a Gtk2::Widget

Plugin->getLabel

sub getLabel{
	my $label = new Gtk2::Label( "My Plugin" );
	return $label;
}

This method is called in order to retrieve the Gtk2::Widget to be displayed in your plugin's tab in the notebook. It must return a Gtk2::Widget.See the example to find out how to add an icon as well.

Parameters:
none
Returns:
$label a Gtk2::Widget

Plugin->setMenu

sub setMenu{
	my ($self)=@_;
	my $plugmnu = Gtk2::Menu->new;
	...
	puniconf::addMenu("Menu Title",$plugmnu);
}

This method is called upon first starting puniconf, It is used to set the menu in the Plugins menu.

Parameters:
none
Returns:
none

Plugin->getToolbarItems

sub getToolbarItems{
	my ($self)=@_;
	my $tooltip='This Button Does Something';
	my $toolbtn=Gtk2::ToolButton->new (...);
		$toolbtn->signal_connect (clicked => sub{...});
	puniconf::addTbItem( $toolbtn, $tooltip, $tooltip );
}

This method is called each time your plugin becomes active (when the user clicks on the tab to show your plugin). It is used to set the items in the toolbar,

Parameters:
none
Returns:
none

Plugin->Open

sub Open{
	my ($self)=@_;
	...
}

This method is called when a user selects Open from the File menu or clicks on the Open toolbar button. If you do not code this method, a warning will be issued. If you do not wish to implement Open(), leave this method empty.

Parameters:
none
Returns:
none

Plugin->Save

sub Save{
	my ($self)=@_;
	...
}

This method is called when a user selects Save from the File menu or clicks on the Save toolbar button. If you do not code this method, a warning will be issued. If you do not wish to implement Save(), leave this method empty.

Parameters:
none
Returns:
none

Plugin->Focus

sub Focus{
	my ($self)=@_;
	...
}

This method is called each time your plugin becomes active (when the user clicks on the tab to show your plugin). You can code extra events here.

Parameters:
none
Returns:
none

Plugin->getIcon

sub getIcon{
	my $icon=puniconf::getWindow->render_icon("gtk-preferences", "menu");
	return $icon;
}

From the Gtk+ API Reference:

"Sets up the icon representing the window. This icon is used when the window is minimized (also known as iconified). Some window managers or desktop environments may also place it in the window frame, or display it in other contexts. The icon should be provided in whatever size it was naturally drawn; that is, don't scale the image before [returning] it. Scaling is postponed until the last minute, when the desired final size is known, to allow best quality."

When your plugin is active, this icon is set to be the default icon.

Parameters:
none
Returns:
$icon a Gtk2::Gdk::Pixbuf

Plugin->getHelp

sub getHelp{
	my ( $self, $buffer )=@_;
	my $iter = $buffer->get_end_iter;
	$buffer->insert_with_tags_by_name ($iter, "My Plugin\n", "helpheading");
}

Parameters:
$buffer the Gtk2::TextBuffer associated with the Help Window
Returns:
none


SourceForge.net Logo Support This Project


This site created, maintained and operated by "Skaman" Sam Tyler, using SaMS content management software. If you like any of the ideas on these pages, feel free to help out, by e-mailing him at SkamanSam@punks.net