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.
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.
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().
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.
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().
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.
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.
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.
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.
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 |
puniconf::clearErr
puniconf::clearErr()
This method clears the Error Window.
puniconf::showErr
puniconf::showErr()
This method displays the Error Window.
puniconf::showStatus
puniconf::showStatus ( $msg )
This method displays a very short status message in the
Status Bar.
Parameters: |
$msg
|
the text to display |
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
|
|
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 |
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.
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.
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.
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,
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.
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.
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.
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.
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 |