## Panel Applet

Panel Applet — a widget embedded in a panel.

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <panel-applet.h>

    struct              PanelApplet;
    enum                PanelAppletOrient;
    enum                PanelAppletFlags;
    PanelAppletOrient   panel_applet_get_orient             (PanelApplet *applet);
    guint               panel_applet_get_size               (PanelApplet *applet);
    void                panel_applet_set_size_hints         (PanelApplet *applet,
                                                             const int *size_hints,
                                                             int n_elements,
                                                             int base_size);
    cairo_pattern_t *   panel_applet_get_background         (PanelApplet *applet);
    void                panel_applet_set_background_widget  (PanelApplet *applet,
                                                             GtkWidget *widget);
    PanelAppletFlags    panel_applet_get_flags              (PanelApplet *applet);
    void                panel_applet_set_flags              (PanelApplet *applet,
                                                             PanelAppletFlags flags);
    gboolean            panel_applet_get_locked_down        (PanelApplet *applet);
    void                panel_applet_add_preferences        (PanelApplet *applet,
                                                             const gchar *schema_dir,
                                                             GError **error);
    gchar *             panel_applet_get_preferences_key    (PanelApplet *applet);
    void                panel_applet_request_focus          (PanelApplet *applet,
                                                             guint32 timestamp);
    void                panel_applet_setup_menu             (PanelApplet *applet,
                                                             const gchar *xml,
                                                             GtkActionGroup *action_group);
    void                panel_applet_setup_menu_from_file   (PanelApplet *applet,
                                                             const gchar *filename,
                                                             GtkActionGroup *action_group);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBin
                               +----GtkEventBox
                                     +----PanelApplet

## Implemented Interfaces

PanelApplet implements AtkImplementorIface and GtkBuildable.

## Properties

      "background"               gchar*                : Read / Write
      "closure"                  gpointer              : Read / Write / Construct Only
      "connection"               GDBusConnection*      : Read / Write / Construct Only
      "flags"                    guint                 : Read / Write
      "id"                       gchar*                : Read / Write / Construct Only
      "locked"                   gboolean              : Read / Write
      "locked-down"              gboolean              : Read / Write
      "orient"                   guint                 : Read / Write
      "prefs-key"                gchar*                : Read / Write
      "size"                     guint                 : Read / Write
      "size-hints"               gpointer              : Read / Write

## Signals

      "change-background"                              : Run Last
      "change-orient"                                  : Run Last
      "change-size"                                    : Run Last
      "move-focus-out-of-applet"                       : Action

## Description

Applets are small applications that are embedded in the GNOME panel. They can be used to give quick access to some features, or to display the state of something specific.

The PanelApplet API hides all of the embedding process as it handles all the communication with the GNOME panel. It is a subclass of GtkBin, so you can add any kind of widgets to it.

See the Getting Started section to learn how to properly use PanelApplet.

## Details

### struct PanelApplet

    struct PanelApplet;

### enum PanelAppletOrient

    typedef enum {
    	PANEL_APPLET_ORIENT_UP,
    	PANEL_APPLET_ORIENT_DOWN,
    	PANEL_APPLET_ORIENT_LEFT,
    	PANEL_APPLET_ORIENT_RIGHT
    #define PANEL_APPLET_ORIENT_FIRST PANEL_APPLET_ORIENT_UP
    #define PANEL_APPLET_ORIENT_LAST  PANEL_APPLET_ORIENT_RIGHT
    } PanelAppletOrient;

Type defining the orientation of the applet. The values may seem backward (e.g. `PANEL_APPLET_ORIENT_RIGHT` means the panel is on the left side), but this represents the direction the applet is oriented to.

`PANEL_APPLET_ORIENT_UP` | The PanelApplet is on a horizontal panel, at the bottom of the screen. It is oriented towards the top of the screen.
`PANEL_APPLET_ORIENT_DOWN` | The PanelApplet is on a horizontal panel, at the top of the screen. It is oriented towards the bottom of the screen.
`PANEL_APPLET_ORIENT_LEFT` | The PanelApplet is on a vertical panel, at the right of the screen. It is oriented towards the left of the screen.

### enum PanelAppletFlags

    typedef enum {
    	PANEL_APPLET_FLAGS_NONE   = 0,
    	PANEL_APPLET_EXPAND_MAJOR = 1 << 0,
    	PANEL_APPLET_EXPAND_MINOR = 1 << 1,
    	PANEL_APPLET_HAS_HANDLE   = 1 << 2
    #define PANEL_APPLET_FLAGS_ALL (PANEL_APPLET_EXPAND_MAJOR|PANEL_APPLET_EXPAND_MINOR|PANEL_APPLET_HAS_HANDLE)
    } PanelAppletFlags;

Flags to be used with `panel_applet_get_flags()`/`panel_applet_set_flags()`, to indicate to the panel a specific behavior requested by the PanelApplet.

`PANEL_APPLET_FLAGS_NONE` | No flags set.
`PANEL_APPLET_EXPAND_MAJOR` | On horizontal panels, the PanelApplet will be allocated as much width as possible. On vertical panels, it will be allocated as much height as possible.
`PANEL_APPLET_EXPAND_MINOR` | On horizontal panels, the PanelApplet will be allocated the full height of the panel. On vertical panels, it will be allocated the full width. Most applets should set this flag in order to use the full panel size and allow the applet to be Fitt's Law compliant.

### panel_applet_get_orient ()

    PanelAppletOrient   panel_applet_get_orient             (PanelApplet *applet);

Gets the PanelAppletOrient of `applet`.

`applet` : | a PanelApplet.
Returns : | the PanelAppletOrient of `applet`.

### panel_applet_get_size ()

    guint               panel_applet_get_size               (PanelApplet *applet);

### Warning

`panel_applet_get_size` has been deprecated since version 3.0 and should not be used in newly-written code. Use the allocation of `applet` instead.

Gets the size of the panel `applet` is on. For a horizontal panel, the size if the height of the panel; for a vertical panel, the size is the width of the panel.

`applet` : | a PanelApplet.
Returns : | the size of the panel `applet` is on.

### panel_applet_set_size_hints ()

    void                panel_applet_set_size_hints         (PanelApplet *applet,
                                                             const int *size_hints,
                                                             int n_elements,
                                                             int base_size);

Give hints to the panel about sizes `applet` is comfortable with. This is generally useful for applets that can take a lot of space, in case the panel gets full and needs to restrict the size of some applets.

`size_hints` should have an even number of sizes. It is an array of (max, min) pairs where min(i) > max(i + 1).

`base_size` will be added to all sizes in `size_hints`, and is therefore a way to guarantee a minimum size to `applet`.

The panel will try to allocate a size that is acceptable to `applet`, i.e. in one of the (`base_size` + max, `base_size` + min) ranges.

`PANEL_APPLET_EXPAND_MAJOR` must be set for `applet` to use size hints.

`applet` : | a PanelApplet.
`size_hints` : | array of sizes.
`n_elements` : | length of `size_hints`.
`base_size` : | base size of the applet.

### panel_applet_get_background ()

    cairo_pattern_t *   panel_applet_get_background         (PanelApplet *applet);

Gets the background pattern for `applet`, or `NULL` if there is none.

`applet` : | a PanelApplet.
Returns : | a new cairo_pattern_t to use as background for `applet`. [transfer full]

### panel_applet_set_background_widget ()

    void                panel_applet_set_background_widget  (PanelApplet *applet,
                                                             GtkWidget *widget);

Configure PanelApplet to automatically draw the background of the applet on `widget`. It is generally enough to call this function with `applet` as `widget`.

`applet` : | a PanelApplet.
`widget` : | a GtkWidget.

### panel_applet_get_flags ()

    PanelAppletFlags    panel_applet_get_flags              (PanelApplet *applet);

Gets the PanelAppletFlags of `applet`.

`applet` : | a PanelApplet.
Returns : | the PanelAppletFlags of `applet`.

### panel_applet_set_flags ()

    void                panel_applet_set_flags              (PanelApplet *applet,
                                                             PanelAppletFlags flags);

Sets the PanelAppletFlags of `applet`. Most of the time, at least `PANEL_APPLET_EXPAND_MINOR` should be used.

`applet` : | a PanelApplet.
`flags` : | PanelAppletFlags to use for `applet`.

### panel_applet_get_locked_down ()

    gboolean            panel_applet_get_locked_down        (PanelApplet *applet);

Gets whether the panel `applet` is on is locked down or not. A locked down applet should not allow any change to its configuration.

`applet` : | a PanelApplet.
Returns : | `TRUE` if the panel `applet` is on is locked down, `FALSE` otherwise.

### panel_applet_add_preferences ()

    void                panel_applet_add_preferences        (PanelApplet *applet,
                                                             const gchar *schema_dir,
                                                             GError **error);

Associates the per-instance GConf directory of `applet` to the schemas defined in `schema_dir`. This must be called if the applet will save per-instance settings, to ensure that each key in the per-instance GConf directory has a defined type, sane default and documentation.

`applet` : | a PanelApplet.
`schema_dir` : | a GConf path of a schema directory.
`error` : | a GError, or `NULL`.

### panel_applet_get_preferences_key ()

    gchar *             panel_applet_get_preferences_key    (PanelApplet *applet);

Gets the GConf path to the per-instance settings of `applet`.

`applet` : | a PanelApplet.
Returns : | a copy of the GConf path to the per-instance settings of `applet`.

### panel_applet_request_focus ()

    void                panel_applet_request_focus          (PanelApplet *applet,
                                                             guint32 timestamp);

Requests focus for `applet`. There is no guarantee that `applet` will successfully get focus after that call.

`applet` : | a PanelApplet.
`timestamp` : | the timestamp of the user interaction (typically a button or key press event) which triggered this call.

### panel_applet_setup_menu ()

    void                panel_applet_setup_menu             (PanelApplet *applet,
                                                             const gchar *xml,
                                                             GtkActionGroup *action_group);

Sets up the context menu of `applet`. `xml` is a GtkUIManager UI definition, describing how to display the menu items. `action_group` contains the various GtkAction that are referenced in `xml`.

See also the Context Menu section.

`applet` : | a PanelApplet.
`xml` : | a menu XML string.
`action_group` : | a GtkActionGroup.

### panel_applet_setup_menu_from_file ()

    void                panel_applet_setup_menu_from_file   (PanelApplet *applet,
                                                             const gchar *filename,
                                                             GtkActionGroup *action_group);

Sets up the context menu of `applet`. `filename` is the path to a menu XML file, containing a GtkUIManager UI definition that describes how to display the menu items. `action_group` contains the various GtkAction that are referenced in `xml`.

See also the Context Menu section.

`applet` : | a PanelApplet.
`filename` : | path to a menu XML file.
`action_group` : | a GtkActionGroup.

## Property Details

### The `"background"` property

      "background"               gchar*                : Read / Write

Implementation detail.

Default value: NULL

### The `"closure"` property

      "closure"                  gpointer              : Read / Write / Construct Only

Implementation detail.

### The `"connection"` property

      "connection"               GDBusConnection*      : Read / Write / Construct Only

Implementation detail.

### The `"flags"` property

      "flags"                    guint                 : Read / Write

The PanelAppletFlags of the applet.

Allowed values: <= 7

Default value: 0

### The `"id"` property

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

Implementation detail.

Default value: NULL

### The `"locked"` property

      "locked"                   gboolean              : Read / Write

Whether the position of the applet is locked.

Default value: FALSE

### The `"locked-down"` property

      "locked-down"              gboolean              : Read / Write

Whether the panel the applet is on is locked down.

Default value: FALSE

### The `"orient"` property

      "orient"                   guint                 : Read / Write

The PanelAppletOrient of the applet.

This property gets set when the applet gets embedded, and can change when the panel position changes.

Allowed values: <= 3

Default value: 0

### The `"prefs-key"` property

      "prefs-key"                gchar*                : Read / Write

The GConf path to the per-instance settings of the applet.

This property gets set when the applet gets embedded.

Default value: NULL

### The `"size"` property

      "size"                     guint                 : Read / Write

### Warning

`PanelApplet:size` has been deprecated since version 3.0 and should not be used in newly-written code. Use the allocation of `applet` instead.

The size of the panel the applet is on. For a horizontal panel, the size if the height of the panel; for a vertical panel, the size is the width of the panel.

This property gets set when the applet gets embedded, and can change when the panel size changes.

Default value: 0

### The `"size-hints"` property

      "size-hints"               gpointer              : Read / Write

The size hints set for the applet. See `panel_applet_set_size_hints()`.

## Signal Details

### The `"change-background"` signal

    void                user_function                      (PanelApplet  *applet,
                                                            CairoPattern *pattern,
                                                            gpointer      user_data)      : Run Last

Emitted when the background of `applet` has changed.

`applet` : | the PanelApplet which emitted the signal.
`pattern` : | the new background pattern for `applet`, or `NULL` if there is none.
`user_data` : | user data set when the signal handler was connected.

### The `"change-orient"` signal

    void                user_function                      (PanelApplet *applet,
                                                            guint        orient,
                                                            gpointer     user_data)      : Run Last

Emitted when the PanelAppletOrient of `applet` has changed.

`applet` : | the PanelApplet which emitted the signal.
`orient` : | the new PanelAppletOrient of `applet`.
`user_data` : | user data set when the signal handler was connected.

### The `"change-size"` signal

    void                user_function                      (PanelApplet *applet,
                                                            gint         size,
                                                            gpointer     user_data)      : Run Last

### Warning

`PanelApplet::change-size` has been deprecated since version 3.0 and should not be used in newly-written code. Use the "size-allocate" signal instead.

Emitted when the size of the panel `applet` is on has changed.

`applet` : | the PanelApplet which emitted the signal.
`size` : | the new size of the panel `applet` is on.
`user_data` : | user data set when the signal handler was connected.

### The `"move-focus-out-of-applet"` signal

    void                user_function                      (PanelApplet     *applet,
                                                            GtkDirectionType direction,
                                                            gpointer         user_data)      : Action

Emitted when the focus is moved out of `applet`. This is an implementation detail.

`applet` : | the PanelApplet which emitted the signal.
`direction` : | the move direction.
`user_data` : | user data set when the signal handler was connected.