Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
dev:howto:panel_plugins [2010/04/05 22:01] – oVxFpcRPloI 217.15.193.7 | dev:howto:panel_plugins [2011/05/16 19:42] – [Xfce Panel Plugins How To] perberos | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | mApe6O | + | ====== Xfce Panel Plugins How To ====== |
+ | {{wiki: | ||
+ | |||
+ | |||
+ | ===== 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/ | ||
+ | interface. External plugins are separate programs that are embedded into the panel using the | ||
+ | [[http:// | ||
+ | [[http://developer.gnome.org/doc/ | ||
+ | |||
+ | 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:// | ||
+ | |||
+ | |||
+ | ===== .desktop file ===== | ||
+ | New in version 4.4 is the requirement for a so called .desktop file, that is '' | ||
+ | to be installed. It should look like this for an external plugin: | ||
+ | |||
+ | | ||
+ | Type=X-XFCE-PanelPlugin | ||
+ | Encoding=UTF-8 | ||
+ | _Name=Plugin name | ||
+ | _Comment=Plugin description | ||
+ | Icon=gtk-icon-name | ||
+ | X-XFCE-Exec=< | ||
+ | |||
+ | For the internal plugin you would use: | ||
+ | |||
+ | X-XFCE-Module=< | ||
+ | X-XFCE-Module-Path=< | ||
+ | |||
+ | For instance, | ||
+ | |||
+ | X-XFCE-Module=quicklauncher | ||
+ | X-XFCE-Module-Path=/ | ||
+ | |||
+ | 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], | ||
+ | |||
+ | 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 ('' | ||
+ | |||
+ | #include < | ||
+ | |||
+ | ===== 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 ' | ||
+ | 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, | ||
+ | | ||
+ | | ||
+ | |||
+ | ==== screen position changed ==== | ||
+ | void | ||
+ | user_function (XfcePanelPlugin | ||
+ | | ||
+ | | ||
+ | |||
+ | 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, | ||
+ | XFCE_SCREEN_POSITION_N, | ||
+ | XFCE_SCREEN_POSITION_NE_H, | ||
+ | |||
+ | /* left */ | ||
+ | XFCE_SCREEN_POSITION_NW_V, | ||
+ | XFCE_SCREEN_POSITION_W, | ||
+ | XFCE_SCREEN_POSITION_SW_V, | ||
+ | |||
+ | /* right */ | ||
+ | XFCE_SCREEN_POSITION_NE_V, | ||
+ | XFCE_SCREEN_POSITION_E, | ||
+ | XFCE_SCREEN_POSITION_SE_V, | ||
+ | |||
+ | /* bottom */ | ||
+ | XFCE_SCREEN_POSITION_SW_H, | ||
+ | XFCE_SCREEN_POSITION_S, | ||
+ | XFCE_SCREEN_POSITION_SE_H, | ||
+ | |||
+ | /* floating */ | ||
+ | XFCE_SCREEN_POSITION_FLOATING_H, | ||
+ | XFCE_SCREEN_POSITION_FLOATING_V, | ||
+ | } | ||
+ | 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, | ||
+ | | ||
+ | | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ==== free data ==== | ||
+ | void | ||
+ | user_function (XfcePanelPlugin *plugin, | ||
+ | | ||
+ | |||
+ | |||
+ | ==== save ==== | ||
+ | void | ||
+ | user_function (XfcePanelPlugin *plugin, | ||
+ | | ||
+ | |||
+ | |||
+ | ==== about ==== | ||
+ | void | ||
+ | user_function (XfcePanelPlugin *plugin, | ||
+ | | ||
+ | |||
+ | 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, | ||
+ | | ||
+ | |||
+ | 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 ' | ||
+ | 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, | ||
+ | | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ===== 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: | ||
+ | is safe when running in [[http://www.xfce.org/documentation/ | ||
+ | |||
+ | void | ||
+ | xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin, | ||
+ | | ||
+ | |||
+ | void | ||
+ | xfce_panel_plugin_menu_insert_item (XfcePanelPlugin *plugin, | ||
+ | GtkMenuItem | ||
+ | |||
+ | If your plugin has a configuration dialog you need to make that menu item | ||
+ | visible and connect to the " | ||
+ | dialog and the " | ||
+ | |||
+ | 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, | ||
+ | There' | ||
+ | the file to save. | ||
+ | |||
+ | gchar * | ||
+ | xfce_panel_plugin_lookup_rc_file (XfcePanelPlugin *plugin); | ||
+ | |||
+ | gchar * | ||
+ | xfce_panel_plugin_save_location (XfcePanelPlugin *plugin, | ||
+ | | ||
+ | |||
+ | |||
+ | |||
+ | ===== Testing and Releasing the plugin ===== | ||
+ | When you test your new plugin, use the '' | ||
+ | |||
+ | For creating a release you need to run '' | ||
+ | |||
+ | ===== Debugging ===== | ||
+ | One can use Valgrind to debug external plugins, using the technique described [[: |