Panel Applet: Panel Applet Reference Manual

## Panel Applet Panel Applet — a widget embedded in a panel. |

## Stability Level

Unstable, unless otherwise indicated

## Functions

PanelAppletOrient | panel_applet_get_orient ()
GtkOrientation | panel_applet_get_gtk_orientation ()
void | panel_applet_set_size_hints ()
cairo_pattern_t * | panel_applet_get_background ()
void | panel_applet_set_background_widget ()
PanelAppletFlags | panel_applet_get_flags ()
void | panel_applet_set_flags ()
gboolean | panel_applet_get_locked_down ()
GSettings * | panel_applet_settings_new ()
void | panel_applet_request_focus ()
void | panel_applet_setup_menu ()
void | panel_applet_setup_menu_from_file ()
void | panel_applet_setup_menu_from_resource ()

## Properties

gchar * | background | Read / Write
gpointer | closure | Read / Write / Construct Only
GDBusConnection * | connection | Read / Write / Construct Only
guint | flags | Read / Write
gchar * | id | Read / Write / Construct Only
gboolean | locked-down | Read / Write
guint | orient | Read / Write
gboolean | out-of-process | Read / Write / Construct Only
gchar * | settings-path | Read / Write
gpointer | size-hints | Read / Write

## Signals

void | change-background | Run Last
void | change-orient | Run Last
void | move-focus-out-of-applet | Action

## Types and Values

struct | PanelApplet
enum | PanelAppletOrient
#define | PANEL_APPLET_ORIENT_FIRST
#define | PANEL_APPLET_ORIENT_LAST
enum | PanelAppletFlags
#define | PANEL_APPLET_FLAGS_ALL

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkBin
                        ╰── GtkEventBox
                            ╰── PanelApplet

## Implemented Interfaces

PanelApplet implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <panel-applet.h>

## 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.

## Functions

### panel_applet_get_orient ()

    PanelAppletOrient
    panel_applet_get_orient (PanelApplet *applet);

Gets the PanelAppletOrient of `applet` .

#### Parameters

applet | a PanelApplet. |

#### Returns

the PanelAppletOrient of `applet` .

### panel_applet_get_gtk_orientation ()

    GtkOrientation
    panel_applet_get_gtk_orientation (PanelApplet *applet);

Gets the GtkOrientation of `applet` .

#### Parameters

applet | a PanelApplet |

#### Returns

the GtkOrientation of `applet` .

Since: 3.18

### 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.

#### Parameters

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.

#### Parameters

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);

`panel_applet_set_background_widget` has been deprecated since version 3.20 and should not be used in newly-written code.

Do not use this API. Since 3.20 this function does nothing.

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

#### Parameters

applet | a PanelApplet. |
widget | a GtkWidget. |

### panel_applet_get_flags ()

    PanelAppletFlags
    panel_applet_get_flags (PanelApplet *applet);

Gets the PanelAppletFlags of `applet` .

#### Parameters

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.

#### Parameters

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.

#### Parameters

applet | a PanelApplet. |

#### Returns

`TRUE` if the panel `applet` is on is locked down, `FALSE` otherwise.

### panel_applet_settings_new ()

    GSettings *
    panel_applet_settings_new (PanelApplet *applet,
                               const char *schema);

Creates a new GSettings object for the per-instance settings of `applet` , with a given schema.

#### Parameters

applet | a PanelApplet. |
schema | the name of the schema. |

#### Returns

a new GSettings object for the per-instance settings of `applet` .

[transfer full]

### 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.

#### Parameters

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,
                             GSimpleActionGroup *action_group,
                             const gchar *translation_domain);

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 GSimpleAction that are referenced in `xml` .

See also the Context Menu section.

#### Parameters

applet | a PanelApplet. |
xml | a menu XML string. |
action_group | a GSimpleActionGroup. |
translation_domain | gettext translation domain |

### panel_applet_setup_menu_from_file ()

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

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 GSimpleAction that are referenced in `xml` .

See also the Context Menu section.

#### Parameters

applet | a PanelApplet. |
filename | path to a menu XML file. |
action_group | a GSimpleActionGroup. |
translation_domain | gettext translation domain |

### panel_applet_setup_menu_from_resource ()

    void
    panel_applet_setup_menu_from_resource (PanelApplet *applet,
                                           const gchar *resource_path,
                                           GSimpleActionGroup *action_group,
                                           const gchar *translation_domain);

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

See also the Context Menu section.

#### Parameters

applet | a PanelApplet. |
resource_path | a resource path |
action_group | a GSimpleActionGroup. |
translation_domain | gettext translation domain |

Since: 3.4

## Types and Values

### struct PanelApplet

    struct PanelApplet;

PanelApplet is an opaque data structure and can only be accessed using the following functions.

### enum 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.

#### Members

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. |
PANEL_APPLET_ORIENT_RIGHT | The PanelApplet is on a vertical panel, at the left of the screen. It is oriented towards the right of the screen. |

### PANEL_APPLET_ORIENT_FIRST

    #define PANEL_APPLET_ORIENT_FIRST PANEL_APPLET_ORIENT_UP

This macro is an alias for PANEL_APPLET_ORIENT_UP

### PANEL_APPLET_ORIENT_LAST

    #define PANEL_APPLET_ORIENT_LAST  PANEL_APPLET_ORIENT_RIGHT

This macro is an alias for PANEL_APPLET_ORIENT_RIGHT

### enum 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.

#### Members

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_HAS_HANDLE | The panel will draw a handle for the PanelApplet. This handle will be usable to move the applet, and to open the context menu of the applet. |

### PANEL_APPLET_FLAGS_ALL

    #define             PANEL_APPLET_FLAGS_ALL

A convenience macro that combines PANEL_APPLET_EXPAND_MAJOR, PANEL_APPLET_EXPAND_MINOR and PANEL_APPLET_HAS_HANDLE from PanelAppletFlags

## Property Details

### The `“background”` property

      “background”               gchar *

Implementation detail.

[skip]

Flags: Read / Write

Default value: NULL

### The `“closure”` property

      “closure”                  gpointer

Implementation detail.

[skip]

Flags: Read / Write / Construct Only

### The `“connection”` property

      “connection”               GDBusConnection *

Implementation detail.

[skip]

Flags: Read / Write / Construct Only

### The `“flags”` property

      “flags”                    guint

The PanelAppletFlags of the applet.

Flags: Read / Write

Allowed values: <= 7

Default value: 0

### The `“id”` property

      “id”                       gchar *

Implementation detail.

[skip]

Flags: Read / Write / Construct Only

Default value: NULL

### The `“locked-down”` property

      “locked-down”              gboolean

Whether the panel the applet is on is locked down.

Flags: Read / Write

Default value: FALSE

### The `“orient”` property

      “orient”                   guint

The PanelAppletOrient of the applet.

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

Flags: Read / Write

Allowed values: <= 3

Default value: 0

### The `“out-of-process”` property

      “out-of-process”           gboolean

Implementation detail.

[skip]

Flags: Read / Write / Construct Only

Default value: TRUE

### The `“settings-path”` property

      “settings-path”            gchar *

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

This property gets set when the applet gets embedded.

Flags: Read / Write

Default value: NULL

### The `“size-hints”` property

      “size-hints”               gpointer

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

Flags: Read / Write

## Signal Details

### The `“change-background”` signal

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

Emitted when the background of `applet` has changed.

#### Parameters

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. |

Flags: Run Last

### The `“change-orient”` signal

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

Emitted when the PanelAppletOrient of `applet` has changed.

#### Parameters

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

Flags: Run Last

### The `“move-focus-out-of-applet”` signal

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

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

[skip]

#### Parameters

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

Flags: Action