← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/gnome-panel/oneiric

« back to all changes in this revision

Viewing changes to doc/reference/panel-applet/tmpl/panel-applet.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2011-05-30 11:04:49 UTC
  • mfrom: (1.3.4 upstream)
  • mto: This revision was merged to the branch mainline in revision 204.
  • Revision ID: james.westby@ubuntu.com-20110530110449-ut1tc5t61rpvf9e3
Tags: upstream-3.0.2
Import upstream version 3.0.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/reference/panel-applet/tmpl/panel-applet.sgml
1
 
<!-- ##### SECTION Title ##### -->
2
 
PanelApplet
3
 
 
4
 
<!-- ##### SECTION Short_Description ##### -->
5
 
The PanelApplet object.
6
 
 
7
 
<!-- ##### SECTION Long_Description ##### -->
8
 
<para>
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.
12
 
</para>
13
 
 
14
 
<para>
15
 
A #PanelApplet is associated with a #BonoboControl. The control makes
16
 
the cross process UI emmbedding required by applets possible.
17
 
</para>
18
 
 
19
 
<!-- ##### SECTION See_Also ##### -->
20
 
<para>
21
 
 
22
 
</para>
23
 
 
24
 
<!-- ##### SECTION Stability_Level ##### -->
25
 
 
26
 
 
27
 
<!-- ##### SECTION Image ##### -->
28
 
 
29
 
 
30
 
<!-- ##### STRUCT PanelApplet ##### -->
31
 
<para>
32
 
The #PanelApplet struct contains private data only.
33
 
</para>
34
 
 
35
 
 
36
 
<!-- ##### SIGNAL PanelApplet::change-background ##### -->
37
 
<para>
38
 
Emitted when the background of the panel changes. Use @type to
39
 
determine which, if any, of @color and @pimxap is valid.
40
 
</para>
41
 
 
42
 
@panelapplet: The object which received the signal.
43
 
@arg1: 
44
 
@arg2: 
45
 
@arg3: 
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
50
 
 
51
 
<!-- ##### SIGNAL PanelApplet::change-orient ##### -->
52
 
<para>
53
 
Emitted when the orientation of the panel changes.
54
 
</para>
55
 
 
56
 
@panelapplet: The object which received the signal.
57
 
@orient: The new #PanelAppletOrient of the applet.
58
 
 
59
 
<!-- ##### SIGNAL PanelApplet::change-size ##### -->
60
 
<para>
61
 
Emitted when the size of the panel changes.
62
 
</para>
63
 
 
64
 
<para>
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().
69
 
</para>
70
 
 
71
 
@panelapplet: The object which received the signal.
72
 
@size: The size hint of the panel.
73
 
 
74
 
<!-- ##### SIGNAL PanelApplet::move-focus-out-of-applet ##### -->
75
 
<para>
76
 
Emitted when the applet has lost focus. This signal is used internally and is not meant to be used by applets themselves.
77
 
</para>
78
 
 
79
 
@panelapplet: The object which received the signal.
80
 
@direction: The direction of focus movement.
81
 
 
82
 
<!-- ##### ARG PanelApplet:background ##### -->
83
 
<para>
84
 
 
85
 
</para>
86
 
 
87
 
<!-- ##### ARG PanelApplet:closure ##### -->
88
 
<para>
89
 
 
90
 
</para>
91
 
 
92
 
<!-- ##### ARG PanelApplet:connection ##### -->
93
 
<para>
94
 
 
95
 
</para>
96
 
 
97
 
<!-- ##### ARG PanelApplet:flags ##### -->
98
 
<para>
99
 
 
100
 
</para>
101
 
 
102
 
<!-- ##### ARG PanelApplet:id ##### -->
103
 
<para>
104
 
 
105
 
</para>
106
 
 
107
 
<!-- ##### ARG PanelApplet:locked ##### -->
108
 
<para>
109
 
 
110
 
</para>
111
 
 
112
 
<!-- ##### ARG PanelApplet:locked-down ##### -->
113
 
<para>
114
 
 
115
 
</para>
116
 
 
117
 
<!-- ##### ARG PanelApplet:orient ##### -->
118
 
<para>
119
 
 
120
 
</para>
121
 
 
122
 
<!-- ##### ARG PanelApplet:prefs-key ##### -->
123
 
<para>
124
 
 
125
 
</para>
126
 
 
127
 
<!-- ##### ARG PanelApplet:size ##### -->
128
 
<para>
129
 
 
130
 
</para>
131
 
 
132
 
<!-- ##### ARG PanelApplet:size-hints ##### -->
133
 
<para>
134
 
 
135
 
</para>
136
 
 
137
 
<!-- ##### ENUM PanelAppletOrient ##### -->
138
 
<para>
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.
143
 
</para>
144
 
 
145
 
@PANEL_APPLET_ORIENT_UP: 
146
 
@PANEL_APPLET_ORIENT_DOWN: 
147
 
@PANEL_APPLET_ORIENT_LEFT: 
148
 
@PANEL_APPLET_ORIENT_RIGHT: 
149
 
 
150
 
<!-- ##### ENUM PanelAppletBackgroundType ##### -->
151
 
<para>
152
 
The #PanelAppletBackgroundType enumerated type specifies the type of
153
 
background of a panel.
154
 
</para>
155
 
 
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,
158
 
background.
159
 
@PANEL_PIXMAP_BACKGROUND:  The panel has either an image background
160
 
or is translucent.
161
 
 
162
 
<!-- ##### ENUM PanelAppletFlags ##### -->
163
 
<para>
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.
166
 
</para>
167
 
 
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
178
 
flag.
179
 
 
180
 
<!-- ##### USER_FUNCTION PanelAppletFactoryCallback ##### -->
181
 
<para>
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.
185
 
</para>
186
 
 
187
 
<para>
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
190
 
and initialized.
191
 
</para>
192
 
 
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.
197
 
 
198
 
 
199
 
<!-- ##### FUNCTION panel_applet_new ##### -->
200
 
<para>
201
 
Creates a new #PanelApplet. This function is typically not
202
 
useful as the applet is created before the #PanelAppletFactoryCallback
203
 
is invoked.
204
 
</para>
205
 
 
206
 
@void: 
207
 
@Returns: The #PanelApplet.
208
 
 
209
 
 
210
 
<!-- ##### FUNCTION panel_applet_get_orient ##### -->
211
 
<para>
212
 
Get the current orientation of the applet.
213
 
</para>
214
 
 
215
 
@applet: The #PanelApplet.
216
 
@Returns: The orientation of the applet.
217
 
 
218
 
 
219
 
<!-- ##### FUNCTION panel_applet_get_size ##### -->
220
 
<para>
221
 
Get the current size hint for the panel. The size hint is
222
 
not useful for most applets.
223
 
</para>
224
 
 
225
 
<para>
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.
230
 
</para>
231
 
 
232
 
@applet: The #PanelApplet.
233
 
@Returns: The panel's size hint.
234
 
 
235
 
 
236
 
<!-- ##### FUNCTION panel_applet_get_background ##### -->
237
 
<para>
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.
245
 
</para>
246
 
 
247
 
<!-- FIXME: give an example of how to use this -->
248
 
 
249
 
@applet: A #PanelApplet.
250
 
@color: A #GdkColor to be filled in.
251
 
@pixmap: Returned #GdkPixmap.
252
 
@Returns: The background type.
253
 
 
254
 
 
255
 
<!-- ##### FUNCTION panel_applet_get_preferences_key ##### -->
256
 
<para>
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
261
 
more information.
262
 
</para>
263
 
 
264
 
@applet: The #PanelApplet.
265
 
@Returns: A GConf path.
266
 
 
267
 
 
268
 
<!-- ##### FUNCTION panel_applet_add_preferences ##### -->
269
 
<para>
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.
275
 
</para>
276
 
 
277
 
<para>
278
 
If you pass %NULL for @opt_error, this function will print
279
 
a warning message from any #GError which GConf may return.
280
 
</para>
281
 
 
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.
286
 
 
287
 
 
288
 
<!-- ##### FUNCTION panel_applet_get_flags ##### -->
289
 
<para>
290
 
Retrieve the #PanelAppletFlags associated with the applet.
291
 
</para>
292
 
 
293
 
@applet: The #PanelApplet.
294
 
@Returns: The #PanelAppletFlags.
295
 
 
296
 
 
297
 
<!-- ##### FUNCTION panel_applet_set_flags ##### -->
298
 
<para>
299
 
Set the #PanelAppletFlags associated with the applet. See
300
 
#PanelAppletFlags for more details on the possible uses of
301
 
these flags.
302
 
</para>
303
 
 
304
 
@applet: The #PanelApplet.
305
 
@flags: The #PanelAppletFlags to associate.
306
 
 
307
 
 
308
 
<!-- ##### FUNCTION panel_applet_set_size_hints ##### -->
309
 
<para>
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).
313
 
</para>
314
 
 
315
 
<para>
316
 
The panel will endeavour to allocate the applet a size
317
 
in one of the (@base + max, @base + min) ranges.
318
 
</para>
319
 
 
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.
325
 
 
326
 
 
327
 
<!-- ##### FUNCTION panel_applet_get_locked_down ##### -->
328
 
<para>
329
 
Check if the @applet is locked down. A locked down applet should not allow any change to its configuration.
330
 
</para>
331
 
 
332
 
@applet: The #PanelApplet.
333
 
@Returns: %TRUE if the @applet is locked down, %FALSE otherwise.
334
 
 
335
 
 
336
 
<!-- ##### FUNCTION panel_applet_request_focus ##### -->
337
 
<para>
338
 
Set keyboard focus to @applet.
339
 
</para>
340
 
 
341
 
@applet: The #PanelApplet.
342
 
@timestamp: timestamp of the event triggering the window focus
343
 
 
344
 
 
345
 
<!-- ##### FUNCTION panel_applet_setup_menu ##### -->
346
 
<para>
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.
350
 
</para>
351
 
 
352
 
@applet: A #PanelApplet.
353
 
@xml: The xml character string describing the popup menu.
354
 
@action_group: 
355
 
<!-- # Unused Parameters # -->
356
 
@verb_list: The list of #BonoboUIVerbs for the menu.
357
 
@user_data: The user data pointer for the menu.
358
 
 
359
 
 
360
 
<!-- ##### FUNCTION panel_applet_setup_menu_from_file ##### -->
361
 
<para>
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.
365
 
</para>
366
 
 
367
 
@applet: A #PanelApplet.
368
 
@filename: 
369
 
@action_group: 
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.
376
 
 
377
 
 
378
 
<!-- ##### FUNCTION panel_applet_factory_main ##### -->
379
 
<para>
380
 
A generic 'main' routine for applets. This should not normally be
381
 
used directly because it is invoked by #PANEL_APPLET_BONOBO_FACTORY.
382
 
</para>
383
 
 
384
 
@factory_id: 
385
 
@out_process: 
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.
392
 
 
393