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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>
Online Help
</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="Adding a Status Bar" href=
"z91.html">
<link rel="NEXT" title="Finishing Touches" href="z94.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="z91.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="z94.html"><font color="#0000ff" size="2"><b>
Next >>></b></font></a>
</td>
</tr>
</table>
</div>
<div class="SECT1">
<h1 class="SECT1">
<a name="SEC-HELP">Online Help</a>
</h1>
<p>
Finished applications should provide online help and
documentation. Of course, the first "line of defense" is to
have an intuitive interface in the first place. But you
should give users a way to get more information if they
need it.
</p>
<p>
This section describes the two major ways you can explain
your interface to users:
</p>
<ul>
<li>
<p>
By writing documentation, and providing buttons and
menu items that jump to relevant sections. For example,
the "Help" button in a properties dialog should bring
up a help window describing the dialog.
</p>
</li>
<li>
<p>
By adding "tooltips," explanatory text that appears if
the mouse remains motionless over a widget for a short
time. For menu items, explanatory text appears in the
window's status bar as the user moves over the
item.
</p>
</li>
</ul>
<div class="SECT2">
<h2 class="SECT2">
<a name="Z92">Gnome Documentation and Help Menu Items</a>
</h2>
<p>
The Gnome documentation installation process was
described in <a href="z72.html#SEC-INSTALLDOCS">the
section called <i>Documentation</i> in the chapter called
<i>Creating Your Source Tree</i></a>. Recall that
applications install documentation in HTML format in
directories named after locales. Each locale directory
contains both help files and a <tt class="FILENAME">
topic.dat</tt> file indexing the available help topics.
</p>
<p>
Gnome makes it ridiculously easy to create menu items for
the nodes in <tt class="FILENAME">topic.dat</tt>. Simply
create a help menu using the <tt class="FUNCTION">
GNOMEUIINFO_HELP()</tt> macro, like this:
</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="PROGRAMLISTING">
static GnomeUIInfo help_menu [] = {
GNOMEUIINFO_HELP ("gnome-hello"),
GNOMEUIINFO_MENU_ABOUT_ITEM(about_cb, NULL),
GNOMEUIINFO_END
};
</pre>
</td>
</tr>
</table>
<p>
The single argument to <tt class="FUNCTION">
GNOMEUIINFO_HELP()</tt> is the name of the directory
where you've installed your help files. The Gnome
libraries will read <tt class="FILENAME">topic.dat</tt>
for the user's locale (or the C locale if there is no
translation) and create a menu item for each topic.
Activating these menu items will launch a help browser to
display the appropriate URL. (Users can configure the
exact browser Gnome will launch.) If <tt class=
"FILENAME">topic.dat</tt> isn't found, Gnome creates no
menu items.
</p>
<p>
In other contexts, you will have to manually set up
widgets and callbacks to open your help files. Gnome
provides some helper functions; the two most important
ones are shown in <a href="sec-help.html#FL-GNOMEHELP">
Figure 10</a>. <tt class="FUNCTION">
gnome_help_file_find_file()</tt> returns the complete
path to a help file, given the name of your help
directory and the name of a help file (relative to one of
the locale directories). If the help file is not found,
<span class="STRUCTNAME">NULL</span> is returned. For
example:
</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="PROGRAMLISTING">
gchar* helpfile;
helpfile = gnome_help_file_find_file("gnome-hello",
"gnome-hello.html");
if (helpfile != NULL)
{
gchar* url;
url = g_strconcat("file:", helpfile, NULL);
gnome_help_goto(NULL, url);
g_free(url);
g_free(helpfile);
}
else
{
gnome_error_dialog(_("Couldn't find the GnomeHello manual!"));
}
</pre>
</td>
</tr>
</table>
<p>
<tt class="FUNCTION">gnome_help_file_find_file()</tt>
takes the user's locale into account when generating the
help file's pathname.
</p>
<p>
<tt class="FUNCTION">gnome_help_goto()</tt> simply
directs the help browser to a URL. You must prepend <span
class="STRUCTNAME">"file:"</span> to a path to make it a
valid URL before calling this function. The first
argument to <tt class="FUNCTION">gnome_help_goto()</tt>
is ignored; this makes it convenient to connect <tt
class="FUNCTION">gnome_help_goto()</tt> as a callback
function, for example to a button's <span class="SYMBOL">
"clicked"</span> signal.
</p>
<p>
<tt class="FILENAME">libgnome/gnome-help.h</tt> contains
a few other variants of <tt class="FUNCTION">
gnome_help_goto()</tt> suited for connection to signals
with different signatures; in particular, there's a
callback there for the <tt class="CLASSNAME">
GnomePropertyBox</tt>'s <span class="SYMBOL">
"help"</span> signal.
</p>
<p>
One caveat: the Gnome libraries look for files in the
Gnome installation prefix, not in your application's
installation prefix. For now, users should install Gnome
applications and libraries in the same place. This was
done for simplicity's sake when Gnome was much smaller;
it's clearly the wrong behavior and will be fixed in a
future version. If you use Gnome library functions such
as <tt class="FUNCTION">gnome_help_file_find_file()</tt>,
your application will automatically take advantage of
this future Gnome enhancement.
</p>
<div class="FIGURE">
<a name="FL-GNOMEHELP"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-GNOMEHELP.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnome/gnome-help.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">gchar* <tt class=
"FUNCTION">
gnome_help_file_find_file</tt></code>(const gchar*
<tt class="PARAMETER"><i>app</i></tt>, const gchar*
<tt class="PARAMETER"><i>filename</i></tt>);</code>
</p>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">gnome_help_goto</tt></code>(void* <tt
class="PARAMETER"><i>ignore</i></tt>, const gchar*
<tt class="PARAMETER"><i>url</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 10. Help Files</b>
</p>
</div>
</div>
<div class="SECT2">
<h2 class="SECT2">
<a name="Z93">Menu Hints</a>
</h2>
<p>
As the user moves over your application menus, a short
description of each menu item should appear in the
statusbar. Gnome makes this very easy; just call the <tt
class="FUNCTION">gnome_app_install_menu_hints()</tt> (<a
href="sec-help.html#FL-MENUHINTS">Figure 11</a>) after
you create your menus and statusbar. The <span class=
"STRUCTNAME">GnomeUIInfo</span> struct passed to this
function must have its <span class="STRUCTNAME">
widget</span> fields filled in by one of the
menu-creation functions, and the <span class=
"STRUCTNAME">GnomeApp</span> must have a <span class=
"STRUCTNAME">GnomeAppBar</span> or <span class=
"STRUCTNAME">GtkStatusbar</span> in its statusbar slot.
</p>
<div class="FIGURE">
<a name="FL-MENUHINTS"></a>
<div class="FUNCSYNOPSIS">
<a name="FL-MENUHINTS.SYNOPSIS"></a>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="FUNCSYNOPSISINFO">
#include <libgnomeui/gnome-app-helper.h>
</pre>
</td>
</tr>
</table>
<p>
<code><code class="FUNCDEF">void <tt class=
"FUNCTION">
gnome_app_install_menu_hints</tt></code>(GnomeApp*
<tt class="PARAMETER"><i>app</i></tt>, GnomeUIInfo*
<tt class="PARAMETER"><i>uiinfo</i></tt>);</code>
</p>
</div>
<p>
<b>Figure 11. Installing Menu Hints</b>
</p>
</div>
</div>
<div class="SECT2">
<h2 class="SECT2">
<a name="SEC-TOOLTIPS">Tooltips</a>
</h2>
<p>
GTK+ provides tooltip functionality; you simply create a
<span class="STRUCTNAME">GtkTooltips</span> and attach it
to a widget. I like to use the following convenience
function in my applications:
</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="PROGRAMLISTING">
void
set_tooltip(GtkWidget* w, const gchar* tip)
{
GtkTooltips* t = gtk_tooltips_new();
gtk_tooltips_set_tip (t, w, tip, NULL);
}
</pre>
</td>
</tr>
</table>
<p>
The <span class="STRUCTNAME">GtkTooltips</span> will be
destroyed along with the widget. Make your tooltips long
rather than short; there's no reason to skimp on the
amount of information you provide here. You should get in
the habit of calling <tt class="FUNCTION">
set_tooltip()</tt> every time you create a button or
other widget that could benefit from it.
</p>
<p>
Note that toolbars created from a <span class=
"STRUCTNAME">GnomeUIInfo</span> template will have
tooltips installed automatically.
</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="z91.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="z94.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>Adding a Status
Bar</b></font>
</td>
<td colspan="2" align="right">
<font color="#000000" size="2"><b>Finishing
Touches</b></font>
</td>
</tr>
</table>
</div>
</body>
</html>
|
