Part II. Panel Plugins

Table of Contents

XfcePanelPlugin — Interface for panel plugins
Panel Plugin Register Macros — Register panel plugins that are compiled as modules.
Panel Plugin Register Macros (4.6 Style) — The 4.6 way of registering plugins that compiled as executables
GObject Oriented Panel Plugin Registers Macros — Macros to register panel plugins, written as GObjects.

Register plugins with the panel

Since 4.8 there are various ways to register a plugin with the panel. Which option you choose depends on a couple of things: is the plugin compiled as a module or as an executable and do you want to write a plugin as a GObject.

Internal or external

In 4.6 you had to choose to compile a plugin as an executable to run it external (with the appropriate macro to register external plugins) and the same for internal plugins that were compiled a modules. This worked quite good, but had a couple of disadvantages:

To switch between internal and external you needed to change the build system and registration macros, so this was not very flexible.
When changes were made in the registration macros (esp the ones for external plugins) a plugin had to recompile. Also each plugin copied the same piece of code.
Improvements in the panel communication (D-Bus) and transparant backgrounds where either avoided or hard to implement.

To work around those disadvantages Xfce Panel 4.8 introduced a new way to run plugins that are compiled as modules in a separate process: a plugin wrapper. The plugin wrapper is started by the panel for each external plugin and embeds the plugin module. It provides the communication between the panel and the module using D-Bus and still has the big advantage of the 'old' exectuable external plugin: if it crashes it won't crash the panel.

Whether a plugin is started internal or external is defined by the boolean in the X-XFCE-Internal key in the plugins desktop file. No need to change the macros and the registration macro code can be kept to an absolute minimum.

This does not mean the 4.6 executable plugins are no supported anymore. However if you write a new plugin or you plugin depends on libxfce4panel 4.8, it is recommended to switch to the new registration functions and compile your plugin as a module. To make this move obvious the old macros are all marked as deprecated in this API reference.

GObject plugins

To handle the difference in 4.6 between internal and external plugins, the plugin API contained 3 different types. There were two objects XfceInternalPanelPlugin and XfceExternalPanelPlugin based on a different parents (resp. GtkEventBox and GtkPlug) that both implemented the XfcePanelPlugin interface.

Because internal and external is handled by the wrapper in 4.8, XfcePanelPlugin is now a single object with GtkEventBox as parent. Apart from the fact that this reduced a lot of code in libxfce4panel, it also has the advantage that it is easier to write plugins as GObject with XFCE_TYPE_PANEL_PLUGIN as parent type. This brings a couple of new advantages compared to plugins with register functions:

You can easily cast you plugin to an XfcePanelPlugin, so no need for custom structures. You also get all the GOBject features like type checking.

Downside is that you have to register all other types you create inside you plugin and that it could be a bit difficult (when running internal) with special libraries. To work around the latter you can make you plugin resident.

All the plugins shipped with the panel are written as GObjects, so you can find enough examples in the plugins/ folder.