Xfce Wiki

Sub domains
 

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
panel_plugins_howto [2007/08/06 18:07] – documentation link 85.25.140.211panel_plugins_howto [2007/12/08 17:56] (current) – removed 88.172.125.130
Line 1: Line 1:
-====== Xfce Panel Plugins How To ====== 
-{{wiki:package.png  }} [[http://foo-projects.org/~nick/packages/xfce4-sample-plugin.tar.bz2|Download]] the external sample plugin. You can also [[http://svn.xfce.org/svn/goodies/xfce4-sample-plugin/trunk/|checkout]] the goodies svn. 
- 
- 
-===== Introduction ===== 
- 
-Starting from version 4.4 the Xfce Panel support two types of plugins: internal and external.  
-The internal plugins are loadable modules, using the  
-[[http://developer.gnome.org/doc/API/2.0/glib/glib-Dynamic-Loading-of-Modules.html|GModule]] 
-interface. External plugins are separate programs that are embedded into the panel using the  
-[[http://developer.gnome.org/doc/API/2.0/gtk/GtkPlug.html|GtkPlug]] and  
-[[http://developer.gnome.org/doc/API/2.0/gtk/GtkSocket.html|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. 
- 
-The API documentation is installed with the panel and also available from  
-http://www.xfce.org/documentation/api/ 
- 
- 
-===== .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 for an external plugin: 
- 
-  [Xfce Panel] 
-  Type=X-XFCE-PanelPlugin 
-  Encoding=UTF-8 
-  _Name=Plugin name 
-  _Comment=Plugin description 
-  Icon=gtk-icon-name 
-  X-XFCE-Exec=<prefix>/libexec/xfce4/panel-plugins/<plugin_name> 
- 
-For the internal plugin you would use: 
- 
-  X-XFCE-Module=<plugin_name> 
-  X-XFCE-Module-Path=<prefix>/lib/xfce4/panel-plugins 
- 
-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 (''gtk'' and ''libxfce4util''): 
- 
-  #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 */ 
-  ... 
- 
-===== 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 [[panel_plugin_debug|here]].