GpApplet: GNOME Panel Reference Manual

## GpApplet GpApplet — a widget embedded in a panel |

## Functions

gboolean | gp_applet_get_locked_down ()
GpLockdownFlags | gp_applet_get_lockdowns ()
GtkOrientation | gp_applet_get_orientation ()
GtkPositionType | gp_applet_get_position ()
void | gp_applet_set_flags ()
void | gp_applet_set_size_hints ()
GSettings * | gp_applet_settings_new ()
void | gp_applet_request_focus ()
void | gp_applet_setup_menu ()
void | gp_applet_setup_menu_from_file ()
void | gp_applet_setup_menu_from_resource ()
GAction * | gp_applet_menu_lookup_action ()
gboolean | gp_applet_get_prefer_symbolic_icons ()
guint | gp_applet_get_panel_icon_size ()
guint | gp_applet_get_menu_icon_size ()
void | gp_applet_show_about ()
void | gp_applet_show_help ()
void | gp_applet_popup_menu_at_widget ()

## Properties

gboolean | enable-tooltips | Read
char * | gettext-domain | Read / Write / Construct Only
char * | id | Read / Write / Construct Only
GVariant * | initial-settings | Write / Construct Only
GpLockdownFlags | lockdowns | Read
gboolean | locked-down | Read
guint | menu-icon-size | Read
GpModule * | module | Write / Construct Only
GtkOrientation | orientation | Read
guint | panel-icon-size | Read
GtkPositionType | position | Read
gboolean | prefer-symbolic-icons | Read
char * | settings-path | Read / Write / Construct Only

## Signals

void | flags-changed | Run Last
void | placement-changed | Run Last
void | size-hints-changed | Run Last

## Types and Values

#define | GP_TYPE_APPLET
enum | GpAppletFlags
struct | GpAppletClass
| GpApplet

## Object Hierarchy

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

## Implemented Interfaces

GpApplet implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <libngome-panel/gp-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 GpApplet API hides all of the embedding process as it handles all the communication with the GNOME Panel. It is a subclass of GtkEventBox, so you can add any kind of widgets to it.

## Functions

### gp_applet_get_locked_down ()

    gboolean
    gp_applet_get_locked_down (GpApplet *applet);

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

#### Parameters

applet | a GpApplet |

#### Returns

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

### gp_applet_get_lockdowns ()

    GpLockdownFlags
    gp_applet_get_lockdowns (GpApplet *applet);

Gets active lockdowns.

#### Parameters

applet | a GpApplet |

#### Returns

the GpLockdownFlags of `applet` .

### gp_applet_get_orientation ()

    GtkOrientation
    gp_applet_get_orientation (GpApplet *applet);

Returns the orientation of the panel.

#### Parameters

applet | a GpApplet |

#### Returns

the orientation of the panel.

### gp_applet_get_position ()

    GtkPositionType
    gp_applet_get_position (GpApplet *applet);

Returns the position of the panel.

#### Parameters

applet | a GpApplet |

#### Returns

the position of the panel.

### gp_applet_set_flags ()

    void
    gp_applet_set_flags (GpApplet *applet,
                         GpAppletFlags flags);

Sets the GpAppletFlags of `applet` . Most of the time, at least `GP_APPLET_FLAGS_EXPAND_MINOR` should be used.

#### Parameters

applet | a GpApplet |
flags | a GpAppletFlags to use for `applet` |

### gp_applet_set_size_hints ()

    void
    gp_applet_set_size_hints (GpApplet *applet,
                              const gint *size_hints,
                              guint n_elements,
                              gint 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.

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

#### Parameters

applet | a GpApplet |
size_hints | array of sizes or `NULL`. | [allow-none]
n_elements | length of `size_hints` |
base_size | base size of the applet |

### gp_applet_settings_new ()

    GSettings *
    gp_applet_settings_new (GpApplet *applet,
                            const gchar *schema);

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

Note that you cannot call `gp_applet_settings_new()` from `init()` class method since required property settings-path is not set yet.

#### Parameters

applet | a GpApplet |
schema | the name of the schema |

#### Returns

a newly created GSettings.

[transfer full]

### gp_applet_request_focus ()

    void
    gp_applet_request_focus (GpApplet *applet,
                             guint32 timestamp);

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

#### Parameters

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

### gp_applet_setup_menu ()

    void
    gp_applet_setup_menu (GpApplet *applet,
                          const gchar *xml,
                          const GActionEntry *entries);

Sets up the context menu of `applet` .

#### Parameters

applet | a GpApplet |
xml | a menu XML string |
entries | a pointer to the first item in an `NULL`-terminated array of GActionEntry structs |

### gp_applet_setup_menu_from_file ()

    void
    gp_applet_setup_menu_from_file (GpApplet *applet,
                                    const gchar *filename,
                                    const GActionEntry *entries);

Sets up the context menu of `applet` .

#### Parameters

applet | a GpApplet |
filename | path to a menu XML file |
entries | a pointer to the first item in an `NULL`-terminated array of GActionEntry structs |

### gp_applet_setup_menu_from_resource ()

    void
    gp_applet_setup_menu_from_resource (GpApplet *applet,
                                        const gchar *resource_path,
                                        const GActionEntry *entries);

Sets up the context menu of `applet` .

#### Parameters

applet | a GpApplet |
resource_path | a resource path |
entries | a pointer to the first item in an `NULL`-terminated array of GActionEntry structs |

### gp_applet_menu_lookup_action ()

    GAction *
    gp_applet_menu_lookup_action (GpApplet *applet,
                                  const gchar *action_name);

Looks up the action with the name `action_name` in action group.

#### Parameters

applet | a GpApplet |
action_name | the name of an action |

#### Returns

a GAction, or `NULL`.

[transfer none]

### gp_applet_get_prefer_symbolic_icons ()

    gboolean
    gp_applet_get_prefer_symbolic_icons (GpApplet *applet);

Returns whether the applet should prefer symbolic icons in panels.

#### Parameters

applet | a GpApplet |

#### Returns

whether the applet should prefer symbolic icons in panels.

### gp_applet_get_panel_icon_size ()

    guint
    gp_applet_get_panel_icon_size (GpApplet *applet);

Returns the panel icon size.

#### Parameters

applet | a GpApplet |

#### Returns

the panel icon size.

### gp_applet_get_menu_icon_size ()

    guint
    gp_applet_get_menu_icon_size (GpApplet *applet);

Returns the menu icon size.

#### Parameters

applet | a GpApplet |

#### Returns

the menu icon size.

### gp_applet_show_about ()

    void
    gp_applet_show_about (GpApplet *applet);

Show about dialog. GpAboutDialogFunc must be set with `gp_applet_info_set_about_dialog()`.

#### Parameters

applet | a GpApplet |

### gp_applet_show_help ()

    void
    gp_applet_show_help (GpApplet *applet,
                         const char *page);

Show help. Help URI must be set with `gp_applet_info_set_help_uri()`.

The optional `page` indentifier may include options and anchor if needed.

#### Parameters

applet | a GpApplet |
page | the optional page identifier |

### gp_applet_popup_menu_at_widget ()

    void
    gp_applet_popup_menu_at_widget (GpApplet *applet,
                                    GtkMenu *menu,
                                    GtkWidget *widget,
                                    GdkEvent *event);

Displays menu and makes it available for selection. This is convenience function around `gtk_menu_popup_at_widget()` that automatically computes the widget_anchor and menu_anchor parameters based on the current applet position.

#### Parameters

applet | a GpApplet |
menu | the GtkMenu to pop up. |
widget | the GtkWidget to align menu with. |
event | the GdkEvent that initiated this request or NULL if it's the current event. |

## Types and Values

### GP_TYPE_APPLET

    #define GP_TYPE_APPLET gp_applet_get_type ()

The type for GpApplet.

### enum GpAppletFlags

Flags to be used with `gp_applet_set_flags()`, to indicate to the panel a specific behavior requested by the GpApplet.

#### Members

GP_APPLET_FLAGS_NONE | No flags set. |
GP_APPLET_FLAGS_EXPAND_MAJOR | On horizontal panels, the GpApplet will be allocated as much width as possible. On vertical panels, it will be allocated as much height as possible. |
GP_APPLET_FLAGS_EXPAND_MINOR | On horizontal panels, the GpApplet 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 full panel size and allow the applet to be Fitt's Law compliant. |
GP_APPLET_FLAGS_HAS_HANDLE | The panel will draw a handle for the GpApplet. This handle will be usable to move the applet, and to open the context menu of the applet. |

### struct GpAppletClass

    struct GpAppletClass {
      GtkEventBoxClass parent_class;

      void (* initial_setup)       (GpApplet        *applet,
                                    GVariant        *initial_settings);

      void (* placement_changed)   (GpApplet        *applet,
                                    GtkOrientation   orientation,
                                    GtkPositionType  position);

      void (* remove_from_panel)   (GpApplet        *self);
    };

The class structure for the GpApplet class.

#### Members

`initial_setup` () | virtual method called when applet has initial settings |
`placement_changed` () | Signal is emitted when the orientation or position properties of applet has changed. |
`remove_from_panel` () | virtual method called when applet is removed from panel. |

### GpApplet

    typedef struct _GpApplet GpApplet;

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

## Property Details

### The `“enable-tooltips”` property

      “enable-tooltips”          gboolean

Whether the applet should show tooltips.

Owner: GpApplet

Flags: Read

Default value: TRUE

### The `“gettext-domain”` property

      “gettext-domain”           char *

The gettext domain.

Owner: GpApplet

Flags: Read / Write / Construct Only

Default value: NULL

### The `“id”` property

      “id”                       char *

The applet id.

Owner: GpApplet

Flags: Read / Write / Construct Only

Default value: NULL

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

      “initial-settings”         GVariant *

The GVariant with initial settings.

Owner: GpApplet

Flags: Write / Construct Only

Allowed values: GVariant<a{sv}>

Default value: NULL

### The `“lockdowns”` property

      “lockdowns”                GpLockdownFlags

Active lockdowns.

Owner: GpApplet

Flags: Read

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

      “locked-down”              gboolean

Whether the applet is on locked down panel.

`GpApplet:locked-down` has been deprecated since version 3.38 and should not be used in newly-written code.

Use “lockdowns” instead

Owner: GpApplet

Flags: Read

Default value: FALSE

### The `“menu-icon-size”` property

      “menu-icon-size”           guint

The size of icons in menus.

Owner: GpApplet

Flags: Read

Allowed values: [16,24]

Default value: 16

### The `“module”` property

      “module”                   GpModule *

The applet module.

Owner: GpApplet

Flags: Write / Construct Only

### The `“orientation”` property

      “orientation”              GtkOrientation

The orientation of the panel.

Owner: GpApplet

Flags: Read

Default value: GTK_ORIENTATION_HORIZONTAL

### The `“panel-icon-size”` property

      “panel-icon-size”          guint

The size of icons in panels.

Owner: GpApplet

Flags: Read

Allowed values: [16,64]

Default value: 16

### The `“position”` property

      “position”                 GtkPositionType

The position of the panel.

Owner: GpApplet

Flags: Read

Default value: GTK_POS_TOP

### The `“prefer-symbolic-icons”` property

      “prefer-symbolic-icons”    gboolean

Whether the applet should prefer symbolic icons in panels.

Owner: GpApplet

Flags: Read

Default value: FALSE

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

      “settings-path”            char *

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

Owner: GpApplet

Flags: Read / Write / Construct Only

Default value: NULL

## Signal Details

### The `“flags-changed”` signal

    void
    user_function (GpApplet *applet,
                   gpointer  user_data)

Signal is emitted when flags has changed.

#### Parameters

applet | the object on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“placement-changed”` signal

    void
    user_function (GpApplet       *applet,
                   GtkOrientation  orientation,
                   GtkPositionType position,
                   gpointer        user_data)

Signal is emitted when the orientation or position properties of applet has changed.

Note that `gp_applet_get_orientation()` or `gp_applet_get_position()` functions will return old values in signal handler!

#### Parameters

applet | the object on which the signal is emitted |
orientation | the new orientation |
position | the new position |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“size-hints-changed”` signal

    void
    user_function (GpApplet *applet,
                   gpointer  user_data)

Signal is emitted when size hints has changed.

#### Parameters

applet | the object on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last