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
Next revision		Previous revision
dev:howto:panel_plugins [2010/04/05 22:01] – oVxFpcRPloI 217.15.193.7dev:howto:panel_plugins [2024/03/26 18:11] (current) – [Testing and Releasing the plugin] gael
Line 1: Line 1:
-mApe6O  <a href="http://qdtpmubxvzjp.com/">qdtpmubxvzjp</a>, [url=http://lkocnjckxwqh.com/]lkocnjckxwqh[/url], [link=http://lpzsdfjhrkzk.com/]lpzsdfjhrkzk[/link], http://hhpmyfixdhlm.com/+====== Xfce Panel Plugins How To ====== 
 +<note tip>You can find the sample plugin [[https://gitlab.xfce.org/panel-plugins/xfce4-sample-plugin|on GitLab]]. There is also a [[https://gitlab.xfce.org/itsManjeet/xfce4-python-sample-plugin|Python version]].</note> 
 + 
 +===== 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  
 +[[https://developer.gnome.org/glib/stable/glib-Dynamic-Loading-of-Modules.html|GModule]] 
 +interface. External plugins are separate programs that are embedded into the panel using the  
 +[[https://developer.gnome.org/gtk3/stable/GtkPlug.html|GtkPlug]] and  
 +[[https://developer.gnome.org/gtk3/stable/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|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 
 + 
 +If the plugin is compatible with GTK+ 3, you need to add this line: 
 + 
 +  X-XFCE-API=2.0 
 + 
 +===== Library ===== 
 + 
 +The necessary widgets are provided by libxfce4panel. In your configure.ac you should add a 
 +line like this: 
 + 
 +  XDT_CHECK_PACKAGE ([LIBXFCE4PANEL], [libxfce4panel-2.0], [4.12.0]) 
 + 
 +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/libxfce4panel.h> 
 + 
 +===== Plugin Registration ===== 
 + 
 +To register a plugin with the plugin system there is one macro available that should be used, instead of using the library functions directly. 
 +  XFCE_PANEL_PLUGIN_REGISTER(construct); 
 +   
 +Older versions use the following two deprecated macros, 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. 
 + 
 +To help development, you can also test plugins without installing them on panel's prefix (e.g. /usr). As for 4.19.4, you can install the plugin in a directory of XDG_DATA_DIRS or in XDG_HOME_DIR, and the panel should find it. In particular, a default plugin installation in /usr/local with a panel in /usr should work on its own (or a plugin installation in ~/.local without root permissions). 
 + 
 +You can also directly run plugins from the source so you don't need to overwrite a plugin version from your distribution. To accomplish this, build the plugin with make and then follow these steps: 
 + 
 +  * Create a symbolic link from your plugin binary to the panel's prefix installation, e.g. ''ln -s /home/johndoe/where/your/src/is/panel-plugin/.libs/libyourplugin.so /usr/lib/xfce4/panel-plugins/libyourplugin-git.so'' 
 +  * Copy ''/usr/share/xfce4/panel/plugins/yourplugin.desktop'' to ''/usr/share/xfce4/panel/plugins/yourplugin-git.desktop'' 
 +  * Edit the latter to point at 'yourplugin-git' instead of 'yourplugin': modify the ''Name'' entry to distinguish your instance and ''X-XFCE-Module'' to match the symbolic link, i.e. ''yourplugin-git''. 
 +  * If you're porting a plugin to GTK+ 3, make sure to add ''X-XFCE-API=2.0'' to the desktop-git file. 
 + 
 +An example: 
 + 
 +<code> 
 +$cat /usr/share/xfce4/panel/plugins/diskperf-git.desktop 
 +[Xfce Panel] 
 +Type=X-XFCE-PanelPlugin 
 +Encoding=UTF-8 
 +Name=Disk Performance Monitor (git) 
 +Comment=Show disk performance 
 +Icon=drive-harddisk 
 +X-XFCE-Internal=FALSE 
 +X-XFCE-Module=diskperf-git 
 +X-XFCE-API=2.0 
 +</code> 
 + 
 +Now the 'git' version of the panel plugin should be available in the 'add plugin' panel dialog. Whenever you make changes and compile the plugin, all you need to do is to add the plugin to panel again or simply refresh the panel ''xfce4-panel -r''. 
 + 
 +===== Debugging ===== 
 +One can use GDB and Valgrind to debug external plugins, using the technique described [[https://docs.xfce.org/xfce/xfce4-panel/debugging|here]].