Xfce Wiki

Sub domains
 

Differences

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

Link to this comparison view

Next revision		Previous revision
panel_plugins_howto [2006/12/13 20:41] – created nickpanel_plugins_howto [2007/12/08 17:56] (current) – removed 88.172.125.130
Line 1: Line 1:
-====== Xfce Panel Plugins How To ====== 
-{{wiki:warning.png  }} **This article is not finished yet. It also needs a sample tarball for both internal and external plugins** 
  
-===== 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-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 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. 
- 
-  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. 
- 
-  gchar * 
-  xfce_panel_plugin_lookup_rc_file (XfcePanelPlugin *plugin); 
- 
-  gchar * 
-  xfce_panel_plugin_save_location (XfcePanelPlugin *plugin, 
-                                   gboolean         create);