1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>
Adding a Status Bar
</title>
<meta name="GENERATOR" content=
"Modular DocBook HTML Stylesheet Version 1.45">
<link rel="HOME" title="GTK+ / Gnome Application Development"
href="ggad.html">
<link rel="UP" title="The Main Window: GnomeApp" href=
"cha-main.html">
<link rel="PREVIOUS" title="Menus and Toolbars with
GnomeUIInfo" href="sec-gnomeuiinfo.html">
<link rel="NEXT" title="Online Help" href="sec-help.html">
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink=
"#840084" alink="#0000FF">
<div class="NAVHEADER">
<table width="100%" border="0" bgcolor="#ffffff" cellpadding=
"1" cellspacing="0">
<tr>
<th colspan="4" align="center">
<font color="#000000" size="2">GTK+ / Gnome Application
Development</font>
</th>
</tr>
<tr>
<td width="25%" bgcolor="#ffffff" align="left">
<a href="sec-gnomeuiinfo.html"><font color="#0000ff"
size="2"><b><<< Previous</b></font></a>
</td>
<td width="25%" colspan="2" bgcolor="#ffffff" align=
"center">
<font color="#0000ff" size="2"><b><a href="ggad.html">
<font color="#0000ff" size="2"><b>
Home</b></font></a></b></font>
</td>
<td width="25%" bgcolor="#ffffff" align="right">
<a href="sec-help.html"><font color="#0000ff" size="2">
<b>Next >>></b></font></a>
</td>
</tr>
</table>
</div>
<div class="SECT1">
<h1 class="SECT1">
<a name="Z91">Adding a Status Bar</a>
</h1>
<p>
Adding a status bar is simple enough. Simply call the
aptly-named <tt class="FUNCTION">
gnome_app_set_statusbar</tt> function (<a href=
"z91.html#FL-SETSTATUSBAR">Figure 5</a>) with your
statusbar widget as the second argument.
</p>
<p>
However, there are some additional things to keep in mind.
First, you can use either <tt class="CLASSNAME">
GtkStatusbar</tt> or <tt class="CLASSNAME">GnomeAppBar</tt>
as a statusbar. Second, you probably want to use the
statusbar to display help about menu items as the user
moves over them; Gnome comes with convenience functions to
do this. This section describes the two status bar widgets;
<a href="sec-help.html">the section called <i>Online
Help</i></a> discusses using the statusbar to display menu
item help.
</p>
<div class="FIGURE">
<a name="FL-SETSTATUSBAR"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-SETSTATUSBAR.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-app.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">void <tt class="FUNCTION">
gnome_app_set_statusbar</tt></code>(GnomeApp* <tt
class="PARAMETER"><i>app</i></tt>, GtkWidget* <tt
class="PARAMETER"><i>statusbar</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 5. Installing a Statusbar</b>
</p>
</div>
<div class="SECT2">
<h2 class="SECT2">
<a name="SEC-APPBAR"><tt class="CLASSNAME">
GnomeAppBar</tt></a>
</h2>
<p>
There's no real reason to prefer <tt class="CLASSNAME">
GnomeAppBar</tt> or <tt class="CLASSNAME">
GtkStatusbar</tt>; they simply have different APIs. The
<tt class="CLASSNAME">GnomeAppBar</tt> widget was written
later, with several goals in mind:
</p>
<ul>
<li>
<p>
To simplify the <tt class="CLASSNAME">
GtkStatusbar</tt> API.
</p>
</li>
<li>
<p>
To support an optional progress bar next to the
status bar, similar to Netscape's.
</p>
</li>
<li>
<p>
Eventual support for "interactive" use in the
tradition of the Emacs "minibuffer." This is
unfinished in Gnome 1.0, however.
</p>
</li>
</ul>
<p>
To create a <tt class="CLASSNAME">GnomeAppBar</tt>, use
<tt class="FUNCTION">gnome_appbar_new()</tt> (<a href=
"z91.html#FL-APPBARNEW">Figure 6</a>). The constructor
lets you configure the capabilities of <tt class=
"CLASSNAME">GnomeAppBar</tt>: it can have a progress bar
(or not), have a status text area (or not), and be
interactive (or not). You must have either a status text
area or a progress bar. <span class="STRUCTNAME">
GnomePreferencesType</span> is a kind of extended boolean
value:
</p>
<ul>
<li>
<p>
<span class="STRUCTNAME">
GNOME_PREFERENCES_NEVER</span> means the bar is never
interactive.
</p>
</li>
<li>
<p>
<span class="STRUCTNAME">
GNOME_PREFERENCES_USER</span> means the bar is
interactive if the user has activated that feature as
a Gnome-wide preference.
</p>
</li>
<li>
<p>
<span class="STRUCTNAME">
GNOME_PREFERENCES_ALWAYS</span> means the bar is
always interactive.
</p>
</li>
</ul>
<p>
In Gnome 1.0, interactivity is incompletely implemented;
so avoid <span class="STRUCTNAME">
GNOME_PREFERENCES_ALWAYS</span>. There are some
experimental Gnome functions which provide an abstraction
of certain user interactions, allowing users to choose
between dialogs and the Emacs-style minibuffer approach;
when these are more developed, <span class="STRUCTNAME">
GNOME_PREFERENCES_USER</span> will make sense even if you
don't explicitly use the interactivity. So <span class=
"STRUCTNAME">GNOME_PREFERENCES_USER</span> is the
recommended setting.
</p>
<div class="FIGURE">
<a name="FL-APPBARNEW"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-APPBARNEW.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-appbar.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">GtkWidget* <tt class=
"FUNCTION">gnome_appbar_new</tt></code>(gboolean <tt
class="PARAMETER"><i>has_progress</i></tt>, gboolean
<tt class="PARAMETER"><i>has_status</i></tt>,
GnomePreferencesType <tt class="PARAMETER"><i>
interactivity</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 6. <tt class="CLASSNAME">GnomeAppBar</tt>
Constructor</b>
</p>
</div>
<p>
Using a <span class="STRUCTNAME">GnomeAppBar</span> is
simple. The progress-bar element presents a <tt class=
"CLASSNAME">GtkProgress</tt> interface; to use it, simply
extract the <tt class="CLASSNAME">GtkProgress</tt> with
<tt class="FUNCTION">gnome_appbar_get_progress()</tt> (<a
href="z91.html#FL-APPBARPROGRESS">Figure 7</a>) and use
the <tt class="CLASSNAME">GtkProgress</tt> functions.
Note that you should not make assumptions about the
particular subclass of <tt class="CLASSNAME">
GtkProgress</tt>; in particular, do not cast it to <tt
class="CLASSNAME">GtkProgressBar</tt>.
</p>
<div class="FIGURE">
<a name="FL-APPBARPROGRESS"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-APPBARPROGRESS.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-appbar.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">GtkProgress* <tt class=
"FUNCTION">
gnome_appbar_get_progress</tt></code>(GnomeAppBar*
<tt class="PARAMETER"><i>appbar</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 7. Extracting <span class="STRUCTNAME">
GtkProgress</span></b>
</p>
</div>
<p>
Status texts are stored in a stack; when the bar is
refreshed, the top item of the stack is displayed. The
bar is refreshed anytime you manipulate the stack. So
pushing some text onto the status stack will display that
text.
</p>
<p>
There are two other sources for the status text. You can
set some "default" text; this is displayed if the stack
is empty. The default default text is <span class=
"STRUCTNAME">""</span>. You can also set the status text
without changing the stack; this "transient" text is
immediately displayed, but not stored. On the next
refresh (the next time you push, pop, or set the
default), the text disappears forever, replaced by the
top of the stack.
</p>
<p>
<a href="z91.html#FL-APPBARTEXT">Figure 8</a> lists the
functions to manipulate the status text. <tt class=
"FUNCTION">gnome_appbar_set_status()</tt> is used to set
the transient status text; <tt class="FUNCTION">
gnome_appbar_refresh()</tt> forces a refresh without
changing the stack---this is useful to be sure any
transient text has been cleared. The other functions
should be obvious.
</p>
<p>
Note that you can use the <tt class="CLASSNAME">
GnomeAppBar</tt> as a simple label---one message at a
time, always replacing the previous message---just stick
to either setting the default or setting the transient
text, and never use the stack.
</p>
<div class="FIGURE">
<a name="FL-APPBARTEXT"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-APPBARTEXT.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-appbar.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gnome_appbar_set_status</tt></code>(GnomeAppBar* <tt
class="PARAMETER"><i>appbar</i></tt>, const gchar*
<tt class="PARAMETER"><i>status</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gnome_appbar_set_default</tt></code>(GnomeAppBar* <tt
class="PARAMETER"><i>appbar</i></tt>, const gchar*
<tt class="PARAMETER"><i>
default_status</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">gnome_appbar_push</tt></code>(GnomeAppBar*
<tt class="PARAMETER"><i>appbar</i></tt>, const
gchar* <tt class="PARAMETER"><i>
status</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">gnome_appbar_pop</tt></code>(GnomeAppBar*
<tt class="PARAMETER"><i>appbar</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gnome_appbar_clear_stack</tt></code>(GnomeAppBar* <tt
class="PARAMETER"><i>appbar</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gnome_appbar_refresh</tt></code>(GnomeAppBar* <tt
class="PARAMETER"><i>appbar</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 8. Setting <tt class="CLASSNAME">
GnomeAppBar</tt> Text</b>
</p>
</div>
</div>
<div class="SECT2">
<h2 class="SECT2">
<a name="SEC-GTKSTATUSBAR"><tt class="CLASSNAME">
GtkStatusbar</tt></a>
</h2>
<p>
<tt class="CLASSNAME">GtkStatusbar</tt> has no default
text or "transient" text, as in <tt class="CLASSNAME">
GnomeAppBar</tt>; it only has a message stack. However,
each message is tagged with a "context" identified by a
string. When you pop a message off the stack, you must
specify a context; the topmost message <i class=
"EMPHASIS">in that context</i> is popped. If there are no
messages in the context you specify, no text is popped.
In essence, the <tt class="CLASSNAME">GtkStatusbar</tt>
"pop" operation works only within namespaces. There's no
way to unconditionally pop all messages or
unconditionally pop the topmost message.
</p>
<p>
In principle this lets different parts of the program use
the statusbar without interfering with one another.
However, in my experience there's no need for this. For
example, Netscape doesn't even have a stack for its
statusbar; its statusbar is simply a label. In general it
is poor interface design to make anything <i class=
"EMPHASIS">essential</i> appear in the statusbar, since
the user might not notice it. Accidentally deleting a
message should not be a major worry.
</p>
<p>
<a href="z91.html#FL-STATUSBAR">Figure 9</a> shows the
<tt class="CLASSNAME">GtkStatusbar</tt> functions.
</p>
<p>
To use the statusbar:
</p>
<ol type="1">
<li>
<p>
First obtain a context ID with <tt class="FUNCTION">
gtk_statusbar_get_context_id()</tt>; the <span class=
"STRUCTNAME">context_description</span> argument can
be any string you like.
</p>
</li>
<li>
<p>
Push a message onto the statusbar using <tt class=
"FUNCTION">gtk_statusbar_push()</tt>; the message is
tagged with the given context ID. The return value is
a message ID you can use to remove the message.
(Unlike <tt class="CLASSNAME">GnomeAppBar</tt>, <tt
class="CLASSNAME">GtkStatusbar</tt> lets you remove a
message that isn't on top of the stack.)
</p>
</li>
<li>
<p>
Eventually remove the message with <tt class=
"FUNCTION">gtk_statusbar_remove()</tt> or <tt class=
"FUNCTION">gtk_statusbar_pop()</tt>. The former
refers to a specific message by ID, the latter
removes the topmost message in the supplied
context.
</p>
</li>
</ol>
<p>
Note that <tt class="FUNCTION">gtk_statusbar_push()</tt>
pushes a message on top of all other messages, even those
in other contexts; but <tt class="FUNCTION">
gtk_statusbar_pop()</tt> will only pop from the context
supplied. Contexts do not refer to separate stacks, they
merely restrict which messages you are permitted to pop.
</p>
<div class="FIGURE">
<a name="FL-STATUSBAR"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-STATUSBAR.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <gtk/gtkstatusbar.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">GtkWidget* <tt class=
"FUNCTION">
gtk_statusbar_new</tt></code>(void);</code>
</p>
<p>
<code><code class="FUNCDEF">guint <tt class=
"FUNCTION">
gtk_statusbar_get_context_id</tt></code>(GtkStatusbar*
<tt class="PARAMETER"><i>statusbar</i></tt>, const
gchar* <tt class="PARAMETER"><i>
context_description</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">guint <tt class=
"FUNCTION">
gtk_statusbar_push</tt></code>(GtkStatusbar* <tt
class="PARAMETER"><i>statusbar</i></tt>, guint <tt
class="PARAMETER"><i>context_id</i></tt>, const
gchar* <tt class="PARAMETER"><i>
text</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gtk_statusbar_pop</tt></code>(GtkStatusbar* <tt
class="PARAMETER"><i>statusbar</i></tt>, guint <tt
class="PARAMETER"><i>context_id</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gtk_statusbar_remove</tt></code>(GtkStatusbar* <tt
class="PARAMETER"><i>statusbar</i></tt>, guint <tt
class="PARAMETER"><i>context_id</i></tt>, guint <tt
class="PARAMETER"><i>message_id</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 9. <tt class="CLASSNAME">
GtkStatusbar</tt></b>
</p>
</div>
</div>
</div>
<div class="NAVFOOTER">
<br>
<br>
<table width="100%" border="0" bgcolor="#ffffff" cellpadding=
"1" cellspacing="0">
<tr>
<td width="25%" bgcolor="#ffffff" align="left">
<a href="sec-gnomeuiinfo.html"><font color="#0000ff"
size="2"><b><<< Previous</b></font></a>
</td>
<td width="25%" colspan="2" bgcolor="#ffffff" align=
"center">
<font color="#0000ff" size="2"><b><a href="ggad.html">
<font color="#0000ff" size="2"><b>
Home</b></font></a></b></font>
</td>
<td width="25%" bgcolor="#ffffff" align="right">
<a href="sec-help.html"><font color="#0000ff" size="2">
<b>Next >>></b></font></a>
</td>
</tr>
<tr>
<td colspan="2" align="left">
<font color="#000000" size="2"><b>Menus and Toolbars
with <span class="STRUCTNAME">
GnomeUIInfo</span></b></font>
</td>
<td colspan="2" align="right">
<font color="#000000" size="2"><b>Online
Help</b></font>
</td>
</tr>
</table>
</div>
</body>
</html>
|
