1
<!-- ##### SECTION Title ##### -->
4
<!-- ##### SECTION Short_Description ##### -->
5
The PanelApplet object.
7
<!-- ##### SECTION Long_Description ##### -->
9
The #PanelApplet object is an object which encapsulates an applet. It
10
is a #GtkContainer which may contain a single widget. This widget, in
11
turn, should contain all widgets exposed by the applet.
15
A #PanelApplet is associated with a #BonoboControl. The control makes
16
the cross process UI emmbedding required by applets possible.
19
<!-- ##### SECTION See_Also ##### -->
24
<!-- ##### SECTION Stability_Level ##### -->
27
<!-- ##### SECTION Image ##### -->
30
<!-- ##### STRUCT PanelApplet ##### -->
32
The #PanelApplet struct contains private data only.
36
<!-- ##### SIGNAL PanelApplet::change-background ##### -->
38
Emitted when the background of the panel changes. Use @type to
39
determine which, if any, of @color and @pimxap is valid.
42
@panelapplet: The object which received the signal.
46
<!-- # Unused Parameters # -->
47
@type: The #PanelAppletBackgroundType.
48
@color: The #GdkColor if @type is #PANEL_COLOR_BACKGROUND.
49
@pixmap: The pixmap file name if @type is #PANEL_PIXMAP_BACKGROUND
51
<!-- ##### SIGNAL PanelApplet::change-orient ##### -->
53
Emitted when the orientation of the panel changes.
56
@panelapplet: The object which received the signal.
57
@orient: The new #PanelAppletOrient of the applet.
59
<!-- ##### SIGNAL PanelApplet::change-size ##### -->
61
Emitted when the size of the panel changes.
65
Note: this is different for size negotiation which is handled by
66
size_request() and size_allocate() as usual. This signal should
67
be used to determine what font size or widget layout to use
68
depending on the size of the panel. See panel_applet_get_size().
71
@panelapplet: The object which received the signal.
72
@size: The size hint of the panel.
74
<!-- ##### SIGNAL PanelApplet::move-focus-out-of-applet ##### -->
76
Emitted when the applet has lost focus. This signal is used internally and is not meant to be used by applets themselves.
79
@panelapplet: The object which received the signal.
80
@direction: The direction of focus movement.
82
<!-- ##### ARG PanelApplet:background ##### -->
87
<!-- ##### ARG PanelApplet:closure ##### -->
92
<!-- ##### ARG PanelApplet:connection ##### -->
97
<!-- ##### ARG PanelApplet:flags ##### -->
102
<!-- ##### ARG PanelApplet:id ##### -->
107
<!-- ##### ARG PanelApplet:locked ##### -->
112
<!-- ##### ARG PanelApplet:locked-down ##### -->
117
<!-- ##### ARG PanelApplet:orient ##### -->
122
<!-- ##### ARG PanelApplet:prefs-key ##### -->
127
<!-- ##### ARG PanelApplet:size ##### -->
132
<!-- ##### ARG PanelApplet:size-hints ##### -->
137
<!-- ##### ENUM PanelAppletOrient ##### -->
139
The #PanelAppletOrient type specifies the orientation of the applet. The
140
values may seem backward (e.g. %PANEL_APPLET_ORIENT_LEFT means the panel
141
is on the right hand side), but this is because the value is representative
142
of the applet's <emphasis>orientation</emphasis>, not the panel's position.
145
@PANEL_APPLET_ORIENT_UP:
146
@PANEL_APPLET_ORIENT_DOWN:
147
@PANEL_APPLET_ORIENT_LEFT:
148
@PANEL_APPLET_ORIENT_RIGHT:
150
<!-- ##### ENUM PanelAppletBackgroundType ##### -->
152
The #PanelAppletBackgroundType enumerated type specifies the type of
153
background of a panel.
156
@PANEL_NO_BACKGROUND: The panel has no background, the default is used.
157
@PANEL_COLOR_BACKGROUND: The panel has a color, i.e rgb value,
159
@PANEL_PIXMAP_BACKGROUND: The panel has either an image background
162
<!-- ##### ENUM PanelAppletFlags ##### -->
164
The #PanelAppletFlags associated with the applet are boolean flags which
165
the panel may read in order to figure out how to handle the applet.
168
@PANEL_APPLET_FLAGS_NONE: No flags are to be associated with the applet.
169
@PANEL_APPLET_EXPAND_MAJOR: The applet should expand horizontally on an
170
horizontal panel and vertically on a vertical panel - e.g. the behaviour
171
of the Window List applet.
172
@PANEL_APPLET_EXPAND_MINOR: The applet should expand vertically on an
173
horizontal panel and horizontally on a vertical panel. Most applets should
174
set this flag in order to utilise the full panel width and allow the applet
175
to be Fitt's Law compliant.
176
@PANEL_APPLET_HAS_HANDLE: The panel should draw a grab handle around the
177
applet - e.g. the Window List and Notification Area applets both set this
180
<!-- ##### USER_FUNCTION PanelAppletFactoryCallback ##### -->
182
This callback is invoked when the applet is loaded onto the panel. Typically
183
the callback will check that @iid matches and fill the @applet with the
184
widgets which make up the applet.
188
Prior to the callback being invoked the #PanelApplet (or an instance of the
189
sub-class specified by the #GType passed to the factory macros) is instantiated
193
@applet: The #PanelApplet.
194
@iid: The Bonobo IID of the applet requested.
195
@user_data: The data passed to the factory macros.
196
@Returns: %TRUE on success, %FALSE on failure.
199
<!-- ##### FUNCTION panel_applet_new ##### -->
201
Creates a new #PanelApplet. This function is typically not
202
useful as the applet is created before the #PanelAppletFactoryCallback
207
@Returns: The #PanelApplet.
210
<!-- ##### FUNCTION panel_applet_get_orient ##### -->
212
Get the current orientation of the applet.
215
@applet: The #PanelApplet.
216
@Returns: The orientation of the applet.
219
<!-- ##### FUNCTION panel_applet_get_size ##### -->
221
Get the current size hint for the panel. The size hint is
222
not useful for most applets.
226
Note: The return value is <emphasis>not an integer value
227
specifying the pixel size of the panel.</emphasis> Do not
228
use this value to calculate the size of the applet. Use it
229
only as a hint by which to decide the applet's layout.
232
@applet: The #PanelApplet.
233
@Returns: The panel's size hint.
236
<!-- ##### FUNCTION panel_applet_get_background ##### -->
238
Returns the current background type. If the background
239
type is %PANEL_NO_BACKGROUND both @color and @pixmap will
240
be unaffected. If the background type is %PANEL_COLOR_BACKGROUND
241
then @color will contain the current panel background colour.
242
If the background type is %PANEL_PIXMAP_BACKGROUND, @pixmap will
243
contain a pointer to a #GdkPixmap which is a copy of the applet's
244
portion of the panel's background pixmap.
247
<!-- FIXME: give an example of how to use this -->
249
@applet: A #PanelApplet.
250
@color: A #GdkColor to be filled in.
251
@pixmap: Returned #GdkPixmap.
252
@Returns: The background type.
255
<!-- ##### FUNCTION panel_applet_get_preferences_key ##### -->
257
Returns the GConf path to the directory containing the applet's
258
per-instance preference keys. Using this you may construct the
259
full path for the applet's preference keys. See
260
<xref linkend="panel-applet-Panel-Applet-GConf-Utilities" /> for
264
@applet: The #PanelApplet.
265
@Returns: A GConf path.
268
<!-- ##### FUNCTION panel_applet_add_preferences ##### -->
270
Associates each schema in @schema_dir with a key in the applet's
271
preferences directory (i.e. the directory returned by
272
panel_applet_get_preferences_key()). Each applet preference
273
should have an associated schema to ensure that the key has
274
a defined type, sane default and documentation.
278
If you pass %NULL for @opt_error, this function will print
279
a warning message from any #GError which GConf may return.
282
@applet: The #PanelApplet.
283
@schema_dir: The GConf path where the applet's schemas are installed
284
e.g. /schemas/apps/my_applet
285
@opt_error: Optional #GError.
288
<!-- ##### FUNCTION panel_applet_get_flags ##### -->
290
Retrieve the #PanelAppletFlags associated with the applet.
293
@applet: The #PanelApplet.
294
@Returns: The #PanelAppletFlags.
297
<!-- ##### FUNCTION panel_applet_set_flags ##### -->
299
Set the #PanelAppletFlags associated with the applet. See
300
#PanelAppletFlags for more details on the possible uses of
304
@applet: The #PanelApplet.
305
@flags: The #PanelAppletFlags to associate.
308
<!-- ##### FUNCTION panel_applet_set_size_hints ##### -->
310
Set a list of desired size ranges for an applet with the
311
#PANEL_APPLET_EXPAND_MAJOR flags set. @size_hints is an
312
array of (max, min) pairs where min(i) > max(i + 1).
316
The panel will endeavour to allocate the applet a size
317
in one of the (@base + max, @base + min) ranges.
320
@applet: The #PanelApplet.
321
@size_hints: Array of size_hints.
322
@n_elements: Number of elements in the array. <emphasis>
323
Not</emphasis> the number of pairs.
324
@base_size: The base size of the applet.
327
<!-- ##### FUNCTION panel_applet_get_locked_down ##### -->
329
Check if the @applet is locked down. A locked down applet should not allow any change to its configuration.
332
@applet: The #PanelApplet.
333
@Returns: %TRUE if the @applet is locked down, %FALSE otherwise.
336
<!-- ##### FUNCTION panel_applet_request_focus ##### -->
338
Set keyboard focus to @applet.
341
@applet: The #PanelApplet.
342
@timestamp: timestamp of the event triggering the window focus
345
<!-- ##### FUNCTION panel_applet_setup_menu ##### -->
347
Sets up a popup menu for @applet described by the xml
348
string, @xml. See <xref linkend="applet-writing" /> section
349
for a description of the format of the xml.
352
@applet: A #PanelApplet.
353
@xml: The xml character string describing the popup menu.
355
<!-- # Unused Parameters # -->
356
@verb_list: The list of #BonoboUIVerbs for the menu.
357
@user_data: The user data pointer for the menu.
360
<!-- ##### FUNCTION panel_applet_setup_menu_from_file ##### -->
362
Sets up a popup menu for @applet described by the xml
363
file, @file. See <xref linkend="applet-writing" /> for a description of
364
the format of the xml.
367
@applet: A #PanelApplet.
370
<!-- # Unused Parameters # -->
371
@opt_datadir: The data directory - i.e. ${prefix}/share (optional).
372
@file: The file's name.
373
@opt_app_name: The application's name (optional).
374
@verb_list: The list of #BonoboUIVerbs for the menu.
375
@user_data: The user data pointer for the menu.
378
<!-- ##### FUNCTION panel_applet_factory_main ##### -->
380
A generic 'main' routine for applets. This should not normally be
381
used directly because it is invoked by #PANEL_APPLET_BONOBO_FACTORY.
386
@applet_type: The #GType to instantiate.
387
@callback: The factory callback.
388
@data: The factory user data pointer.
389
@Returns: 0 on success, 1 on failure.
390
<!-- # Unused Parameters # -->
391
@iid: The bonobo-activation iid of the factory.