gaim/gaim
Make this sucker compile again!!
Gaim Perl Plugins are setup very similarly to their C counterparts. Most of the API calls are implemented and are divided into pacakges. There are some significant differences between the Perl and C API. Much like the C API, the best place to seek guidances is the source located in the plugins/perl/common directory. The tutorial that follows will be example based and attempt to touch on the salient features of the embedded perl interpreter. It is also important to note that some of the C API is missing in Gaim's perl API.
It is possible to get Gtk2-Perl to work with Gaim's perl API, however you must not load the module with @c use but with @c require. If you are uninterested in using Gtk with your perl plugins than this still has bearing on you if you would like to use certain perl modules that are dynamically loaded. By always using @c require instead of @c use the problem is avoided.
Let us start with a simple example of a Gaim perl plugin. The following code sample is a complete plugin that can be copied and used as is.
It is necessary to load the Gaim perl package with the line @code use Gaim; @endcode which will make all the Gaim perl API available to the script. The @c \%PLUGIN_INFO has contains all the information that will be displayed in the Plugin frame of the Preferences dialog. In addition to information needed to describe the plugin to the user, information about how the plugin is to be handled is present. The keys @c load and @c unload specify and action to take when the plugin is loaded and when it is unloaded from the Preferences dialog respectively. There are other key values that may be present in the @c \%PLUGIN_INFO hash that will be covered in the following sections.
The Perl subroutine @c plugin_init is executed when the plugin is probed by the plugin subsystem. What this means is as soon as Gaim is started, this subroutine is run once, regardless of whether the plugin is loaded or not. The other two subroutines present are those defined by the @c \%PLUGIN_INFO hash and take the plugin handle as an argument. When the plugin is loaded and subsequently unloaded it will print a message to the debug window using the @c Gaim::debug_info() Gaim perl API call.
The last step is to save the script with a .pl file extention in your ~/.gaim/plugins directory. After restarting gaim the plugin "Perl Test Plugin" should now appear under "Tools -> Preferences -> Plugins". To view the messages make sure you run Gaim from the console with the '-d' flag or open the Debug Window from inside Gaim under "Help". When you enable the checkbox next the plugin you should see a message appear in the Debug Window (or console) and when you disable the checkbox you should see another message appear. You have now created the framework that will allow you to create almost any kind of Gaim plugin you can imagine.
The BuddList, Group and Chat APIs are very similar and whatever is shown for the @c Gaim::BuddlyList API should carry over to @c Gaim::Chat and @c Gaim::Group. Note that there is a @c Gaim::Find pacakge that was created to keep the naming consistent with how these functions are named in the C API.
# In this case the buddies of the account found earlier are retrieved and put in an array '@buddy_array'
# Further down an accessor method is used, 'get_name()' -- see source for details on the full set of methods
The BuddyList API allows for plugins to edit buddies in the list, find the buddies on a given account, set alias, and manipulate the structer as needed. It is also contains the methods for accessing @c Gaim::Group and @c Gaim::Chat types.
The @c Gaim::Connection API is one of the many packages that will not be covered in depth in this tutorial. They are more useful to protocol plugin developers. However, the entire @c gaim_connection_ API has corresponding, functioning perl subroutines.
The plugin preference API allows the plugin to display options in a preference pane that the user can change to manipulate the behaviour of the particular perl plugin. The method used for creating the pane in C does not allow a direct mapping into perl. Therefore perl plugin writers must be aware that there will be significant differences in how they create plugin preference panes.
To first create a standard plugin preference tab we need to add some key/value pairs to the @c \%PLUGIN_INFO hash. The first line contains the perl subroutine that must be provided and will return a @c Gaim::Pref::Frame.
The perl subroutine @c prefs_info_cb will be called to create the tab for the perl plugin in the Preferences dialog. An example of this function will explain the details of creating a preference frame. However, it is necessary to first create the preferences from @c plugin_load as follows.
Using the Gtk2-Perl module for Perl it is possible to create tailored @c GtkFrame elements and display them in a preference window. Note that Gtk2-Perl must be loaded with @c require and not @c use . The first step is to create the proper key/value pairs in the @c \%PLUGIN_INFO hash noting that the @c prefs_info key is no longer valid. Instead the keys @c GTK_UI and @c gtk_prefs_info must be set as follows.
To finish this example @c gtk_prefs_info_cb needs to be defined. To introduce some of the flexibility of using Gtk2-Perl the example also includes a button and a callback for the button. Explaining Gtk2-Perl is beyond the scope of this tutorial and more info can be found at the project's website <a href="http://gtk2-perl.sourceforge.net/">http://gtk2-perl.sourceforge.net/</a>.
The @c Gaim::Request package allows for plugins to have interactive dialog boxes without the need for creating them in Gtk creating a seperation between the user interfaace and the plugin. The portion of the Request API available to perl scripts is listed below followed by an example illustrating their use.
@arg @em cancel_cb - The string name of the perl subroutine to call when the Cancel button is clicked.
@arg @em savedialog - Boolean where true indicates use as a save file dialog and false indicates an open file dialog.
Gaim::Request::input(handle, title, primary, secondary, default_value, multiline, masked, hint, ok_text, ok_cb, cancel_text, cancel_cb);
Gaim::Request::fields(handle, title, primary, secondary, fields, ok_text, ok_cb, cancel_text, cancel_cb);
What follows is an example of a @c Gaim::Request::fields() dialog box with two callbacks for an OK button and a Cancel Button.
# Each fields is created with Gaim::Request::*_new(), is made viewable with Gaim::Request::field_*_set_show_all()
This section of the manual covers some of the more important features that can be added to Gaim perl Plugins. Plugin actions are callback functions that are accessible to the user from the Gaim main window under "Tools -> [Plugin Name]". Timeouts allow a plugin to exectue a perl subroutine after a given period of time. Note that timeouts only occur once, so if the timeout must occur periodically just add a new timeout at the end of the timeout callback function. Callbacks are functions that are called when an event occurs such as a buddy signing-on or a message being received. These three tools will be discussed in the following three examples.
Plugin actions require the @c \%PLUGIN_INFO hash to have a key/value pair added and a callback perl subroutine defined to list the available actions, as well as one callback subroutine for each action. Also, a @c \%plugin_actions hash needs to be defined relating the action names returned by the callback to the appropriate callback subroutines for each action.
Timeouts allow a perl subroutine to be exectued after a specified time. They only occur once, so as stated earlier the timeout must be reregistered after every time it is called.