XVI. Module programming guide

This is a brief description of how to program a plugin for GHX 2.

A plugin for GHX 2 is a shared library (.so) dynamically loaded by GHX at the start time (currently, GHX doesn’t allow you to insert or remove a plugin while running).

3 kinds of plugins are available:

  • Replace internal function plugin replaces one of the GHX internal functions.
  • Add command plugin inserts a new button in the command panel. The plugin provides new function using existing GHX internal commands.
  • Mixed mode plugin does the same thing as both previous plugin type. There is only few plugin of this type and they are declared as special Add command plugin.

Replace internal function (RIF) plugin

You can’t replace GHX functions as you want. GHX allows you to replace only few functions:

  • make_error_window is a function displaying all error messages. A default basic error window is always available in GHX but you can program a new one and replace the default window.
  • make_file_info_window is called by the button „??“ of the GHX file browser when to obtain file information. GHX defaultly doesn’t have a file_info_window. This function is provided by a plugin.
  • make_agreement_window is a function called to display agreement messages when you log in a site. This function is now provided by a plugin.

Currently, only these functions can be replaced inside GHX but new ones come in the future.

Sometimes, plugins must more than one entry point. For instance, to replace the agreement window, you must provide not 1 but 3 entry point, read RELATIONS.txt or module.h for more information.

Add command (ANCOC) plugin

you can develop plugin adding a new possibilities to GHX 2 using GHX core. There is nearly no limitation to your imagination.

This is the list of currently available plugins.

  • Postnews allows creation of a message and posts it to the news using GHX transfer core.
  • New User is a site admin plugin allowing creation of accounts on a site.
  • Open/Edit User is also a site admin plugin allowing modification of site accounts.

Soon, the file browser becomes an add command plugin.

Mixed mode plugin

Mixed mode module inserts a button in the command bar and also replace GHX internal functions. The only available plugin is the public chat plugin. If no plugin is inserted to support public chat, GHX discards public chat incoming message. If a plugin is available, a click on the command bar button opens the public chat window and when a public chat message arrives, GHX calls the plugin display function to update the window.

How to create a GHX2 plugin

To develop a plugin for GHX2, you need:

  • A C compiler, gcc or egcs is the best solution I think.
  • GTK 1.0.x or above. Avoid GTK 1.1.x because not every one has it. We use GTK 1.0.1 and 1.0.4 to develop plugins.
  • the plugin toolkit. This is a list of heavily commented C includes describing functions to provide to create a plugin and functions of GHX you can use. The toolkit includes some plugin samples:
    • One RIF plugin, the agreement plugin. This is the original source code of the agreement plugin provided with GHX 2. This is a very simple sample but it describes all functions and moreover is a multiple entry point plugin.
    • One ANCOC plugin, the postnews plugin. A very simple plugin describing how to add a new function in the command bar and how to call
      GHX internal transfer core with no return value.
    • One RIF plugin, the file info plugin. A more complex sample showing how to call GHX internal transfer core and obtains the values returned
      by the core.

Currently, GHX2 doesn’t allow to plug or unplug a module while running so I have not yet program the module_exit function but you must support this for the future.