This file is indexed.

/usr/share/gtk-doc/html/libbonoboui/libbonoboui-faq.html is in libbonoboui2-dev 2.24.5-3ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  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
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Common Questions</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="index.html" title="LibBonoboUI API Reference Manual">
<link rel="up" href="index.html" title="LibBonoboUI API Reference Manual">
<link rel="prev" href="index.html" title="LibBonoboUI API Reference Manual">
<link rel="next" href="ch01.html" title="Object Hierarchy">
<meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="index.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td> </td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">LibBonoboUI API Reference Manual</th>
<td><a accesskey="n" href="ch01.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="libbonoboui-faq"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle">Common Questions</span></h2>
<p>Common Questions — 
	    Find answers to common questions in the libbonoboui manual
	</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="id2714396"></a><h2>Questions and Answers</h2>
<p>
	    Frequently asked questions about the Bonobo UI Handler, version 0.1
	    by Michael Meeks &lt;michael@helixcode.com&gt;
	</p>
<div class="qandaset">
<a name="id2714408"></a><table border="0" width="100%" summary="Q and A Set">
<col align="left" width="1%">
<col>
<tbody>
<tr class="question">
<td align="left" valign="top">
<a name="id2714411"></a><a name="id2714413"></a><p><b>1.</b></p>
</td>
<td align="left" valign="top"><p> How do I port my App from the old to
		    the new UI handler? </p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p> If you have written a component, then ideally you should have
			to make no code changes, nor re-link the component. There is a
			compatibility layer that should just work. However, this exposes
			you to many evils of the old interface, and does strange things to
			paths for radio items etc.  If you have a complex UI you will want
			to re-write it. </p>
<p>
			If you have written a container, then again the changes are
			minimal, simply replace the gnome_app calls with bonobo_win
			calls. As long as you only used the bonobo API to create menus you
			should be fine.  It is *important* that you replace the ui handler
			parameter to all calls to bonobo_client_site_new_view to something
			of this form:</p>
<pre class="programlisting">
view_frame = bonobo_client_site_new_view (
	BONOBO_CLIENT_SITE (site),
	bonobo_ui_compat_get_container (ui_handler));
		    </pre>
<p> This is also true of the UI handler you pass to
			</p>
<pre class="programlisting">
bonobo_widget_new_control (..., uih)
			</pre>
<p> and its variants.
		    </p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2749398"></a><a name="id2749400"></a><p><b>2.</b></p>
</td>
<td align="left" valign="top"><p>Where do I find examples ?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p> See samples/bonoboui/hello.c which shows several ways of
		    constructing the UI. See also doc/ui-xml.txt. To build standard menus
		    copy items from std-ui.xml in the documentation.
		    </p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2749414"></a><a name="id2749416"></a><p><b>3.</b></p>
</td>
<td align="left" valign="top"><p> How does translation work?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p>
			Every item has a non translated name which is used to construct a
			path for programmatic use. This is invariant over translations, it
			will often be similar to a label or verb name. User readable text
			is prefixed in the XML file by an '_', the file is parsed as it is
			read from disk and these '_' are removed as the strings are
			translated. </p>
<p> In order to extract translatable strings from a header file you
			need to use the 'bonobo-ui-extract' utility which will be
			installed with bonobo. Do:</p>
<span class="command"><strong><code class="literal">
			bonobo-ui-extract my-app-ui.xml &gt; my-app-ui.h
			</code></strong></span><p>Ensure that you include my-app-ui.h in your POTFILES.in, but
			there is no need to include it in any files.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2710655"></a><a name="id2710657"></a><p><b>4.</b></p>
</td>
<td align="left" valign="top"><p>Why don't you use XPath / XPointer?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p> These are fine reccomendations for addressing elements of an
			XML document. A major contributor to these reccomendations is my
			friend Daniel Velliard, with whom I discussed this issue. The UI
			handler primarily is designed to deal with an extremely dynamic
			XML structure.  The whole point of a path is to be invariant over
			XML (de)merges.  It transpires that XPath addressing
			eg. /menuitem[4] is not suitable for this situation. Hence an
			alternative, simple path scheme was implemented. </p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2710677"></a><a name="id2710679"></a><p><b>5.</b></p>
</td>
<td align="left" valign="top"><p>Where is the code for the UI handler?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p>
			See <code class="filename">bonobo-window</code>,
			<code class="filename">bonobo-ui-xml</code>,
			<code class="filename">bonobo-ui-container</code>,
			<code class="filename">bonobo-ui-component</code>,
			<code class="filename">bonobo-ui-toolbar</code>,
			<code class="filename">bonobo-ui-item</code>,
			<code class="filename">bonobo-ui-compat</code></p>
<p> Do not see <code class="filename">bonobo-ui-handler</code>,
			<code class="filename">bonobo-uih-menu</code>,
			<code class="filename">bonobo-uih-toolbar</code>
			<code class="filename">bonobo-uih-private</code>. These are the old
			code. </p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2710761"></a><a name="id2710763"></a><p><b>6.</b></p>
</td>
<td align="left" valign="top"><p>
		    But what happens when Component Foo implements 'FileSave' and Component
		    Baa also implements 'FileSave'?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p> The verbs are emitted on the component that registers them. In
			this case the verb gets sent to the component associated with
			whatever item was activated.</p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2710781"></a><a name="id2710783"></a><p><b>7.</b></p>
</td>
<td align="left" valign="top"><p>I'm confused by paths,
		    where does the File menu live?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p>In the old strategy there was a partition of the menu vs.  other
			APIs, so a different paths trategy was used, in the old setup we
			would use:</p>
<pre class="programlisting">
		/File		[ old ]
		    </pre>
<p>In the new setup we use:</p>
<pre class="programlisting">
		/menu/File	[ new ]
		    </pre>
<p>Thus we can still use the same namespace for toolbars and other
			misc. items.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2710818"></a><a name="id2710820"></a><p><b>8.</b></p>
</td>
<td align="left" valign="top"><p> What does this cmd / widget separation really mean?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p><b>the plot: </b>
			    Since we want to be able to allow the user to full customize
			    his or her menus and toolbars we need to be able to abstract
			    the following things away from the layout of the menus:
			    </p>
<p>
				sensitivity, hiddenness, state ( such as toggledness )
			    </p>
<p>
			    Other things we want to separate are:
			    </p>
<p>
				default labels, tips and pixmaps</p>
<p>
			</p>
<p><b>
			So; how is this separation achieved in practice? </b>
			    We have a namespace that 'commands' live in; these can either
			    be things like 'Save' ( a verb ) or 'Threaded View' ( a state
			    with an id ). Both verbs and id's are in the same space. So;
			    we describe the capbilities of a program in terms of the verbs
			    and state inputs it can handle, and provide a default UI
			    layout, perhaps like this:
			    </p>
<pre class="programlisting">
&lt;Root&gt;
	&lt;commands&gt;
		&lt;cmd name="baa" _label="Our Label" _tip="Hello World"
		 pixtype="stock" pixname="Open"/&gt;
	&lt;/commands&gt;
	&lt;menu&gt;
		&lt;menuitem name="foo" verb="baa"/&gt;
	&lt;/menu&gt;
&lt;/Root&gt;
			    </pre>
<p>

			    Now; the user can chose to remove the 'Our Label' button, or
			    more creatively might decide to convert it into a toolbar and
			    change the label to 'MyLabel':
			    </p>
<pre class="programlisting">
-	&lt;menu&gt;
-		&lt;menuitem name="foo" verb="baa"/&gt;
-	&lt;/menu&gt;
+	&lt;dockitem name="fishy"&gt;
+		&lt;toolitem name="foo" verb="baa" _label="MyLabel"/&gt;
+	&lt;/dockitem&gt;
			    </pre>
<p>
			</p>
<p><b> But what does this mean for the programmer? . </b>
			    What it means, is that when you decided to make this (
			    dangerous lookin ) verb insensitive, instead of setting
			    sensitive="0" on the item at path /menu/foo, you instead do it
			    on the item at path /commands/baa. This then allows the user
			    to have none, one or many representations of each verb/id as
			    either menu or toolbar items.</p>
<p><b> But wait, don't you need Menu_Open for stock menu
			icons? . </b>
			    In this case no; since we need to be able to generate either a
			    menu or a toolbar item view of this verb/id. Consequently the
			    code will add the Menu_ prefix where needed for you.
			</p>
<p><b> But wait, what if the stock items are called
			Foo_Open and Baa_Open for menu / toolbar items ? or ... what if I
			have a non-stock toolbar icon that won't fit in a menu ? . </b>
			    Sadly there was not time to implement custom widget sizing
			    logic, so setting a single pixmap on the verb won't
			    work. However, you can still set the pixmap on the individual
			    toolbar / menu items at the expense of customization.</p>
<p><b> But what about acclerators ?
			How do I get rid of '_'s in my toolbar labels. . </b>
			    Since accelerators are clearly part of the widget and not the
			    command it is important to put labels with accelerators in
			    them in the widget and not the command node. _But_ it is also
			    important to ensure that a non-accelerated version is left in
			    the command for use by GUI configuration software as a default
			    label, it would also be wise to use this as the default
			    toolbar label. So this is good practice:
			    </p>
<pre class="programlisting">
&lt;Root&gt;
	&lt;commands&gt;
	        &lt;cmd name="FileOpen" _label="Open" hidden="1"
		_tip="Open a file" pixtype="stock" pixname="Open"
		accel="F3"/&gt;
	&lt;/commands&gt;

	&lt;menu&gt;
	        &lt;menuitem name="FileNew" verb="" _label="_New"/&gt;
	&lt;/menu&gt;
&lt;/Root&gt;
			    </pre>
<p>

			    See std-ui.xml for a set of correctly organised useful cmd and
			    widget descriptions.
			
			    Note that 'verb=""' is shorthand for making the verb name the
			    same as the node name (in this example, "FileNew"). This is
			    not the same as leaving the verb out entirely. </p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2758609"></a><a name="id2758611"></a><p><b>9.</b></p>
</td>
<td align="left" valign="top"><p> Why don't my old non-alphanumeric keyboard accelerators
		    work anymore? </p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p>
			Keyboard accelerators are now specified in ItemFactory format,
			e.g.  "*Control*s". In old Bonobo, you would have passed 'S' to
			specify the character. For alphanumeric keys, this translation is
			obvious and hard to get wrong. But for non-alphanumeric keys, you
			now have to use the symbolic name returned by gdk_keyval_name
			(which in turn is the symbolic name returned by
			XKeysymToString). For example, to specify Control-equal-sign as a
			keyboard accelerator now, you use "*Control*equal". "*Control*="
			will silently fail to do anything useful.
		    </p>
<p>
			Standard KeySym names are obtained from &lt;X11/keysymdef.h&gt; by
			removing the XK_ prefix from each name.</p>
</td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2758643"></a><a name="id2758645"></a><p><b>10.</b></p>
</td>
<td align="left" valign="top"><p>Why do the menu bar titles
		    flash when merging occurs?</p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>
			They flash if the &lt;submenu&gt; node has been redefined, or if
			Bonobo thinks it has been. A common cause for this is to define
			the label for the menu in more than one place. Bonobo will not
			recognize that &lt;submenu name="File" _label="File"&gt; is
			identical to a submenu already defined exactly the same way
			elsewhere. If you're adding items to an existing menu, don't
			redefine the label; refer to the existing submenu node by name
			only, e.g. &lt;submenu name="File"&gt;. Note that in addition to
			flashiness this can also cause torn-off menus to hide themselves.
		    </p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2758674"></a><a name="id2758676"></a><p><b>11.</b></p>
</td>
<td align="left" valign="top"><p>Surely the radio group belongs on the Verb !?
		    </p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>
			Due to the way the group="whatever" works, it is not possible to
			have the group set on the command, there can of course be mutiple
			sets of the same radio verbs, but they cannot share the same
			group.
		    </p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2758693"></a><a name="id2758695"></a><p><b>12.</b></p>
</td>
<td align="left" valign="top"><p>How do I let the user customize a toolbar once it's hidden?
		    </p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top"><p>You really want to add a menu item with the builtin verb
			'BonoboCustomize' that should magically do what you want.
		    </p></td>
</tr>
<tr class="question">
<td align="left" valign="top">
<a name="id2758710"></a><a name="id2758712"></a><p><b>13.</b></p>
</td>
<td align="left" valign="top"><p> In a UI file I have two &lt;menu&gt; elements, and the
		    menu items inside the second &lt;menu&gt; do not show up in the
		    application. What's wrong? </p></td>
</tr>
<tr class="answer">
<td align="left" valign="top"></td>
<td align="left" valign="top">
<p>
			You have to put all menu items in a UI file in a single
			&lt;menu&gt; element. Instead of this: </p>
<pre class="programlisting">
&lt;menu&gt;
    &lt;menuitem foo/&gt;
&lt;/menu&gt;
&lt;menu&gt;
    &lt;menuitem foo2/&gt;
&lt;/menu&gt;
		    </pre>
<p>Use this:</p>
<pre class="programlisting">
&lt;menu&gt;
    &lt;menuitem foo/&gt;
    &lt;menuitem foo2/&gt;
&lt;/menu&gt;
		    </pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.15.1</div>
</body>
</html>