gecco ----- PLUGIN-HOWTO ------------ 2000/03/30 How to write a plugin for gecco ------------------------------- 1. What is a gecco plugin? 2. What do I need to build a plugin? 3. The gecco plugin API? 4. Plugin example 1. WHAT IS A gecco PLUGIN? --------------------------- To conform to gecco's intent, a gecco plugin is a system administration tool. To become an actual gecco plugin, it must conform to the gecco API. This is a fairly simple interface, requiring the plugin to provide 2 specific functions and make a call to 1 API function. The simplicity of the API allows plugins to be created from scratch, or from an existing application. In the latter case, an existing application needs only to have minor changes made to it, while the bulk of it can usually remain unchanged. 2. WHAT DO I NEED TO BUILD A PLUGIN ------------------------------------ To build a plugin, the following is necessary: -gcc (or another compiler) -make -libtool -install (not manditory, see below) -autoconf, autoheader, automake and aclocal (not manditory, see below) It would be nice to have "install", for installing the plugin, but a copy of 'install-sh' is included with gecco itself. If the skeleton setup of geccoDummy is used (see '4. Plugin Example' below), the GNU tools (autoconf, autoheader, automake and aclocal) should be used. This allows the author to simply edit the 'Makefile.am' and 'acconfig.h' files. These programs are not otherwise needed. 3. THE gecco PLUGIN API? -------------------------------------------------------------- The gecco plugin API is very basic. A plugin need simply to make 2 specific function visible to gecco, and must register itself with gecco. The function "gecco_plugin_init" is sent one of two different signals to direct it's action. The two possible commands are GECCO_PLUGIN_REGISTER, which intends to tell the plugin that this it must register itself with gecco, and GECCO_PLUGIN_CLEANUP, which intends to tell the plugin that it should perform any clean up actions that it needs to. Both commands will occur only once, when the plugin is first being loaded, and when gecco is closing. The function "gecco_plugin_run" must simply start the execution of the plugin. It must use the GtkWidget it is passed as an initial container to hold the plugin display. This must be done using the gtk_container_add() function. This function should return TRUE on success and FALSE on failure. The two functions that must be present in a plugin are: void *gecco_plugin_init ( int ) int gecco_plugin_run ( GtkWidget * ) To register itself (when GECCO_PLUGIN_REGISTER is sent to gecco_plugin_init), the plugin must return the call to gecco_plugin_register. void *gecco_plugin_register ( char *, char *, char *, char **, char *, char **, char **, int ) The arguments sent to gecco_plugin_register are as follows: Name: This argument is of type 'char *'. It is simply a string containing the name of the plugin. example: #define PLUGIN_NAME "geccoPlugin" Version: This argument is also of type 'char *'. It also is simply a string, this time containing the version. example: #define PLUGIN_VERSION 0.4.3 Fullname: This argument is of type 'char *'. It is a string containing the full plugin name. example: #define PLUGIN_FULLNAME PLUGIN_NAME\ " " PLUGIN_VERSION Authors: This argument is of type 'static const char **'. It is a NULL terminated array of strings containing the name(s) of the authors of the plugin. example: static const char *PLUGIN_AUTHOR[] = { "John Vivian",\ NULL }; Description: This argument is of type 'char *'. It is a string describing the plugin. example: #define PLUGIN_DESCRIPTION "A plugin." Buttons: This argument is of type 'static char **'. It is a NULL terminated array of buttons to appear on the main plugin window. If 'NULL' is sent instead of an array, gecco will not create a window for the plugin. This will allow the plugin to perform other functions, such as running another (hopefully configuration) program. example: static char *buttons[] = { GNOME_STOCK_BUTTON_OK, GNOME_STOCK_BUTTON_CANCEL, GNOME_STOCK_BUTTON_HELP, NULL }; Icon(s): This argument is of type 'static char **'. It can be either a hard-coded XPM icon, or a NULL terminated array of filenames to attempt to load. The array of filenames is the most flexible of the two, as more image formats are supported (JPEG, GIF, XPM, PNG). example 1: static char *xpm_icon[] = { "32 32 128 2", .... " " }; example 2: static char *iconlist[] = { "/usr/share/pixmaps/gecco.xpm", "/another/path/image.jpg", NULL }; Need Root: This argument is of type 'int'. It is simply a TRUE/FALSE flag which tells gecco whether the plugin requires root privileged in order to perform it's function(s). example: int needroot = TRUE; The following line is needs to be included in the plugin's 'gecco_plugin_init' function. This will register the plugin with gecco, and pass the return value back to gecco: return ( gecco_plugin_register ( PLUGIN_NAME, PLUGIN_VERSION, PLUGIN_FULLNAME, PLUGIN_AUTHOR, PLUGIN_DESCRIPTION, buttons, xpm_icon, needroot ) ); If the 'buttons' field is set to NULL, no dialog window will be provided to the plugin. As mentioned, this will allow the plugin to create it's own display from scratch, or call an external program. 4. PLUGIN EXAMPLE ------------------ The plugin geccoDummy is an example plugin. It contains all basic source files needed to build a gecco plugin and (hopefully) conform to the GNU build standards. The geccoDummy source package contains a shell script called 'pluginprep.sh' which can be used to create a new plugin. The script will prompt for a few pieces of information about the new plugin and automatically generate a new source tree. The new source tree will have all components necessary to create all supporting pieces (eg. internationalization, documentation, auto* files). There will also be 2 source files in the 'src' directory: 'geccoPLUGINNAME.c' and 'geccoPLUGINNAME.h'. The plugin skeleton uses a structure (defined in 'geccoPLUGINNAME.h') which contains all components of the plugin. This includes the GtkWidget pointer to the plugin's main window, and the tooltips. This structure is used to access the plugin's information and components throughout the program, and is to be passed by reference to all functions which require access to it; in practice, it should not be accessed directly.