====== Einführung in Xfce Panel Plugins ====== {{wiki:package.png}} Lade Sie ein [[http://foo-projects.org/~nick/packages/xfce4-sample-plugin.tar.bz2|externes Beispiel Plugin]] herunter welches auch über den [[http://svn.xfce.org/svn/goodies/xfce4-sample-plugin/trunk/|Goodies SVN]] ausgecheckt werden kann. ===== Einleitung ===== Seit der Xfce-4.4 Version gibt es zwei Arten von Plugins für das Panel. Einmal sind das die Internen, die als Module geladen werden können die das [[http://developer.gnome.org/doc/API/2.0/glib/glib-Dynamic-Loading-of-Modules.html|GModule Interface]] nutzen und die Externen Plugins die seperate Programme sind und eingebettet werden die den [[http://developer.gnome.org/doc/API/2.0/gtk/GtkPlug.html|GtkPlug]] und [[http://developer.gnome.org/doc/API/2.0/gtk/GtkSocket.html|GtkSocket]] Mechanismus nutzen. Für diese Plugins wurde das Plugin-System komplett mit den restenlichen Panel-Framework neu geschrieben. Diese Seite beschreibt wie Plugin-Entwickler mit diesem System arbeiten. Die API-Dokumentation wurde auch mit dem Panel installiert und ist auch auf der Seite http://www.xfce.org/documentation/api/ zu finden. ===== .desktop Dateien ===== Neu in der Version 4.4 ist die Voraussetzung für sogenannte .desktop Dateien welche als ''pluginname.desktop'' installiert werden. So würde ein Externes-Plugin aussehen: [Xfce Panel] Type=X-XFCE-PanelPlugin Encoding=UTF-8 _Name=Plugin name _Comment=Plugin description Icon=gtk-icon-name X-XFCE-Exec=/libexec/xfce4/panel-plugins/ Für ein Internes-Plugin würde es wie folgt aussehen: X-XFCE-Module= X-XFCE-Module-Path=/lib/xfce4/panel-plugins Wenn das Modul nicht mehr als eine Instanz gleichzeitig laufen hat, fügen Sie diese Zeile hinzu: 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 will make your 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 (''gtk'' and ''libxfce4util''): #include ===== 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 */ ... ===== Signals ===== There are several signals that plugins may be interested in: ==== orientation changed ==== void user_function (XfcePanelPlugin *plugin, GtkOrientation orientation, gpointer user_data); ==== screen position changed ==== 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); ==== size changed ==== This function will return TRUE when you handle the size change gboolean user_function (XfcePanelPlugin *plugin, gint size, gpointer user_data); ==== free data ==== void user_function (XfcePanelPlugin *plugin, gpointer user_data); ==== save ==== void user_function (XfcePanelPlugin *plugin, gpointer user_data); ==== about ==== 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); ==== configure-plugin ==== 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 */ const gchar * xfce_panel_plugin_get_name (XfcePanelPlugin *plugin); const gchar * xfce_panel_plugin_get_id (XfcePanelPlugin *plugin); const gchar * xfce_panel_plugin_get_display_name (XfcePanelPlugin *plugin); /* getting properties */ gint 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. **IMPORTANT:** If your custom menu item allows changes to the plugin, make sure it is safe when running in [[http://www.xfce.org/documentation/api/libxfce4util/libxfce4util-Xfce-Kiosk-functions.html|Kiosk]] mode! void xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin, GtkWidget *widget); void xfce_panel_plugin_menu_insert_item (XfcePanelPlugin *plugin, GtkMenuItem *item); If your 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. gchar * xfce_panel_plugin_lookup_rc_file (XfcePanelPlugin *plugin); gchar * xfce_panel_plugin_save_location (XfcePanelPlugin *plugin, gboolean create); ===== Testing and Releasing the plugin ===== When you test your new plugin, use the ''-Wall -Werror'' CFLAGS (and a recent version of GCC) to detect code problems. Also make sure the plugins is linked (''plugin_name_LDADD'' in Makefile.am) to all the needed libraries, so there will be no problems when building with ''LDFLAGS="-Wl,--as-needed"''. For creating a release you need to run ''./autogen.sh && make distcheck''. Fix all warnings and errors in make distcheck before distributing the package. ===== Debugging ===== One can use Valgrind to debug external plugins, using the technique described [[:howto/panel_plugin_debug|here]].