Xfce Wiki

Sub domains
 
no way to compare when less than two revisions

Differences

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


Previous revision
Next revision
—dev:howto:panel_plugins [2010/04/06 03:40] – old revision restored hashimo
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
 +
 +For instance, 
 +
 +  X-XFCE-Module=quicklauncher
 +  X-XFCE-Module-Path=/usr/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 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 <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 [[:howto/panel_plugin_debug|here]].