You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

8.3 KiB

= Plugin System for Xfce Panel 4.4 =

Starting from version 4.4 the Xfce Panel supports two types of plugins:
* Internal plugins. These are loadable modules, using the gmodule interface.
* External plugins. These are separate programs that are embedded into the
panel using the GtkPlug/GtkSocket mechanism.

In order to handle these plugins the plugin system was entirely rewritten,
along with the rest of the panel framework. This file describes the way plugin
writers should interact with this system.

For the impatient, you can have a look at the plugins provided with the panel
to see how the system is suposed to work.

The API documentation is installed with the panel and also available from
http://www.xfce.org/documentation/api-4.4/


== .desktop file ==

New in version 4.4 is the requirement for a so called .desktop file, that is
'pluginname.desktop', to be installed. It should look like this:

[Xfce Panel]
Name=Plugin
Comment=Plugin to solve all your problems
Icon=fancy-icon
X-XFCE-Exec=/full/path/to/xfce4-fancy-plugin

See the plugins provided with the panel for some tricks for Makefile.am and
to find out how to get translations in the file using intltool.

For an internal plugin you would use 'X-XFCE-Module' with the full path to the
loadable module.

If the module should have no more than 1 instance running at the same time,
you add this line:

X-XFCE-Unique=true


== Library ==

The necessary widgets are provided by libxfce4panel. In your configure.ac you
should add a line like this:

XDT_CHECK_PACKAGE ([LIBXFCE4PANEL], [libxfce4panel-1.0], [4.3.99.2])

The above assumes that you are using the xfce4-dev-tools package, which you
really should, because it makes you life easier. Otherwise, you'd have to
adjust it to include the relevant PKG_CONFIG macro.


== Header File ==

There is only one header file that needs to be included, which will take care
of including other required headers:

#include <libxfce4panel/xfce-panel-plugin.h>


== Plugin Registration ==

To register a plugin with the plugin system there are two macros available
that should be used, instead of using the library functions directly; one for
internal plugins and one for external plugins.

XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL(construct);

XFCE_PANEL_PLUGIN_REGISTER_INTERNAL(construct);

The 'construct' argument is the name of a function that may be cast to
XfcePanelPluginFunc, i.e. it takes a single XfcePanelPlugin pointer as
argument. In the function all widgets should be created and callbacks
connected to the appropriate plugin signals (see below).

example usage:

static void plugin_construct (XfcePanelPlugin *plugin);

XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL (plugin_construct);

/* implement functions */
....

For an internal plugin, only the macro call is different. And of course the
build files.


== Signals ==

There are several signals that plugins may be interested in:

The "orientation-changed" signal
void user_function (XfcePanelPlugin *plugin, GtkOrientation orientation,
gpointer user_data);

The "screen-position-changed" signal
void user_function (XfcePanelPlugin *plugin, XfceScreenPosition *position,
gpointer user_data);

The XfceScreenPosition describes the position of the panel on the screen.
There are 12 positions, 3 on each side, plus two floating positions.

typedef enum
{
XFCE_SCREEN_POSITION_NONE,

/* top */
XFCE_SCREEN_POSITION_NW_H, /* North West Horizontal */
XFCE_SCREEN_POSITION_N, /* North */
XFCE_SCREEN_POSITION_NE_H, /* North East Horizontal */

/* left */
XFCE_SCREEN_POSITION_NW_V, /* North West Vertical */
XFCE_SCREEN_POSITION_W, /* West */
XFCE_SCREEN_POSITION_SW_V, /* South West Vertical */

/* right */
XFCE_SCREEN_POSITION_NE_V, /* North East Vertical */
XFCE_SCREEN_POSITION_E, /* East */
XFCE_SCREEN_POSITION_SE_V, /* South East Vertical */

/* bottom */
XFCE_SCREEN_POSITION_SW_H, /* South West Horizontal */
XFCE_SCREEN_POSITION_S, /* South */
XFCE_SCREEN_POSITION_SE_H, /* South East Horizontal */

/* floating */
XFCE_SCREEN_POSITION_FLOATING_H, /* Floating Horizontal */
XFCE_SCREEN_POSITION_FLOATING_V, /* Floating Vertical */
}
XfceScreenPosition;

Several macros are defined to make it easier to work with screen positions:

xfce_screen_position_is_horizontal(position);

xfce_screen_position_get_orientation(position);

xfce_screen_position_is_floating(position);

xfce_screen_position_is_top(position);

xfce_screen_position_is_left(position);

xfce_screen_position_is_right(position);

xfce_screen_position_is_bottom(position);

The "size-changed" signal (return TRUE when you handle the size change):
gboolean user_function (XfcePanelPlugin *plugin, int size,
gpointer user_data);

The "free-data" signal, free all allocated resources:
void user_function (XfcePanelPlugin *plugin,
gpointer user_data);

The "save" signal, save configuration, may be called more than once:
void user_function (XfcePanelPlugin *plugin,
gpointer user_data);

The "about" signal, emitted when the 'About' menu item is clicked:
void user_function (XfcePanelPlugin *plugin,
gpointer user_data);

To show the menu item the plugin writer should also call:
void xfce_panel_plugin_menu_show_about (XfcePanelPlugin *plugin);

The "configure-plugin" signal, emitted when the 'Configure' menu item is
clicked:
void user_function (XfcePanelPlugin *plugin,
gpointer user_data);

To show the menu item the plugin writer should also call:
void xfce_panel_plugin_menu_show_configure (XfcePanelPlugin *plugin);


== Properties ==

Several functions are available to get more information about the plugin (and
the panel it is part of). Only one property can also be changed, the 'expand'
behavior. The plugin API also provides convenience functions to store and
retrieve a pointer to user data.

/* identification */
G_CONST_RETURN char *
xfce_panel_plugin_get_name (XfcePanelPlugin *plugin);

G_CONST_RETURN char *
xfce_panel_plugin_get_id (XfcePanelPlugin *plugin);

G_CONST_RETURN char *
xfce_panel_plugin_get_display_name (XfcePanelPlugin *plugin);

/* getting properties */
int xfce_panel_plugin_get_size (XfcePanelPlugin *plugin);

XfceScreenPosition
xfce_panel_plugin_get_screen_position (XfcePanelPlugin *plugin);

gboolean xfce_panel_plugin_get_expand (XfcePanelPlugin *plugin);

GtkOrientation xfce_panel_plugin_get_orientation (XfcePanelPlugin *plugin);

/* settings properties */
void xfce_panel_plugin_set_expand (XfcePanelPlugin *plugin,
gboolean expand);


== Menu ==

The plugin has a right-click mouse menu connected to it that allows the user
to show the about or settings dialog, to remove the plugin, or to show the
panel settings dialog. Plugin writers have to make sure all widgets in the
plugin that receive mouse events are connected to the menu by using the
xfce_panel_plugin_add_action_widget() function. A plugin can also add
additional, custom menu items.

void xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin,
GtkWidget *widget);

void xfce_panel_plugin_menu_insert_item (XfcePanelPlugin *plugin,
GtkMenuItem *item);

If you're plugin has a configuration dialog you need to make that menu item
visible and connect to the "configure-plugin" signal. The same for an about
dialog and the "about" signal.

void xfce_panel_plugin_menu_show_about (XfcePanelPlugin *plugin);

void xfce_panel_plugin_menu_show_configure (XfcePanelPlugin *plugin);


== Configuration ==

Plugins can save and retrieve their configuration, using a unique file name.
There's one function for looking up the config file for reading and one for
the file to save.

char *xfce_panel_plugin_lookup_rc_file (XfcePanelPlugin *plugin);

char *xfce_panel_plugin_save_location (XfcePanelPlugin *plugin,
gboolean create);


== Examples ==

Look at the plugins included with the panel for examples on how to use the
plugin interface.