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.

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:

view_frame = bonobo_client_site_new_view (
	BONOBO_CLIENT_SITE (site),
	bonobo_ui_compat_get_container (ui_handler));
		    

This is also true of the UI handler you pass to

bonobo_widget_new_control (..., uih)
			

and its variants.

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.

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.

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:

Ensure that you include my-app-ui.h in your POTFILES.in, but there is no need to include it in any files.

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.

See bonobo-window, bonobo-ui-xml, bonobo-ui-container, bonobo-ui-component, bonobo-ui-toolbar, bonobo-ui-item, bonobo-ui-compat

Do not see bonobo-ui-handler, bonobo-uih-menu, bonobo-uih-toolbar bonobo-uih-private. These are the old code.

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.

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:

		/File		[ old ]
		    

In the new setup we use:

		/menu/File	[ new ]
		    

Thus we can still use the same namespace for toolbars and other misc. items.

the plot:  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:

sensitivity, hiddenness, state ( such as toggledness )

Other things we want to separate are:

default labels, tips and pixmaps

So; how is this separation achieved in practice?  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:

<Root>
	<commands>
		<cmd name="baa" _label="Our Label" _tip="Hello World"
		 pixtype="stock" pixname="Open"/>
	</commands>
	<menu>
		<menuitem name="foo" verb="baa"/>
	</menu>
</Root>
			    

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':

-	<menu>
-		<menuitem name="foo" verb="baa"/>
-	</menu>
+	<dockitem name="fishy">
+		<toolitem name="foo" verb="baa" _label="MyLabel"/>
+	</dockitem>
			    

But what does this mean for the programmer? .  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.

But wait, don't you need Menu_Open for stock menu icons? .  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.

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 ? .  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.

But what about acclerators ? How do I get rid of '_'s in my toolbar labels. .  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:

<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>
			    

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.

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.

Standard KeySym names are obtained from <X11/keysymdef.h> by removing the XK_ prefix from each name.

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.

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.

You really want to add a menu item with the builtin verb 'BonoboCustomize' that should magically do what you want.

You have to put all menu items in a UI file in a single <menu> element. Instead of this:

<menu>
    <menuitem foo/>
</menu>
<menu>
    <menuitem foo2/>
</menu>
		    

Use this:

<menu>
    <menuitem foo/>
    <menuitem foo2/>
</menu>