XfcePanelPlugin

XfcePanelPlugin —

Panel plugin interface.

Synopsis




                    XfcePanelPlugin;
void                (*XfcePanelPluginFunc)              (XfcePanelPlugin *plugin);
gboolean            (*XfcePanelPluginCheck)             (GdkScreen *screen);
gchar*              xfce_panel_plugin_get_name          (XfcePanelPlugin *plugin);
gchar*              xfce_panel_plugin_get_id            (XfcePanelPlugin *plugin);
gchar*              xfce_panel_plugin_get_display_name  (XfcePanelPlugin *plugin);
int                 xfce_panel_plugin_get_size          (XfcePanelPlugin *plugin);
XfceScreenPosition  xfce_panel_plugin_get_screen_position
                                                        (XfcePanelPlugin *plugin);
void                xfce_panel_plugin_set_expand        (XfcePanelPlugin *plugin,
                                                         gboolean expand);
gboolean            xfce_panel_plugin_get_expand        (XfcePanelPlugin *plugin);
GtkOrientation      xfce_panel_plugin_get_orientation   (XfcePanelPlugin *plugin);
void                xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin,
                                                         GtkWidget *widget);
void                xfce_panel_plugin_menu_insert_item  (XfcePanelPlugin *plugin,
                                                         GtkMenuItem *item);
void                xfce_panel_plugin_menu_show_about   (XfcePanelPlugin *plugin);
void                xfce_panel_plugin_menu_show_configure
                                                        (XfcePanelPlugin *plugin);
void                xfce_panel_plugin_block_menu        (XfcePanelPlugin *plugin);
void                xfce_panel_plugin_unblock_menu      (XfcePanelPlugin *plugin);
void                xfce_panel_plugin_register_menu     (XfcePanelPlugin *plugin,
                                                         GtkMenu *menu);
char*               xfce_panel_plugin_lookup_rc_file    (XfcePanelPlugin *plugin);
char*               xfce_panel_plugin_save_location     (XfcePanelPlugin *plugin,
                                                         gboolean create);
void                xfce_panel_plugin_focus_widget      (XfcePanelPlugin *plugin,
                                                         GtkWidget *widget);
void                xfce_panel_plugin_set_panel_hidden  (XfcePanelPlugin *plugin,
                                                         gboolean hidden);

Object Hierarchy


  GInterface
   +----XfcePanelPlugin

Prerequisites

XfcePanelPlugin requires GtkContainer.

Known Implementations

XfcePanelPlugin is implemented by XfceExternalPanelPlugin and XfceInternalPanelPlugin.

Properties


  "display-name"             gchararray            : Read
  "expand"                   gboolean              : Read / Write
  "id"                       gchararray            : Read
  "name"                     gchararray            : Read
  "screen-position"          XfceScreenPosition    : Read
  "size"                     gint                  : Read

Signals


  "about"                                          : Run Last / No Recursion / No Hooks
  "configure-plugin"                               : Run Last / No Recursion / No Hooks
  "free-data"                                      : Run Last / No Recursion / No Hooks
  "orientation-changed"                            : Run Last / No Recursion / No Hooks
  "save"                                           : Run Last / No Recursion / No Hooks
  "screen-position-changed"                        : Run Last / No Recursion / No Hooks
  "size-changed"                                   : Run Last / No Recursion / No Hooks

Description

The interface implemented by both internal and external plugins. Plugin writers may use the functions described below to interact with the plugin widget.

Details

XfcePanelPlugin

typedef struct _XfcePanelPlugin XfcePanelPlugin;

The XfcePanelPlugin is a purely virtual object to describe an instance of a widget implementing the panel plugin interface.


XfcePanelPluginFunc ()

void                (*XfcePanelPluginFunc)              (XfcePanelPlugin *plugin);

Callback function to create the plugin contents. It should be given as the argument to the registration macros.

See also: XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL() and XFCE_PANEL_PLUGIN_REGISTER_INTERNAL()

plugin :

The XfcePanelPlugin

XfcePanelPluginCheck ()

gboolean            (*XfcePanelPluginCheck)             (GdkScreen *screen);

Callback function that is run before creating a plugin. It should return FALSE if the plugin is not available for whatever reason. The function can be given as argument to one of the registration macros.

screen :

the GdkScreen the panel is running on

Returns :

TRUE if the plugin can be started, FALSE otherwise. See also: XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_WITH_CHECK(), XFCE_PANEL_PLUGIN_REGISTER_INTERNAL_WITH_CHECK() and XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_FULL()

xfce_panel_plugin_get_name ()

gchar*              xfce_panel_plugin_get_name          (XfcePanelPlugin *plugin);

The plugin name identifies a plugin type and therefore must be unique.

plugin :

an XfcePanelPlugin

Returns :

the plugin name.

xfce_panel_plugin_get_id ()

gchar*              xfce_panel_plugin_get_id            (XfcePanelPlugin *plugin);

The plugin id is a unique identifier string that is given to every instance of a panel plugin.

plugin :

an XfcePanelPlugin

Returns :

the plugin id.

xfce_panel_plugin_get_display_name ()

gchar*              xfce_panel_plugin_get_display_name  (XfcePanelPlugin *plugin);

The display name is the (translated) plugin name that can be used in a user interface, e.g. a dialog or a menu.

plugin :

an XfcePanelPlugin

Returns :

the display name of plugin.

xfce_panel_plugin_get_size ()

int                 xfce_panel_plugin_get_size          (XfcePanelPlugin *plugin);

plugin :

an XfcePanelPlugin

Returns :

the current panel size.

xfce_panel_plugin_get_screen_position ()

XfceScreenPosition  xfce_panel_plugin_get_screen_position
                                                        (XfcePanelPlugin *plugin);

plugin :

an XfcePanelPlugin

Returns :

the current XfceScreenPosition of the panel.

xfce_panel_plugin_set_expand ()

void                xfce_panel_plugin_set_expand        (XfcePanelPlugin *plugin,
                                                         gboolean expand);

Sets whether to expand the plugin when the width of the panel increases.

plugin :

an XfcePanelPlugin

expand :

whether to expand the plugin

xfce_panel_plugin_get_expand ()

gboolean            xfce_panel_plugin_get_expand        (XfcePanelPlugin *plugin);

plugin :

an XfcePanelPlugin

Returns :

whether the plugin will expand when the panel width increases.

xfce_panel_plugin_get_orientation ()

GtkOrientation      xfce_panel_plugin_get_orientation   (XfcePanelPlugin *plugin);

plugin :

an XfcePanelPlugin

Returns :

the current GtkOrientation of the panel.

xfce_panel_plugin_add_action_widget ()

void                xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin,
                                                         GtkWidget *widget);

Attach the plugin menu to this widget. Plugin writers should call this for every widget that can receive mouse events. If you forget to call this the plugin will not have a right-click menu and the user won't be able to remove it.

plugin :

an XfcePanelPlugin

widget :

a GtkWidget that receives mouse events

xfce_panel_plugin_menu_insert_item ()

void                xfce_panel_plugin_menu_insert_item  (XfcePanelPlugin *plugin,
                                                         GtkMenuItem *item);

Insert custom menu item.

plugin :

an XfcePanelPlugin

item :

the menu item to add

xfce_panel_plugin_menu_show_about ()

void                xfce_panel_plugin_menu_show_about   (XfcePanelPlugin *plugin);

Show the 'About' item in the menu. Clicking on the menu item will emit the "about" signal.

plugin :

an XfcePanelPlugin

xfce_panel_plugin_menu_show_configure ()

void                xfce_panel_plugin_menu_show_configure
                                                        (XfcePanelPlugin *plugin);

Show the 'Configure' item in the menu. Clicking on the menu item will emit the "configure-plugin" signal.

plugin :

an XfcePanelPlugin

xfce_panel_plugin_block_menu ()

void                xfce_panel_plugin_block_menu        (XfcePanelPlugin *plugin);

Temporarily block the menu from being shown. This can be used by plugin writers when the configuration dialog is active.

See also: xfce_panel_plugin_unblock_menu()

plugin :

an XfcePanelPlugin

xfce_panel_plugin_unblock_menu ()

void                xfce_panel_plugin_unblock_menu      (XfcePanelPlugin *plugin);

Don't block the menu from being shown.

See also: xfce_panel_plugin_block_menu()

plugin :

an XfcePanelPlugin

xfce_panel_plugin_register_menu ()

void                xfce_panel_plugin_register_menu     (XfcePanelPlugin *plugin,
                                                         GtkMenu *menu);

Register an open menu. This will make sure the panel will properly handle its autohide behaviour.

plugin :

an XfcePanelPlugin

menu :

a GtkMenu that will be opened

xfce_panel_plugin_lookup_rc_file ()

char*               xfce_panel_plugin_lookup_rc_file    (XfcePanelPlugin *plugin);

Looks up unique filename associated with plugin in standard configuration locations. Uses xfce_resource_lookup() internally.

plugin :

an XfcePanelPlugin

Returns :

path to configuration file or NULL if none was found. The returned string must be freed using g_free(). See also: xfce_panel_plugin_save_location()

xfce_panel_plugin_save_location ()

char*               xfce_panel_plugin_save_location     (XfcePanelPlugin *plugin,
                                                         gboolean create);

Unique file location that can be used to store configuration information. Uses xfce_resource_save_location() internally.

plugin :

an XfcePanelPlugin

create :

whether the file should be created

Returns :

path to configuration file or NULL is the file could not be created. The returned string must be freed using g_free(). See also: xfce_panel_plugin_lookup_rc_file()

xfce_panel_plugin_focus_widget ()

void                xfce_panel_plugin_focus_widget      (XfcePanelPlugin *plugin,
                                                         GtkWidget *widget);

Grab the focus on widget. Asks the panel to allow focus on its items and set the focus to the requested widget.

plugin :

an XfcePanelPlugin

widget :

widget to focus

xfce_panel_plugin_set_panel_hidden ()

void                xfce_panel_plugin_set_panel_hidden  (XfcePanelPlugin *plugin,
                                                         gboolean hidden);

Ask the panel to hide or unhide. This only has effect when autohide is enabled.

plugin :

an XfcePanelPlugin

hidden :

FALSE to unhide, TRUE to hide the panel

Property Details

The "display-name" property

  "display-name"             gchararray            : Read

Translated plugin name. This is the name that can be presented to the user, e.g. in dialogs or menus.

Default value: NULL


The "expand" property

  "expand"                   gboolean              : Read / Write

Whether to expand the plugin when the panel width increases.

Default value: FALSE


The "id" property

  "id"                       gchararray            : Read

Unique identifier string created for every XfcePanelPlugin instance.

Default value: NULL


The "name" property

  "name"                     gchararray            : Read

Untranslated plugin name. This identifies the plugin type and therefore has to be unique.

Default value: NULL


The "screen-position" property

  "screen-position"          XfceScreenPosition    : Read

The current XfceScreenPosition of the panel.

Default value: XFCE_SCREEN_POSITION_S


The "size" property

  "size"                     gint                  : Read

The current panel size.

Allowed values: [10,128]

Default value: 32

Signal Details

The "about" signal

void                user_function                      (XfcePanelPlugin *plugin,
                                                        gpointer         user_data)      : Run Last / No Recursion / No Hooks

Emitted when the 'About' menu item is clicked. Plugin writers should connect to this signal to show information about their plugin (and its authors).

See also: xfce_panel_plugin_menu_show_about()

plugin :

a XfcePanelPlugin widget

user_data :

user data set when the signal handler was connected.

The "configure-plugin" signal

void                user_function                      (XfcePanelPlugin *plugin,
                                                        gpointer         user_data)      : Run Last / No Recursion / No Hooks

Emitted when the 'Configure' menu item is clicked. Plugin writers should connect to this signal to show a settings dialog.

See also: xfce_panel_plugin_menu_show_configure()

plugin :

a XfcePanelPlugin widget

user_data :

user data set when the signal handler was connected.

The "free-data" signal

void                user_function                      (XfcePanelPlugin *plugin,
                                                        gpointer         user_data)      : Run Last / No Recursion / No Hooks

Emitted when the panel is closing. Plugin writers should connect to this signal to free any allocated resources.

See also: XfcePanelPlugin::save

plugin :

a XfcePanelPlugin widget

user_data :

user data set when the signal handler was connected.

The "orientation-changed" signal

void                user_function                      (XfcePanelPlugin *plugin,
                                                        GtkOrientation   orientation,
                                                        gpointer         user_data)        : Run Last / No Recursion / No Hooks

Emitted when the panel orientation changes.

plugin :

a XfcePanelPlugin widget

orientation :

new GtkOrientation of the panel

user_data :

user data set when the signal handler was connected.

The "save" signal

void                user_function                      (XfcePanelPlugin *plugin,
                                                        gpointer         user_data)      : Run Last / No Recursion / No Hooks

Emitted before the panel is closing. May be called more than once while the panel is running. Plugin writers should connect to this signal to save the plugins configuration.

See also: xfce_panel_plugin_get_rc_file()

plugin :

a XfcePanelPlugin widget

user_data :

user data set when the signal handler was connected.

The "screen-position-changed" signal

void                user_function                      (XfcePanelPlugin   *plugin,
                                                        XfceScreenPosition position,
                                                        gpointer           user_data)      : Run Last / No Recursion / No Hooks

Emitted when the screen position changes. Most plugins will be more interested in the "orientation-changed" signal.

plugin :

a XfcePanelPlugin widget

position :

new XfceScreenPosition of the panel

user_data :

user data set when the signal handler was connected.

The "size-changed" signal

gboolean            user_function                      (XfcePanelPlugin *plugin,
                                                        gint             size,
                                                        gpointer         user_data)      : Run Last / No Recursion / No Hooks

Emitted when the panel size changes. By default a plugin will get a geometry of size x size. This means that a plugin writer must handle this signal for any other behavior, even to 'do nothing'.

plugin :

a XfcePanelPlugin widget

size :

new panel size

user_data :

user data set when the signal handler was connected.

Returns :

A callback function should return TRUE when the signal is handled and FALSE otherwise, in which case the default handler will run.

See Also

Writing Plugins