Xfce Wiki

Sub domains
 

Differences

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

Link to this comparison view

de:dev:howto:panel_plugins [2008/08/30 02:18]
w3lly translated to german
de:dev:howto:panel_plugins [2010/10/02 17:26]
Line 1: Line 1:
-====== Anleitung für 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=<prefix>/libexec/xfce4/panel-plugins/<plugin_name> 
- 
-Für ein Internes-Plugin würde es wie folgt aussehen: 
- 
-  X-XFCE-Module=<plugin_name> 
-  X-XFCE-Module-Path=<prefix>/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 <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]].