
Frequently asked questions about the Bonobo UI Handler, version 0.1
by Michael Meeks <michael@helixcode.com>

* How do I port my App from the old to the new UI handler ?

	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

* Where do I find examples ?

	See bonobo/app.c which shows several ways of constructing the
UI. See also bonobo/ui.xml. To build standard menus copy items from
std-ui.xml in the documentation.

* How does translation work ?

	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:

	bonobo-ui-extract my-app-ui.xml > my-app-ui.h

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

* Why don't you use XPath / XPointer ?

	 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.

* Where is the code for the UI handler ?

	See bonobo-win, 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.

* But what happens when Component Foo implements 'FileSave' and Component
Baa also implements 'FileSave' ?

	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.

* I'm confused by paths, where does the File menu live ?

	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.


* What does this cmd / widget separation really mean ?

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

