/usr/share/gtk-doc/html/libbonoboui/libbonoboui-faq.html is in libbonoboui2-dev 2.24.5-2.
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 <michael@helixcode.com>
</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 > 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">
<Root>
<commands>
<cmd name="baa" _label="Our Label" _tip="Hello World"
pixtype="stock" pixname="Open"/>
</commands>
<menu>
<menuitem name="foo" verb="baa"/>
</menu>
</Root>
</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">
- <menu>
- <menuitem name="foo" verb="baa"/>
- </menu>
+ <dockitem name="fishy">
+ <toolitem name="foo" verb="baa" _label="MyLabel"/>
+ </dockitem>
</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">
<Root>
<commands>
<cmd name="FileOpen" _label="Open" hidden="1"
_tip="Open a file" pixtype="stock" pixname="Open"
accel="F3"/>
</commands>
<menu>
<menuitem name="FileNew" verb="" _label="_New"/>
</menu>
</Root>
</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 <X11/keysymdef.h> 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 <submenu> 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 <submenu name="File" _label="File"> 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. <submenu name="File">. 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 <menu> elements, and the
menu items inside the second <menu> 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
<menu> element. Instead of this: </p>
<pre class="programlisting">
<menu>
<menuitem foo/>
</menu>
<menu>
<menuitem foo2/>
</menu>
</pre>
<p>Use this:</p>
<pre class="programlisting">
<menu>
<menuitem foo/>
<menuitem foo2/>
</menu>
</pre>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
<div class="footer">
<hr>
Generated by GTK-Doc V1.15.1</div>
</body>
</html>
|