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);
GSettings *         panel_applet_settings_new           (PanelApplet *applet,
                                                         const char *schema);
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-down"              gboolean              : Read / Write
  "orient"                   guint                 : Read / Write
  "prefs-key"                gchar*                : Read / Write
  "settings-path"            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
} 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.

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.

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

applet :

a PanelApplet.

schema :

the name of the schema.

Returns :

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

panel_applet_add_preferences ()

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

Warning

panel_applet_add_preferences has been deprecated since version 3.0 and should not be used in newly-written code. Use GSettings to store per-instance settings.

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

Warning

panel_applet_get_preferences_key has been deprecated since version 3.0 and should not be used in newly-written code. Use GSettings to store per-instance settings.

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

Warning

PanelApplet:prefs-key has been deprecated since version 3.0 and should not be used in newly-written code. Use GSettings to store per-instance settings.

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

This property gets set when the applet gets embedded.

Default value: NULL


The "settings-path" property

  "settings-path"            gchar*                : Read / Write

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