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
gchar *	gettext-domain	Read / Write / Construct Only
gchar *	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
gchar *	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”           gchar *

The gettext domain.

Owner: GpApplet

Flags: Read / Write / Construct Only

Default value: NULL

The `“id”` property

  “id”                       gchar *

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”            gchar *

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

GpApplet

Functions

Properties

Signals

Types and Values

Object Hierarchy

Implemented Interfaces

Includes

Description

Functions

gp_applet_get_locked_down ()

Parameters

Returns

gp_applet_get_lockdowns ()

Parameters

Returns

gp_applet_get_orientation ()

Parameters

Returns

gp_applet_get_position ()

Parameters

Returns

gp_applet_set_flags ()

Parameters

gp_applet_set_size_hints ()

Parameters

gp_applet_settings_new ()

Parameters

Returns

gp_applet_request_focus ()

Parameters

gp_applet_setup_menu ()

Parameters

gp_applet_setup_menu_from_file ()

Parameters

gp_applet_setup_menu_from_resource ()

Parameters

gp_applet_menu_lookup_action ()

Parameters

Returns

gp_applet_get_prefer_symbolic_icons ()

Parameters

Returns

gp_applet_get_panel_icon_size ()

Parameters

Returns

gp_applet_get_menu_icon_size ()

Parameters

Returns

gp_applet_show_about ()

Parameters

gp_applet_show_help ()

Parameters

gp_applet_popup_menu_at_widget ()

Parameters

Types and Values

GP_TYPE_APPLET

enum GpAppletFlags

Members

struct GpAppletClass

Members

GpApplet

Property Details

The “enable-tooltips” property

The “gettext-domain” property

The “id” property

The “initial-settings” property

The “lockdowns” property

The “locked-down” property

The “menu-icon-size” property

The “module” property

The “orientation” property

The “panel-icon-size” property

The “position” property

The “prefer-symbolic-icons” property

The “settings-path” property

Signal Details

The “flags-changed” signal

Parameters

The “placement-changed” signal

The `“enable-tooltips”` property

The `“gettext-domain”` property

The `“id”` property

The `“initial-settings”` property

The `“lockdowns”` property

The `“locked-down”` property

The `“menu-icon-size”` property

The `“module”` property

The `“orientation”` property

The `“panel-icon-size”` property

The `“position”` property

The `“prefer-symbolic-icons”` property

The `“settings-path”` property

The `“flags-changed”` signal

The `“placement-changed”` signal

The `“size-hints-changed”` signal