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 [2008/04/18 15:58] – 125.40.123.215 | dev:howto:panel_plugins [2010/04/05 22:01] – oVxFpcRPloI 217.15.193.7 | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Xfce Panel Plugins How To ====== | + | mApe6O |
- | {{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=< | + | |
- | + | ||
- | 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 [[: | + |