![]() |
![]() |
![]() |
Panel Applet Library Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
#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
);
GObject +----GInitiallyUnowned +----GtkWidget +----GtkContainer +----GtkBin +----GtkEventBox +----PanelApplet
"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
"change-background" :Run Last
"change-orient" :Run Last
"change-size" :Run Last
"move-focus-out-of-applet" :Action
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.
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.
The PanelApplet is on a horizontal panel, at the bottom of the screen. It is oriented towards the top of the screen. | |
The PanelApplet is on a horizontal panel, at the top of the screen. It is oriented towards the bottom of the screen. | |
The PanelApplet is on a vertical panel, at the right of the screen. It is oriented towards the left of the screen. | |
The PanelApplet is on a vertical panel, at the left of the screen. It is oriented towards the right of the screen. |
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.
No flags set. | |
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. | |
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. | |
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. |
PanelAppletOrient panel_applet_get_orient (PanelApplet *applet
);
Gets the PanelAppletOrient of applet
.
|
a PanelApplet. |
Returns : |
the PanelAppletOrient of applet . |
guint panel_applet_get_size (PanelApplet *applet
);
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.
|
a PanelApplet. |
Returns : |
the size of the panel applet is on. |
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.
|
a PanelApplet. |
|
array of sizes. |
|
length of size_hints . |
|
base size of the applet. |
cairo_pattern_t * panel_applet_get_background (PanelApplet *applet
);
Gets the background pattern for applet
, or NULL
if there is none.
|
a PanelApplet. |
Returns : |
a new cairo_pattern_t to use as background for
applet . [transfer full]
|
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
.
|
a PanelApplet. |
|
a GtkWidget. |
PanelAppletFlags panel_applet_get_flags (PanelApplet *applet
);
Gets the PanelAppletFlags of applet
.
|
a PanelApplet. |
Returns : |
the PanelAppletFlags of applet . |
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.
|
a PanelApplet. |
|
PanelAppletFlags to use for applet . |
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.
|
a PanelApplet. |
Returns : |
TRUE if the panel applet is on is locked down, FALSE otherwise. |
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.
|
a PanelApplet. |
|
the name of the schema. |
Returns : |
a new GSettings object for the per-instance settings of applet . |
void panel_applet_add_preferences (PanelApplet *applet
,const gchar *schema_dir
,GError **error
);
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.
|
a PanelApplet. |
|
a GConf path of a schema directory. |
|
a GError, or NULL . |
gchar * panel_applet_get_preferences_key (PanelApplet *applet
);
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
.
|
a PanelApplet. |
Returns : |
a copy of the GConf path to the per-instance settings of applet . |
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.
|
a PanelApplet. |
|
the timestamp of the user interaction (typically a button or key press event) which triggered this call. |
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.
|
a PanelApplet. |
|
a menu XML string. |
|
a GtkActionGroup. |
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.
|
a PanelApplet. |
|
path to a menu XML file. |
|
a GtkActionGroup. |
"background"
property "background" gchar* : Read / Write
Implementation detail.
Default value: NULL
"connection"
property "connection" GDBusConnection* : Read / Write / Construct Only
Implementation detail.
"flags"
property "flags" guint : Read / Write
The PanelAppletFlags of the applet.
Allowed values: <= 7
Default value: 0
"id"
property "id" gchar* : Read / Write / Construct Only
Implementation detail.
Default value: NULL
"locked-down"
property "locked-down" gboolean : Read / Write
Whether the panel the applet is on is locked down.
Default value: FALSE
"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
"prefs-key"
property "prefs-key" gchar* : Read / Write
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
"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
"size"
property "size" guint : Read / Write
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
"size-hints"
property "size-hints" gpointer : Read / Write
The size hints set for the applet. See panel_applet_set_size_hints()
.
"change-background"
signalvoid user_function (PanelApplet *applet,
CairoPattern *pattern,
gpointer user_data) : Run Last
Emitted when the background of applet
has changed.
|
the PanelApplet which emitted the signal. |
|
the new background pattern for applet , or NULL if there is none. |
|
user data set when the signal handler was connected. |
"change-orient"
signalvoid user_function (PanelApplet *applet,
guint orient,
gpointer user_data) : Run Last
Emitted when the PanelAppletOrient of applet
has changed.
|
the PanelApplet which emitted the signal. |
|
the new PanelAppletOrient of applet . |
|
user data set when the signal handler was connected. |
"change-size"
signalvoid user_function (PanelApplet *applet,
gint size,
gpointer user_data) : Run Last
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.
|
the PanelApplet which emitted the signal. |
|
the new size of the panel applet is on. |
|
user data set when the signal handler was connected. |
"move-focus-out-of-applet"
signalvoid user_function (PanelApplet *applet,
GtkDirectionType direction,
gpointer user_data) : Action
Emitted when the focus is moved out of applet
. This is an
implementation detail.
|
the PanelApplet which emitted the signal. |
|
the move direction. |
|
user data set when the signal handler was connected. |