## XfcePanelPlugin XfcePanelPlugin — Interface for panel plugins |

## Synopsis

    #include <libxfce4panel/libxfce4panel.h>

                        XfcePanelPlugin;
    struct              XfcePanelPluginClass;
    const gchar *       xfce_panel_plugin_get_name          (XfcePanelPlugin *plugin);
    const gchar *       xfce_panel_plugin_get_display_name  (XfcePanelPlugin *plugin);
    const gchar *       xfce_panel_plugin_get_comment       (XfcePanelPlugin *plugin);
    gint                xfce_panel_plugin_get_unique_id     (XfcePanelPlugin *plugin);
    const gchar *       xfce_panel_plugin_get_property_base (XfcePanelPlugin *plugin);
    const gchar * const  * xfce_panel_plugin_get_arguments  (XfcePanelPlugin *plugin);
    gint                xfce_panel_plugin_get_size          (XfcePanelPlugin *plugin);
    gboolean            xfce_panel_plugin_get_expand        (XfcePanelPlugin *plugin);
    void                xfce_panel_plugin_set_expand        (XfcePanelPlugin *plugin,
                                                             gboolean expand);
    GtkOrientation      xfce_panel_plugin_get_orientation   (XfcePanelPlugin *plugin);
    XfceScreenPosition  xfce_panel_plugin_get_screen_position
                                                            (XfcePanelPlugin *plugin);
    gboolean            xfce_panel_plugin_get_locked        (XfcePanelPlugin *plugin);
    void                xfce_panel_plugin_take_window       (XfcePanelPlugin *plugin,
                                                             GtkWindow *window);
    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_configure
                                                            (XfcePanelPlugin *plugin);
    void                xfce_panel_plugin_menu_show_about   (XfcePanelPlugin *plugin);
    void                xfce_panel_plugin_remove            (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);
    GtkArrowType        xfce_panel_plugin_arrow_type        (XfcePanelPlugin *plugin);
    void                xfce_panel_plugin_position_widget   (XfcePanelPlugin *plugin,
                                                             GtkWidget *menu_widget,
                                                             GtkWidget *attach_widget,
                                                             gint *x,
                                                             gint *y);
    void                xfce_panel_plugin_position_menu     (GtkMenu *menu,
                                                             gint *x,
                                                             gint *y,
                                                             gboolean *push_in,
                                                             gpointer panel_plugin);
    void                xfce_panel_plugin_focus_widget      (XfcePanelPlugin *plugin,
                                                             GtkWidget *widget);
    void                xfce_panel_plugin_block_autohide    (XfcePanelPlugin *plugin,
                                                             gboolean blocked);
    gchar *             xfce_panel_plugin_lookup_rc_file    (XfcePanelPlugin *plugin);
    gchar *             xfce_panel_plugin_save_location     (XfcePanelPlugin *plugin,
                                                             gboolean create);
    #define             xfce_panel_plugin_xfconf_channel_new(plugin)
    #define             xfce_panel_plugin_set_panel_hidden  (plugin,
                                                             hidden)

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBin
                                     +----GtkEventBox
                                           +----XfcePanelPlugin

## Implemented Interfaces

XfcePanelPlugin implements AtkImplementorIface, GtkBuildable and XfcePanelPluginProvider.

## Properties

      "arguments"                GStrv                 : Read / Write / Construct Only
      "comment"                  gchar*                : Read / Write / Construct Only
      "display-name"             gchar*                : Read / Write / Construct Only
      "expand"                   gboolean              : Read / Write
      "mode"                     XfcePanelPluginMode   : Read
      "name"                     gchar*                : Read / Write / Construct Only
      "nrows"                    guint                 : Read
      "orientation"              GtkOrientation        : Read
      "screen-position"          XfceScreenPosition    : Read
      "shrink"                   gboolean              : Read / Write
      "size"                     gint                  : Read
      "small"                    gboolean              : Read / Write
      "unique-id"                gint                  : Read / Write / Construct Only

## Signals

      "about"                                          : Run Last
      "configure-plugin"                               : Run Last
      "free-data"                                      : Run Last
      "mode-changed"                                   : Run Last
      "nrows-changed"                                  : Run Last
      "orientation-changed"                            : Run Last
      "remote-event"                                   : Run Last
      "removed"                                        : Run Last
      "save"                                           : Run Last
      "screen-position-changed"                        : Run Last
      "size-changed"                                   : Run Last

## Description

The interface plugin developers used to interact with the plugin and the panel.

## Details

### XfcePanelPlugin

    typedef struct _XfcePanelPlugin XfcePanelPlugin;

This struct contain private data only and should be accessed by the functions below.

### struct XfcePanelPluginClass

    struct XfcePanelPluginClass {
      /* for object oriented plugins only */
      void     (*construct)               (XfcePanelPlugin    *plugin);

      /* signals */
      void     (*screen_position_changed) (XfcePanelPlugin    *plugin,
                                           XfceScreenPosition  position);
      gboolean (*size_changed)            (XfcePanelPlugin    *plugin,
                                           gint                size);
      void     (*orientation_changed)     (XfcePanelPlugin    *plugin,
                                           GtkOrientation      orientation);
      void     (*free_data)               (XfcePanelPlugin    *plugin);
      void     (*save)                    (XfcePanelPlugin    *plugin);
      void     (*about)                   (XfcePanelPlugin    *plugin);
      void     (*configure_plugin)        (XfcePanelPlugin    *plugin);
      void     (*removed)                 (XfcePanelPlugin    *plugin);
      gboolean (*remote_event)            (XfcePanelPlugin    *plugin,
                                           const gchar        *name,
                                           const GValue       *value);

      /* new in 4.10 */
      void     (*mode_changed)            (XfcePanelPlugin    *plugin,
                                           XfcePanelPluginMode mode);
      void     (*nrows_changed)           (XfcePanelPlugin    *plugin,
                                           guint               rows);
    };

Class of an XfcePanelPlugin. The interface can be used to create GObject based plugin.

`construct` () | This function is for object orientated plugins and triggered after the init function of the object. When this function is triggered, the plugin information like name, display name, comment and unique id are available. This is also the place where you would call functions like `xfce_panel_plugin_menu_show_configure()`. You can see this as the replacement of XfcePanelPluginFunc for object based plugins. Since 4.8.
`screen_position_changed` () | See "screen-position-changed" for more information.
`size_changed` () | See "size-changed" for more information.
`orientation_changed` () | See "orientation-changed" for more information.
`free_data` () | See "free-data" for more information.
`save` () | See "save" for more information.
`about` () | See "about" for more information.
`configure_plugin` () | See "configure-plugin" for more information.
`removed` () | See "removed" for more information.
`remote_event` () | See "remote-event" for more information.
`mode_changed` () |
`nrows_changed` () |

### xfce_panel_plugin_get_name ()

    const gchar *       xfce_panel_plugin_get_name          (XfcePanelPlugin *plugin);

The internal name of the panel plugin.

`plugin` : | an XfcePanelPlugin.
Returns : | the name of the panel plugin.

### xfce_panel_plugin_get_display_name ()

    const gchar *       xfce_panel_plugin_get_display_name  (XfcePanelPlugin *plugin);

This returns the translated name of the plugin set in the .desktop file of the plugin.

`plugin` : | an XfcePanelPlugin.
Returns : | the (translated) display name of the plugin.

### xfce_panel_plugin_get_comment ()

    const gchar *       xfce_panel_plugin_get_comment       (XfcePanelPlugin *plugin);

This returns the translated comment of the plugin set in the .desktop file of the plugin.

`plugin` : | an XfcePanelPlugin.
Returns : | the (translated) comment of the plugin.

Since 4.8

### xfce_panel_plugin_get_unique_id ()

    gint                xfce_panel_plugin_get_unique_id     (XfcePanelPlugin *plugin);

The internal unique id of the plugin. Each plugin in the panel has a unique number that is for example used for the config file name or property base in the xfconf channel.

`plugin` : | an XfcePanelPlugin.
Returns : | the unique id of the plugin. Since 4.8

### xfce_panel_plugin_get_property_base ()

    const gchar *       xfce_panel_plugin_get_property_base (XfcePanelPlugin *plugin);

The property base for this plugin in the xfce4-panel XfconfChannel, this name is something like /plugins/plugin-1.

`plugin` : | an XfcePanelPlugin.
Returns : | the property base for the xfconf channel userd by a plugin. See also: xfconf_channel_new_with_property_base. XFCE_PANEL_PLUGIN_CHANNEL_NAME and xfce_panel_get_channel_name

### xfce_panel_plugin_get_arguments ()

    const gchar * const  * xfce_panel_plugin_get_arguments  (XfcePanelPlugin *plugin);

Argument vector passed to the plugin when it was added. Most of the time the return value will be `NULL`, but if could for example contain a list of filenames when the user added the plugin with

xfce4-panel --add=launcher *.desktop

see the code of the launcher plugin how to use this.

`plugin` : | an XfcePanelPlugin.
Returns : | the argument vector. The vector is owned by the plugin and should not be freed.

Since 4.8

### xfce_panel_plugin_get_size ()

    gint                xfce_panel_plugin_get_size          (XfcePanelPlugin *plugin);

The size of the panel in which the plugin is embedded.

`plugin` : | an XfcePanelPlugin.
Returns : | the current size of the panel.

### xfce_panel_plugin_get_expand ()

    gboolean            xfce_panel_plugin_get_expand        (XfcePanelPlugin *plugin);

Whether the plugin is expanded or not. This set by the plugin using `xfce_panel_plugin_set_expand()`.

`plugin` : | an XfcePanelPlugin.
Returns : | `TRUE` when the plugin should expand, `FALSE` otherwise.

### xfce_panel_plugin_set_expand ()

    void                xfce_panel_plugin_set_expand        (XfcePanelPlugin *plugin,
                                                             gboolean expand);

Wether the plugin should expand of not

`plugin` : | an XfcePanelPlugin.
`expand` : | whether to expand the plugin.

### xfce_panel_plugin_get_orientation ()

    GtkOrientation      xfce_panel_plugin_get_orientation   (XfcePanelPlugin *plugin);

The orientation of the panel in which the plugin is embedded.

`plugin` : | an XfcePanelPlugin.
Returns : | the current GtkOrientation of the panel.

### xfce_panel_plugin_get_screen_position ()

    XfceScreenPosition  xfce_panel_plugin_get_screen_position
                                                            (XfcePanelPlugin *plugin);

The screen position of the panel in which the plugin is embedded.

`plugin` : | an XfcePanelPlugin.
Returns : | the current XfceScreenPosition of the panel.

### xfce_panel_plugin_get_locked ()

    gboolean            xfce_panel_plugin_get_locked        (XfcePanelPlugin *plugin);

Whether the plugin is locked (not allowing customization). This is emitted through the panel based on the Xfconf locking of the panel window the plugin is embedded on.

It is however possible to send a fake signal to the plugin to override this propery, so you should only use this for interface elements and (if you use Xfconf) check the locking yourself before you write any values or query the kiosk mode using the api in libxfce4util.

`plugin` : | an XfcePanelPlugin.
Returns : | `TRUE` if the user is not allowed to modify the plugin, `FALSE` is customization is allowed.

Since 4.8

### xfce_panel_plugin_take_window ()

    void                xfce_panel_plugin_take_window       (XfcePanelPlugin *plugin,
                                                             GtkWindow *window);

Connect a dialog to a plugin. When the `plugin` is closed, it will destroy the `window`.

`plugin` : | an XfcePanelPlugin.
`window` : | a GtkWindow.

Since 4.8

### 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 a custom menu item to the plugin's right click menu. This item is packed below the "Move" menu item.

`plugin` : | an XfcePanelPlugin.
`item` : | a GtkMenuItem.

### xfce_panel_plugin_menu_show_configure ()

    void                xfce_panel_plugin_menu_show_configure
                                                            (XfcePanelPlugin *plugin);

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

`plugin` : | an XfcePanelPlugin.

### 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_remove ()

    void                xfce_panel_plugin_remove            (XfcePanelPlugin *plugin);

Remove this plugin from the panel and remove all its configuration.

Plugins should not use this function to implement their own menu item or button to remove theirselfs from the panel, but only in case the there are problems with the plugin in the panel. Always try to inform the user why this occured.

`plugin` : | an XfcePanelPlugin.

Since 4.8

### xfce_panel_plugin_block_menu ()

    void                xfce_panel_plugin_block_menu        (XfcePanelPlugin *plugin);

Block configuring the plugin. This will make the "Properties" menu item insensitive.

`plugin` : | an XfcePanelPlugin.

### xfce_panel_plugin_unblock_menu ()

    void                xfce_panel_plugin_unblock_menu      (XfcePanelPlugin *plugin);

Unblock configuring the plugin. This will make the "Properties" menu item sensitive.

`plugin` : | an XfcePanelPlugin.

### xfce_panel_plugin_register_menu ()

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

Register a menu that is about to popup. This will make sure the panel will properly handle its autohide behaviour. You have to call this function every time the menu is opened (e.g. using `gtk_popup_menu()`).

If you want to open the menu aligned to the side of the panel (and the plugin), you should use `xfce_panel_plugin_position_menu()` as GtkMenuPositionFunc. This callback function will take care of calling `xfce_panel_plugin_register_menu()` as well.

See also: `xfce_panel_plugin_position_menu()` and `xfce_panel_plugin_block_autohide()`.

`plugin` : | an XfcePanelPlugin.
`menu` : | a GtkMenu that will be opened

### xfce_panel_plugin_arrow_type ()

    GtkArrowType        xfce_panel_plugin_arrow_type        (XfcePanelPlugin *plugin);

Determine the GtkArrowType for a widget that opens a menu and uses `xfce_panel_plugin_position_menu()` to position the menu.

`plugin` : | an XfcePanelPlugin.
Returns : | the GtkArrowType to use.

### xfce_panel_plugin_position_widget ()

    void                xfce_panel_plugin_position_widget   (XfcePanelPlugin *plugin,
                                                             GtkWidget *menu_widget,
                                                             GtkWidget *attach_widget,
                                                             gint *x,
                                                             gint *y);

The menu widget is positioned relative to `attach_widget`. If `attach_widget` is NULL, the menu widget is instead positioned relative to `panel_plugin`.

This function is intended for custom menu widgets. For a regular GtkMenu you should use `xfce_panel_plugin_position_menu()` instead (as callback argument to `gtk_menu_popup()`).

See also: `xfce_panel_plugin_position_menu()`.

`plugin` : | an XfcePanelPlugin.
`menu_widget` : | a GtkWidget that will be used as popup menu.
`attach_widget` : | a GtkWidget relative to which the menu should be positioned.
`x` : | return location for the x coordinate.
`y` : | return location for the x coordinate.

### xfce_panel_plugin_position_menu ()

    void                xfce_panel_plugin_position_menu     (GtkMenu *menu,
                                                             gint *x,
                                                             gint *y,
                                                             gboolean *push_in,
                                                             gpointer panel_plugin);

Function to be used as GtkMenuPositionFunc in a call to `gtk_menu_popup()`. As data argument it needs an XfcePanelPlugin.

The menu is normally positioned relative to `panel_plugin`. If you want the menu to be positioned relative to another widget, you can use `gtk_menu_attach_to_widget()` to explicitly set a 'parent' widget.

As a convenience, `xfce_panel_plugin_position_menu()` calls `xfce_panel_plugin_register_menu()` for the menu.

Example 2.

void myplugin_popup_menu (XfcePanelPlugin *plugin, GtkMenu *menu, GdkEventButton *ev) { gtk_menu_popup (menu, NULL, NULL, xfce_panel_plugin_position_menu, plugin, ev->button, ev->time ); }

For a custom widget that will be used as a popup menu, use `xfce_panel_plugin_position_widget()` instead.

See also: `gtk_menu_popup()`.

`menu` : | a GtkMenu.
`x` : | return location for the x coordinate.
`y` : | return location for the y coordinate.
`push_in` : | keep inside the screen (see GtkMenuPositionFunc)
`panel_plugin` : | an XfcePanelPlugin.

### 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` : | a GtkWidget inside the plugins that should be focussed.

### xfce_panel_plugin_block_autohide ()

    void                xfce_panel_plugin_block_autohide    (XfcePanelPlugin *plugin,
                                                             gboolean blocked);

Wether this plugin blocks the autohide functality of the panel. Use this when you 'popup' something that is visually attached to the plugin at it will look weird for a user if the panel will hide while he/she is working in the popup.

For menus it there is `xfce_panel_plugin_register_menu()` which will take care of this.

`plugin` : | an XfcePanelPlugin.
`blocked` : | new blocking state of this plugin.

### xfce_panel_plugin_lookup_rc_file ()

    gchar *             xfce_panel_plugin_lookup_rc_file    (XfcePanelPlugin *plugin);

Looks for the plugin resource file. This should be used to get the plugin read location of the config file. You should only use the returned path to read information from, since it might point to a not-writable file (in kiosk mode for example).

See also: `xfce_panel_plugin_save_location()` and `xfce_resource_lookup()`

`plugin` : | an XfcePanelPlugin.
Returns : | The path to a config file or `NULL` if no file was found. The returned string must be freed using `g_free()`

### xfce_panel_plugin_save_location ()

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

Returns the path that can be used to store configuration information. Don't use this function if you want to read from the config file, but use `xfce_panel_plugin_lookup_rc_file()` instead.

See also: `xfce_panel_plugin_lookup_rc_file()` and `xfce_resource_save_location()`

`plugin` : | an XfcePanelPlugin.
`create` : | whether to create missing directories.
Returns : | The path to a config file or `NULL` if no file was found. The returned string must be freed u sing `g_free()`.

### xfce_panel_plugin_xfconf_channel_new()

    #define             xfce_panel_plugin_xfconf_channel_new(plugin)

Convienient function for opening an XfconfChannel for a plugin. The channel's property base will be propery returned from `xfce_panel_plugin_get_property_base()`.

See also: xfce_panel_plugin_get_property_base, XFCE_PANEL_PLUGIN_CHANNEL_NAME and xfce_panel_get_channel_name

`plugin` : | An XfcePanelPlugin.

Since 4.8

### xfce_panel_plugin_set_panel_hidden()

    #define             xfce_panel_plugin_set_panel_hidden(plugin, hidden)

### Warning

`xfce_panel_plugin_set_panel_hidden` has been deprecated since version 4.8 and should not be used in newly-written code. Use `xfce_panel_plugin_block_autohide()` instead.

See `xfce_panel_plugin_block_autohide()` for more information.

`plugin` : | an XfcePanelPlugin.
`hidden` : | new blocking state of this plugin.

## Property Details

### The `"arguments"` property

      "arguments"                GStrv                 : Read / Write / Construct Only

The arguments the plugin was started with. If the plugin was not started with any arguments this value is `NULL`. Plugin writer can use it to read the arguments array, but `xfce_panel_plugin_get_arguments()` is recommended.

### The `"comment"` property

      "comment"                  gchar*                : Read / Write / Construct Only

The translated description of the XfcePanelPlugin. This property is set during plugin construction and can't be set twice. Plugin writer can use it to read the plugin description, but `xfce_panel_plugin_get_comment()` is recommended.

Default value: NULL

Since 4.8

### The `"display-name"` property

      "display-name"             gchar*                : Read / Write / Construct Only

The translated display name of the XfcePanelPlugin. This property is set during plugin construction and can't be set twice. Plugin writer can use it to read the plugin display name, but `xfce_panel_plugin_get_display_name()` is recommended.

Default value: NULL

### The `"expand"` property

      "expand"                   gboolean              : Read / Write

Wether the XfcePanelPlugin expands on the panel. Plugin writes can use it to read or set this property, but `xfce_panel_plugin_set_expand()` is recommended.

Default value: FALSE

### The `"mode"` property

      "mode"                     XfcePanelPluginMode   : Read

Display mode of the plugin.

Default value: XFCE_PANEL_PLUGIN_MODE_HORIZONTAL

Since 4.10

### The `"name"` property

      "name"                     gchar*                : Read / Write / Construct Only

The internal, unstranslated, name of the XfcePanelPlugin. Plugin writer can use it to read the plugin name, but `xfce_panel_plugin_get_name()` is recommended since that returns a const string.

Default value: NULL

### The `"nrows"` property

      "nrows"                    guint                 : Read

Number of rows the plugin is embedded on.

Allowed values: [1,6]

Default value: 1

Since 4.10

### The `"orientation"` property

      "orientation"              GtkOrientation        : Read

The GtkOrientation of the XfcePanelPlugin. Plugin writer can use it to read the plugin orientation, but `xfce_panel_plugin_get_orientation()` is recommended.

Default value: GTK_ORIENTATION_HORIZONTAL

### The `"screen-position"` property

      "screen-position"          XfceScreenPosition    : Read

The XfceScreenPosition of the XfcePanelPlugin. Plugin writer can use it to read the plugin's screen position, but `xfce_panel_plugin_get_screen_psotion()` is recommended.

Default value: XFCE_SCREEN_POSITION_NONE

### The `"shrink"` property

      "shrink"                   gboolean              : Read / Write

Wether the XfcePanelPlugin can shrink when there is no space left on the panel. Plugin writes can use it to read or set this property, but `xfce_panel_plugin_set_shrink()` is recommended.

Default value: FALSE

Since 4.10

### The `"size"` property

      "size"                     gint                  : Read

The size in pixels of the XfcePanelPlugin. Plugin writer can use it to read the plugin size, but `xfce_panel_plugin_get_size()` is recommended.

Allowed values: [0,768]

Default value: 0

### The `"small"` property

      "small"                    gboolean              : Read / Write

Wether the XfcePanelPlugin is small enough to fit a single row of a multi-row panel. Plugin writes can use it to read or set this property, but `xfce_panel_plugin_set_small()` is recommended.

Default value: FALSE

Since 4.10

### The `"unique-id"` property

      "unique-id"                gint                  : Read / Write / Construct Only

Unique plugin ID.

Allowed values: >= G_MAXULONG

Default value: -1

## Signal Details

### The `"about"` signal

    void                user_function                      (XfcePanelPlugin *plugin,
                                                            gpointer         user_data)      : Run Last

This signal is emmitted when the About entry in the right-click menu is clicked. Plugin writes can use it to show information about the plugin and display credits of the developers, translators and other contributors.

See also: `xfce_panel_plugin_menu_show_about()`.

`plugin` : | an XfcePanelPlugin.
`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

This signal is emmitted when the Properties entry in the right-click menu is clicked. Plugin writes can use this signal to open a plugin settings dialog.

See also: `xfce_panel_plugin_menu_show_configure()` and `xfce_titled_dialog_new()`.

`plugin` : | an XfcePanelPlugin.
`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

This signal is emmitted when the plugin is closing. Plugin writers should use this signal to free any allocated resources.

See also XfceHVBox.

`plugin` : | an XfcePanelPlugin.
`user_data` : | user data set when the signal handler was connected.

### The `"mode-changed"` signal

    void                user_function                      (XfcePanelPlugin    *plugin,
                                                            XfcePanelPluginMode mode,
                                                            gpointer            user_data)      : Run Last

This signal is emmitted whenever the mode of the panel the `plugin` is on changes.

`plugin` : | an XfcePanelPlugin.
`mode` : | new XfcePanelPluginMode of the panel.
`user_data` : | user data set when the signal handler was connected.

Since 4.10

### The `"nrows-changed"` signal

    void                user_function                      (XfcePanelPlugin *plugin,
                                                            guint            rows,
                                                            gpointer         user_data)      : Run Last

This signal is emmitted whenever the nrows of the panel the `plugin` is on changes.

`plugin` : | an XfcePanelPlugin.
`rows` : | new number of rows of the panel
`user_data` : | user data set when the signal handler was connected.

Since 4.10

### The `"orientation-changed"` signal

    void                user_function                      (XfcePanelPlugin *plugin,
                                                            GtkOrientation   orientation,
                                                            gpointer         user_data)        : Run Last

This signal is emmitted whenever the orientation of the panel the `plugin` is on changes. Plugins writers can for example use this signal to change the order of widgets in the plugin.

See also: XfceHVBox.

`plugin` : | an XfcePanelPlugin.
`orientation` : | new GtkOrientation of the panel.
`user_data` : | user data set when the signal handler was connected.

### The `"remote-event"` signal

    gboolean            user_function                      (XfcePanelPlugin *plugin,
                                                            gchar           *name,
                                                            GValue          *value,
                                                            gpointer         user_data)      : Run Last

This signal is emmitted by the user by running xfce4-panel --plugin-event=plugin-name:name:type:value. It can be used for remote communication, like for example to popup a menu.

`plugin` : | an XfcePanelPlugin.
`name` : | name of the signal.
`value` : | value of the signal.
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` to stop signal emission to other plugins, `FALSE` to send the signal also to other plugins with the same name.

### The `"removed"` signal

    void                user_function                      (XfcePanelPlugin *plugin,
                                                            gpointer         user_data)      : Run Last

This signal is emmitted when the plugin is permanently removed from the panel configuration by the user. Developers can use this signal to cleanup custom setting locations that for example store passwords.

The free-data signal is emitted after this signal!

Note that if you use the xfconf channel and base property provided by `xfce_panel_plugin_get_property_base()` or the rc file location returned by `xfce_panel_plugin_save_location()`, the panel will take care of removing those settings.

`plugin` : | an XfcePanelPlugin.
`user_data` : | user data set when the signal handler was connected.

Since 4.8

### The `"save"` signal

    void                user_function                      (XfcePanelPlugin *plugin,
                                                            gpointer         user_data)      : Run Last

This signal is emitted when the plugin should save it's configuration. The signal is always emmitted before the plugin closes (before the "free-data" signal) and also once in 10 minutes or so.

See also: `xfce_panel_plugin_save_location()`.

`plugin` : | an XfcePanelPlugin.
`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

This signal is emmitted whenever the screen position of the panel the `plugin` is on changes. Plugins writers can for example use this signal to change the arrow direction of buttons.

`plugin` : | an XfcePanelPlugin.
`position` : | the 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

This signal is emmitted whenever the size of the panel the `plugin` is on changes. Plugins writers can for example use this signal to update their icon size.

If the function returns `FALSE` or is not used, the panel will force a square size to the plugin. If you want non-square plugins and you don't need this signal you can use something like this:

g_signal_connect (plugin, "size-changed", G_CALLBACK (gtk_true), NULL);

`plugin` : | an XfcePanelPlugin.
`size` : | the new size of the panel.
`user_data` : | user data set when the signal handler was connected.