![]() |
![]() |
![]() |
Panel Applet Library Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
#include <panel-applet.h> PanelApplet; enum PanelAppletOrient; enum PanelAppletBackgroundType; enum PanelAppletFlags; gboolean (*PanelAppletFactoryCallback) (PanelApplet *applet
,const gchar *iid
,gpointer user_data
); GtkWidget * panel_applet_new (void
); PanelAppletOrient panel_applet_get_orient (PanelApplet *applet
); guint panel_applet_get_size (PanelApplet *applet
); PanelAppletBackgroundType panel_applet_get_background (PanelApplet *applet
,GdkColor *color
,GdkPixmap **pixmap
); gchar * panel_applet_get_preferences_key (PanelApplet *applet
); void panel_applet_add_preferences (PanelApplet *applet
,const gchar *schema_dir
,GError **opt_error
); PanelAppletFlags panel_applet_get_flags (PanelApplet *applet
); void panel_applet_set_flags (PanelApplet *applet
,PanelAppletFlags flags
); void panel_applet_set_size_hints (PanelApplet *applet
,const int *size_hints
,int n_elements
,int base_size
); gboolean panel_applet_get_locked_down (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
); int panel_applet_factory_main (const gchar *factory_id
,gboolean out_process
,GType applet_type
,PanelAppletFactoryCallback callback
,gpointer data
);
GObject +----GInitiallyUnowned +----GtkObject +----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" gboolean : Read / Write "locked-down" gboolean : Read / Write "orient" guint : Read / Write "prefs-key" 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" : Run Last / Action
The PanelApplet object is an object which encapsulates an applet. It is a GtkContainer which may contain a single widget. This widget, in turn, should contain all widgets exposed by the applet.
A PanelApplet is associated with a BonoboControl. The control makes the cross process UI emmbedding required by applets possible.
typedef struct _PanelApplet PanelApplet;
The PanelApplet struct contains private data only.
typedef enum { PANEL_APPLET_ORIENT_UP, PANEL_APPLET_ORIENT_DOWN, PANEL_APPLET_ORIENT_LEFT, PANEL_APPLET_ORIENT_RIGHT } PanelAppletOrient;
The PanelAppletOrient type specifies the orientation of the applet. The
values may seem backward (e.g. PANEL_APPLET_ORIENT_LEFT
means the panel
is on the right hand side), but this is because the value is representative
of the applet's orientation, not the panel's position.
typedef enum { PANEL_NO_BACKGROUND, PANEL_COLOR_BACKGROUND, PANEL_PIXMAP_BACKGROUND } PanelAppletBackgroundType;
The PanelAppletBackgroundType enumerated type specifies the type of background of a panel.
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;
The PanelAppletFlags associated with the applet are boolean flags which the panel may read in order to figure out how to handle the applet.
No flags are to be associated with the applet. | |
The applet should expand horizontally on an horizontal panel and vertically on a vertical panel - e.g. the behaviour of the Window List applet. | |
The applet should expand vertically on an horizontal panel and horizontally on a vertical panel. Most applets should set this flag in order to utilise the full panel width and allow the applet to be Fitt's Law compliant. | |
The panel should draw a grab handle around the applet - e.g. the Window List and Notification Area applets both set this flag. |
gboolean (*PanelAppletFactoryCallback) (PanelApplet *applet
,const gchar *iid
,gpointer user_data
);
This callback is invoked when the applet is loaded onto the panel. Typically
the callback will check that iid
matches and fill the applet
with the
widgets which make up the applet.
Prior to the callback being invoked the PanelApplet (or an instance of the sub-class specified by the GType passed to the factory macros) is instantiated and initialized.
|
The PanelApplet. |
|
The Bonobo IID of the applet requested. |
|
The data passed to the factory macros. |
Returns : |
TRUE on success, FALSE on failure.
|
GtkWidget * panel_applet_new (void
);
Creates a new PanelApplet. This function is typically not useful as the applet is created before the PanelAppletFactoryCallback is invoked.
Returns : |
The PanelApplet. |
PanelAppletOrient panel_applet_get_orient (PanelApplet *applet
);
Get the current orientation of the applet.
|
The PanelApplet. |
Returns : |
The orientation of the applet. |
guint panel_applet_get_size (PanelApplet *applet
);
Get the current size hint for the panel. The size hint is not useful for most applets.
Note: The return value is not an integer value specifying the pixel size of the panel. Do not use this value to calculate the size of the applet. Use it only as a hint by which to decide the applet's layout.
|
The PanelApplet. |
Returns : |
The panel's size hint. |
PanelAppletBackgroundType panel_applet_get_background (PanelApplet *applet
,GdkColor *color
,GdkPixmap **pixmap
);
Returns the current background type. If the background
type is PANEL_NO_BACKGROUND
both color
and pixmap
will
be unaffected. If the background type is PANEL_COLOR_BACKGROUND
then color
will contain the current panel background colour.
If the background type is PANEL_PIXMAP_BACKGROUND
, pixmap
will
contain a pointer to a GdkPixmap which is a copy of the applet's
portion of the panel's background pixmap.
|
A PanelApplet. |
|
A GdkColor to be filled in. |
|
Returned GdkPixmap. |
Returns : |
The background type. |
gchar * panel_applet_get_preferences_key (PanelApplet *applet
);
Returns the GConf path to the directory containing the applet's per-instance preference keys. Using this you may construct the full path for the applet's preference keys. See Panel Applet GConf Utilities(3) for more information.
|
The PanelApplet. |
Returns : |
A GConf path. |
void panel_applet_add_preferences (PanelApplet *applet
,const gchar *schema_dir
,GError **opt_error
);
Associates each schema in schema_dir
with a key in the applet's
preferences directory (i.e. the directory returned by
panel_applet_get_preferences_key()
). Each applet preference
should have an associated schema to ensure that the key has
a defined type, sane default and documentation.
If you pass NULL
for opt_error
, this function will print
a warning message from any GError which GConf may return.
|
The PanelApplet. |
|
The GConf path where the applet's schemas are installed e.g. /schemas/apps/my_applet |
|
Optional GError. |
PanelAppletFlags panel_applet_get_flags (PanelApplet *applet
);
Retrieve the PanelAppletFlags associated with the applet.
|
The PanelApplet. |
Returns : |
The PanelAppletFlags. |
void panel_applet_set_flags (PanelApplet *applet
,PanelAppletFlags flags
);
Set the PanelAppletFlags associated with the applet. See PanelAppletFlags for more details on the possible uses of these flags.
|
The PanelApplet. |
|
The PanelAppletFlags to associate. |
void panel_applet_set_size_hints (PanelApplet *applet
,const int *size_hints
,int n_elements
,int base_size
);
Set a list of desired size ranges for an applet with the
PANEL_APPLET_EXPAND_MAJOR flags set. size_hints
is an
array of (max, min) pairs where min(i) > max(i + 1).
The panel will endeavour to allocate the applet a size
in one of the (base
+ max, base
+ min) ranges.
|
The PanelApplet. |
|
Array of size_hints. |
|
Number of elements in the array. Not the number of pairs. |
|
The base size of the applet. |
gboolean panel_applet_get_locked_down (PanelApplet *applet
);
Check if the applet
is locked down. A locked down applet should not allow any change to its configuration.
|
The PanelApplet. |
Returns : |
TRUE if the applet is locked down, FALSE otherwise.
|
void panel_applet_request_focus (PanelApplet *applet
,guint32 timestamp
);
Set keyboard focus to applet
.
|
The PanelApplet. |
|
timestamp of the event triggering the window focus |
void panel_applet_setup_menu (PanelApplet *applet
,const gchar *xml
,GtkActionGroup *action_group
);
Sets up a popup menu for applet
described by the xml
string, xml
. See Writing Applets section
for a description of the format of the xml.
|
A PanelApplet. |
|
The xml character string describing the popup menu. |
|
void panel_applet_setup_menu_from_file (PanelApplet *applet
,const gchar *filename
,GtkActionGroup *action_group
);
Sets up a popup menu for applet
described by the xml
file, file
. See Writing Applets for a description of
the format of the xml.
|
A PanelApplet. |
|
|
|
int panel_applet_factory_main (const gchar *factory_id
,gboolean out_process
,GType applet_type
,PanelAppletFactoryCallback callback
,gpointer data
);
A generic 'main' routine for applets. This should not normally be used directly because it is invoked by PANEL_APPLET_BONOBO_FACTORY.
|
|
|
|
|
The GType to instantiate. |
|
The factory callback. |
|
The factory user data pointer. |
Returns : |
0 on success, 1 on failure. |
"background"
property "background" gchar* : Read / Write
Panel Applet Background.
Default value: NULL
"connection"
property "connection" GDBusConnection* : Read / Write / Construct Only
The DBus Connection.
"id"
property "id" gchar* : Read / Write / Construct Only
The Applet identifier.
Default value: NULL
"locked"
property "locked" gboolean : Read / Write
Whether Panel Applet is locked.
Default value: FALSE
"locked-down"
property "locked-down" gboolean : Read / Write
Whether Panel Applet is locked down.
Default value: FALSE
"prefs-key"
property "prefs-key" gchar* : Read / Write
GConf Preferences Key.
Default value: NULL
"change-background"
signalvoid user_function (PanelApplet *panelapplet, PanelAppletBackgroundType arg1, GdkColor *arg2, GdkPixmap *arg3, gpointer user_data) : Run Last
Emitted when the background of the panel changes. Use type
to
determine which, if any, of color
and pimxap
is valid.
|
The object which received the signal. |
|
|
|
|
|
|
|
user data set when the signal handler was connected. |
"change-orient"
signalvoid user_function (PanelApplet *panelapplet, guint arg1, gpointer user_data) : Run Last
Emitted when the orientation of the panel changes.
|
The object which received the signal. |
|
The new PanelAppletOrient of the applet. |
|
user data set when the signal handler was connected. |
"change-size"
signalvoid user_function (PanelApplet *panelapplet, gint arg1, gpointer user_data) : Run Last
Emitted when the size of the panel changes.
Note: this is different for size negotiation which is handled by
size_request()
and size_allocate()
as usual. This signal should
be used to determine what font size or widget layout to use
depending on the size of the panel. See panel_applet_get_size()
.
|
The object which received the signal. |
|
The size hint of the panel. |
|
user data set when the signal handler was connected. |
"move-focus-out-of-applet"
signalvoid user_function (PanelApplet *panelapplet, GtkDirectionType arg1, gpointer user_data) : Run Last / Action
Emitted when the applet has lost focus. This signal is used internally and is not meant to be used by applets themselves.
|
The object which received the signal. |
|
The direction of focus movement. |
|
user data set when the signal handler was connected. |