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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>
Special Dialog Types
</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="User Communication: Dialogs" href=
"cha-dialogs.html">
<link rel="PREVIOUS" title="A Dialog Example" href="z101.html">
<link rel="NEXT" title="Convenience Routines" href=
"sec-dialogs-convenience.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="z101.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-dialogs-convenience.html"><font color=
"#0000ff" size="2"><b>Next >>></b></font></a>
</td>
</tr>
</table>
</div>
<div class="SECT1">
<h1 class="SECT1">
<a name="CHA-DIALOGS-SPECIAL">Special Dialog Types</a>
</h1>
<p>
This section describes some special kinds of dialog that
exist for your convenience, and for UI consistency. Of
course nearly everything said so far about <tt class=
"CLASSNAME">GnomeDialog</tt> also applies to its
subclasses.
</p>
<div class="SECT2">
<h2 class="SECT2">
<a name="SEC-GNOMEABOUT"><tt class="CLASSNAME">
GnomeAbout</tt></a>
</h2>
<p>
Gnome applications should have an "About Foo" menu item
which displays this widget (where "Foo" is the name of
your application). Using it is ridiculously easy; there's
only one function involved, <tt class="FUNCTION">
gnome_about_new()</tt> (<a href=
"cha-dialogs-special.html#FL-ABOUT">Figure 7</a>). The
arguments are, respectively: the title of your
application, the version of your application, a one-line
copyright notice, a <span class="STRUCTNAME">
NULL</span>-terminated vector of author's names, a short
paragraph saying anything you want to say, and an image
filename to display as your application's logo. Only the
<span class="STRUCTNAME">authors</span> argument is
required; the others can be <span class="STRUCTNAME">
NULL</span>, but your dialog will look fairly strange if
all of them are.
</p>
<div class="FIGURE">
<a name="FL-ABOUT"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-ABOUT.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-about.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">GtkWidget* <tt class=
"FUNCTION">gnome_about_new</tt></code>(const gchar*
<tt class="PARAMETER"><i>title</i></tt>, const gchar*
<tt class="PARAMETER"><i>version</i></tt>, const
gchar* <tt class="PARAMETER"><i>copyright</i></tt>,
const gchar** <tt class="PARAMETER"><i>
authors</i></tt>, const gchar* <tt class="PARAMETER">
<i>comments</i></tt>, const gchar* <tt class=
"PARAMETER"><i>logo</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 7. <tt class="CLASSNAME">GnomeAbout</tt></b>
</p>
</div>
<p>
<tt class="CLASSNAME">GnomeAbout</tt> automatically
closes when clicked, so you don't really need to worry
about it; just create and show the dialog. Remember to
ensure only one instance exists at any given time, as
explained in <a href=
"cha-dialogs.html#SEC-DIALOGS-TOUCHES">the section called
<i>Finishing Touches</i></a>.
</p>
<p>
Here's a menu item callback to show an about dialog, from
the Gnome calendar application:
</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="PROGRAMLISTING">
static void
about_calendar_cmd (GtkWidget *widget, void *data)
{
GtkWidget *about;
const gchar *authors[] = {
"Miguel de Icaza <miguel@kernel.org>",
"Federico Mena <federico@gimp.org>",
"Arturo Espinosa <arturo@nuclecu.unam.mx>",
NULL
};
about = gnome_about_new (_("Gnome Calendar"), VERSION,
"(C) 1998 the Free Software Foundation",
authors,
_("The GNOME personal calendar and schedule manager."),
NULL);
gtk_window_set_modal (GTK_WINDOW (about), TRUE);
gtk_widget_show (about);
}
</pre>
</td>
</tr>
</table>
<p>
Note that the authors give both their name and email
address; that way people can use the dialog to decide
where to send hate mail and bug reports. (Or thank you
notes!) The <tt class="FUNCTION">VERSION</tt> macro comes
from <tt class="FILENAME">config.h</tt>, and is defined
by <tt class="FILENAME">configure</tt>. The Gnome
Calendar authors chose to prevent multiple dialog
instances by making the dialog modal---the user can't
re-select the menu item while the dialog is open. It is
probably better to use the technique described in <a
href="cha-dialogs.html#SEC-DIALOGS-TOUCHES">the section
called <i>Finishing Touches</i></a>, so the dialog is
deiconified and raised if the user reselects the menu
item.
</p>
</div>
<div class="SECT2">
<h2 class="SECT2">
<a name="SEC-PROPERTYBOX"><tt class="CLASSNAME">
GnomePropertyBox</tt></a>
</h2>
<p>
<tt class="CLASSNAME">GnomePropertyBox</tt> is used for
application preferences, or to edit the properties of a
user-visible object. It's a dialog with a <tt class=
"CLASSNAME">GtkNotebook</tt> inside, and four buttons:
"OK," "Apply," "Close," and "Help." The "OK" button is
equivalent in all respects to clicking "Apply" followed
by "Close." "Apply" should immediately make any changes
the user has requested using the widgets you've placed in
the <tt class="CLASSNAME">GnomePropertyBox</tt>.
Unsurprisingly, "Help" should display help. "OK" and
"Close" are handled automatically by the property box, so
you can ignore them.
</p>
<p>
You don't need to deal with the property box's buttons
directly; instead <tt class="CLASSNAME">
GnomePropertyBox</tt> emits <span class="SYMBOL">
"apply"</span> and <span class="SYMBOL">"help"</span>
signals. Handlers for these should look like:
</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="PROGRAMLISTING">
void handler(GtkWidget* propertybox, gint page_num, gpointer data);
</pre>
</td>
</tr>
</table>
<p>
<span class="STRUCTNAME">page_num</span> is the
currently-active page of the <tt class="CLASSNAME">
GtkNotebook</tt> inside the dialog. (<tt class=
"CLASSNAME">GtkNotebook</tt> pages are numbered from
front to back, starting with 0; the front page is the
first one you add to the notebook.) For <span class=
"SYMBOL">"help"</span>, the page number lets you provide
context-sensitive help. When the user clicks the "Apply"
or "OK" button, the <span class="SYMBOL">"apply"</span>
signal is emitted once per page, then emitted a final
time with <span class="STRUCTNAME">-1</span> as the <span
class="STRUCTNAME">page_num</span> value. The multiple
emissions of <span class="SYMBOL">"apply"</span> are
something of an anachronism, because it has become de
facto standard behavior to simply apply all pages when
the <span class="STRUCTNAME">-1</span> page number is
received.
</p>
<p>
To create a property box, you first create the dialog,
then create each page and add it. Creating a <tt class=
"CLASSNAME">GnomePropertyBox</tt> is straightforward; <tt
class="FUNCTION">gnome_property_box_new()</tt> takes no
arguments.
</p>
<div class="FIGURE">
<a name="FL-PROPERTYBOX"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-PROPERTYBOX.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-propertybox.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">GtkWidget* <tt class=
"FUNCTION">
gnome_property_box_new</tt></code>(void);</code>
</p>
<p>
<code><code class="FUNCDEF">gint <tt class=
"FUNCTION">
gnome_property_box_append_page</tt></code>(GnomePropertyBox*
<tt class="PARAMETER"><i>pb</i></tt>, GtkWidget* <tt
class="PARAMETER"><i>page</i></tt>, GtkWidget* <tt
class="PARAMETER"><i>tab</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 8. <tt class="CLASSNAME">
GnomePropertyBox</tt></b>
</p>
</div>
<p>
You then create a widget for each page (probably a
container with a number of controls inside), and append
it to the property box with <tt class="FUNCTION">
gnome_property_box_append_page()</tt> (<a href=
"cha-dialogs-special.html#FL-PROPERTYBOX">Figure 8</a>).
Its <span class="STRUCTNAME">page</span> argument is the
widget to place inside the new notebook page, and <span
class="STRUCTNAME">tab</span> is a widget to use on the
notebook tab. The page number of the newly-added page is
returned, so you don't have to keep a count yourself.
</p>
<p>
It's your responsibility to keep track of any user
interaction with the contents of each page. When the user
changes a setting, you must notify the property box; it
uses this information to set the "Apply" and "OK" buttons
sensitive if and only if there are unapplied changes. The
relevant routines are in <a href=
"cha-dialogs-special.html#FL-PROPBOXCHANGED">Figure
9</a>.
</p>
<div class="FIGURE">
<a name="FL-PROPBOXCHANGED"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-PROPBOXCHANGED.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-propertybox.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gnome_property_box_changed</tt></code>(GnomePropertyBox*
<tt class="PARAMETER"><i>pb</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gnome_property_box_set_state</tt></code>(GnomePropertyBox*
<tt class="PARAMETER"><i>pb</i></tt>, gboolean <tt
class="PARAMETER"><i>setting</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 9. Property Box State</b>
</p>
</div>
<p>
<tt class="FUNCTION">gnome_property_box_changed()</tt>
tells the property box about changes; the property box
will automatically unset its internal "changes pending"
flag when <span class="SYMBOL">"apply"</span> is emitted.
If you need to change that internal flag for some reason
(unlikely), you can use <tt class="FUNCTION">
gnome_property_box_set_state()</tt>.
</p>
</div>
<div class="SECT2">
<h2 class="SECT2">
<a name="SEC-MESSAGEBOX"><tt class="CLASSNAME">
GnomeMessageBox</tt></a>
</h2>
<p>
A <tt class="CLASSNAME">GnomeMessageBox</tt> is a <tt
class="CLASSNAME">GnomeDialog</tt> subclass that conveys
a short message or asks a simple question. Gnome provides
several "types" of message box; they have different icons
next to the text, and corresponding titles. The icons
look nice, and allow users to quickly classify the
message being presented.
</p>
<p>
The API is very simple; there are no functions specific
to <tt class="CLASSNAME">GnomeMessageBox</tt> other than
the constructor, in <a href=
"cha-dialogs-special.html#FL-MSGBOX">Figure 10</a>. The
first argument is the message to display; the second is a
string encoding the message box type. Then you can list
any buttons, just as you would with <tt class="FUNCTION">
gnome_dialog_new()</tt>. Unlike the unadorned <tt class=
"CLASSNAME">GnomeDialog</tt>, <tt class="CLASSNAME">
GnomeMessageBox</tt> closes on any button click by
default. Of course you can change this behavior using <tt
class="FUNCTION">gnome_dialog_set_close()</tt>.
</p>
<div class="FIGURE">
<a name="FL-MSGBOX"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-MSGBOX.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-messagebox.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">GtkWidget* <tt class=
"FUNCTION">gnome_message_box_new</tt></code> (const
gchar* <tt class="PARAMETER"><i>message</i></tt>,
const gchar* <tt class="PARAMETER"><i>
messagebox_type</i></tt>, <tt class="PARAMETER"><i>
...</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 10. Message Box Constructor</b>
</p>
</div>
<p>
Macros are provided for the available message box types.
</p>
<ul>
<li>
<p>
<tt class="FUNCTION">GNOME_MESSAGE_BOX_INFO</tt>
should be used for "FYI" messages.
</p>
</li>
<li>
<p>
<tt class="FUNCTION">GNOME_MESSAGE_BOX_WARNING</tt>
should be used for nonfatal errors.
</p>
</li>
<li>
<p>
<tt class="FUNCTION">GNOME_MESSAGE_BOX_ERROR</tt>
should be used if an operation fails entirely.
</p>
</li>
<li>
<p>
<tt class="FUNCTION">GNOME_MESSAGE_BOX_QUESTION</tt>
should be used if your dialog asks a question.
</p>
</li>
<li>
<p>
<tt class="FUNCTION">GNOME_MESSAGE_BOX_GENERIC</tt>
should be used if none of the other types apply.
</p>
</li>
</ul>
<p>
Here's how you might use <tt class="CLASSNAME">
GnomeMessageBox</tt>:
</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="PROGRAMLISTING">
GtkWidget * mbox;
mbox = gnome_message_box_new (message,
GNOME_MESSAGE_BOX_INFO,
GNOME_STOCK_BUTTON_OK,
NULL);
gtk_widget_show (mbox);
</pre>
</td>
</tr>
</table>
<p>
Notice that <tt class="CLASSNAME">GnomeMessageBox</tt>,
like most <tt class="CLASSNAME">GnomeDialog</tt>
subclasses but not <tt class="CLASSNAME">GnomeDialog</tt>
itself, automatically closes when clicked. So there is no
need to destroy it by hand.
</p>
</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="z101.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-dialogs-convenience.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>A Dialog
Example</b></font>
</td>
<td colspan="2" align="right">
<font color="#000000" size="2"><b>Convenience
Routines</b></font>
</td>
</tr>
</table>
</div>
</body>
</html>
|
