The BonoboUIComponent is the client side portion of the UI merging scheme.
It should be implemented by any component that wishes to merge menus / UI.
The Component object is neccessary to receive notifications from the
associated BonoboUIContainer. Notifications come in two forms - verbs and
events. Verbs have an associated ( non translated ) name that is used to
match them with callbacks. Events have an associated ( non translated ) id
that does the same thing. Events pass a state string. Events are used for
eg. toggle buttons, Verbs are used for eg. Menu items.
Mostly you don't need to bother with creating your own BonoboUIComponent,
if you implement a Control eg. a BonoboUIComponent is created at Control
construction time and can be accessed thus:
Example 1. Using the UI Component associated with a control
/*
* For the format of the XML see bonobo/doc/xml-ui.txt
* For a standard template to base your UI on see bonobo/doc/std-ui.xml
*/
const char my_ui_elements [] =
">placeholder name=\"FileOps\"<"
" >menuitem name=\"Foo\" verb=\"FileFoo\" _label=\"Foo!\""
" _tip=\"do some foo thing\"/<"
">/placeholder<";
static void
control_activate_cb (BonoboControl *object,
gboolean state,
gpointer user_data)
{
BonoboUIComponent *ui_component;
/* Get UIComponent from control */
ui_component = bonobo_control_get_ui_component (control);
if (state) /* Activate */
bonobo_ui_component_set_translate (
ui_component, "/menu/File", my_ui_elements, NULL);
else /* De-activate */
bonobo_ui_component_unset_container (ui_component);
}
static void
verb_foo_cb (BonoboUIComponent *ui_container,
gpointer user_data,
const char *cname)
{
BonoboControl *control = user_data;
g_print ("FileFoo !\n");
}
static BonoboUIVerb my_ui_verbs[] = {
BONOBO_UI_VERB ("FileFoo", verb_foo_cb),
BONOBO_UI_VERB_END
};
BonoboObject *
create_ui_control (void)
{
BonoboControl *control;
BonoboUIComponent *ui_component;
GtkWidget *widget;
control = bonobo_control_new ((widget = gtk_widget_new_label ("Hello World")));
/* Automaticaly associate the remote UIContainer for us on activate */
bonobo_control_set_automerge (control, TRUE);
ui_component = bonobo_control_get_ui_component (control);
/* Register the verbs with the UI Component */
bonobo_ui_component_add_verb_list_with_data (
ui_component, my_ui_verbs, control);
gtk_signal_connect (GTK_OBJECT (control), "activate",
GTK_SIGNAL_FUNC (control_activate_cb), NULL);
gtk_widget_show (widget);
return BONOBO_OBJECT (control);
}
This sets up the UI, associates a 'FileFoo' verb with a callback, and
on control activation merges the UI elements into a standard path
in the file menu.
There are several standard placeholders that it is important for
containers to implement, basing your UI on the doc/std-ui.xml is
a very good starting point. Also in the above example the _label
and _tip are not cmd / widget separated - for more information read
doc/ui-xml.txt.
Most applications will should not use the BonoboUIComponent in this
way, there is a bonobo_ui_util_set_ui that does
the translation, help menu build, insertion etc. from an installed
XML file. The above example is complete except for translation, which
is extremely important. Here is a better activate function:
Example 2. A better way to create your UI
static void
control_activate_cb (BonoboControl *object,
gboolean state,
gpointer user_data)
{
BonoboUIComponent *ui_component;
/* Get UIComponent from control */
ui_component = bonobo_control_get_ui_component (control);
if (state) /* Activate */
/*
* Use a helper function to setup your UI from a file:
*/
bonobo_ui_util_set_ui (
ui_component, MY_COMPILE_TIME_PREFIX,
"GNOME_MyApp.ui", "my-app");
else /* De-activate */
bonobo_ui_component_unset_container (ui_component);
}
In this example "GNOME_MyApp.ui" is the correctly namespaced UI
xml filename, ( see doc/NAMESPACE to register your name ), and
"my-app" is the gnome application name, from which a path to your
installed help files can be deduced.
Set the xml fragment into the remote BonoboUIContainer's tree
attached to component at the specified path
If you see blank menu items ( or just separators ) it's
likely that you should be using bonobo_ui_component_set_translate
which substantialy deprecates this routine.
This routine parses the XML strings, and converts any:
_label="Hello World" type strings into the translated,
and encoded format expected by the remote BonoboUIContainer.
This routine fetches a chunk of the XML tree in the
BonoboUIContainer associated with component pointed
to by path. If recurse then the child nodes of path
are returned too, otherwise they are not.
This routine fetches a chunk of the XML tree in the
BonoboUIContainer associated with component pointed
to by path. If recurse then the child nodes of path
are returned too, otherwise they are not.
This registers the control CORBA object into the
BonoboUIContainer associated with this component at
the specified path. This is most often used to associate
controls with a certain path.
This increments the freeze count on the remote associated
BonoboUIContainer, this means that a batch of update operations
can be performed without a re-render penalty per update.
NB. if your GUI is frozen / not updating you probably have a
freeze / thaw reference leak/
This decrements the freeze count on the remote associated
BonoboUIContainer, this means that a batch of update operations
can be performed without a re-render penalty per update.
NB. if your GUI is frozen / not updating you probably have a
freeze / thaw reference leak/
This helper function sets an XML property ( or attribute )
on the XML node pointed at by path. It does this by
a read / modify / write process. If you find yourself
doing this a lot, you need to consider batching this process.
This sets the contents of the status bar to text in the
remote BonoboUIContainer associated with component.
This is done by setting the contents of the /status/main
node.
This declares and fills a BonoboUIVerb structure suitable for
use in constructing a lost of verbs to add with
bonobo_ui_component_add_verb_list_with_data.
This is a helper function to save registering verbs individualy
it allows registration of a great batch of verbs at one time
in a list of BonoboUIVerb terminated by BONOBO_UI_VERB_END