|  |  |  | LibBonoboUI API Reference Manual |  | 
|---|---|---|---|---|
                    BonoboUIComponent;
                    BonoboUIComponentPrivate;
void                (*BonoboUIListenerFn)               (BonoboUIComponent *component,
                                                         const char *path,
                                                         Bonobo_UIComponent_EventType type,
                                                         const char *state,
                                                         gpointer user_data);
void                (*BonoboUIVerbFn)                   (BonoboUIComponent *component,
                                                         gpointer user_data,
                                                         const char *cname);
                    BonoboUIComponentClass;
BonoboUIComponent*  bonobo_ui_component_construct       (BonoboUIComponent *component,
                                                         const char *name);
BonoboUIComponent*  bonobo_ui_component_new             (const char *name);
BonoboUIComponent*  bonobo_ui_component_new_default     (void);
void                bonobo_ui_component_set_name        (BonoboUIComponent *component,
                                                         const char *name);
const char*         bonobo_ui_component_get_name        (BonoboUIComponent *component);
void                bonobo_ui_component_set_container   (BonoboUIComponent *component,
                                                         Bonobo_UIContainer container,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_unset_container (BonoboUIComponent *component,
                                                         CORBA_Environment *opt_ev);
Bonobo_UIContainer  bonobo_ui_component_get_container   (BonoboUIComponent *component);
void                bonobo_ui_component_add_verb        (BonoboUIComponent *component,
                                                         const char *cname,
                                                         BonoboUIVerbFn fn,
                                                         gpointer user_data);
void                bonobo_ui_component_add_verb_full   (BonoboUIComponent *component,
                                                         const char *cname,
                                                         GClosure *closure);
void                bonobo_ui_component_remove_verb     (BonoboUIComponent *component,
                                                         const char *cname);
void                bonobo_ui_component_remove_verb_by_closure
                                                        (BonoboUIComponent *component,
                                                         GClosure *closure);
void                bonobo_ui_component_add_listener    (BonoboUIComponent *component,
                                                         const char *id,
                                                         BonoboUIListenerFn fn,
                                                         gpointer user_data);
void                bonobo_ui_component_add_listener_full
                                                        (BonoboUIComponent *component,
                                                         const char *id,
                                                         GClosure *closure);
void                bonobo_ui_component_remove_listener (BonoboUIComponent *component,
                                                         const char *cname);
void                bonobo_ui_component_remove_listener_by_closure
                                                        (BonoboUIComponent *component,
                                                         GClosure *closure);
void                bonobo_ui_component_set             (BonoboUIComponent *component,
                                                         const char *path,
                                                         const char *xml,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_set_translate   (BonoboUIComponent *component,
                                                         const char *path,
                                                         const char *xml,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_set_tree        (BonoboUIComponent *component,
                                                         const char *path,
                                                         BonoboUINode *node,
                                                         CORBA_Environment *ev);
void                bonobo_ui_component_rm              (BonoboUIComponent *component,
                                                         const char *path,
                                                         CORBA_Environment *ev);
gboolean            bonobo_ui_component_path_exists     (BonoboUIComponent *component,
                                                         const char *path,
                                                         CORBA_Environment *ev);
CORBA_char*         bonobo_ui_component_get             (BonoboUIComponent *component,
                                                         const char *path,
                                                         gboolean recurse,
                                                         CORBA_Environment *opt_ev);
BonoboUINode*       bonobo_ui_component_get_tree        (BonoboUIComponent *component,
                                                         const char *path,
                                                         gboolean recurse,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_object_set      (BonoboUIComponent *component,
                                                         const char *path,
                                                         Bonobo_Unknown control,
                                                         CORBA_Environment *opt_ev);
Bonobo_Unknown      bonobo_ui_component_object_get      (BonoboUIComponent *component,
                                                         const char *path,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_widget_set      (BonoboUIComponent *component,
                                                         const char *path,
                                                         GtkWidget *widget,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_freeze          (BonoboUIComponent *component,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_thaw            (BonoboUIComponent *component,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_set_prop        (BonoboUIComponent *component,
                                                         const char *path,
                                                         const char *prop,
                                                         const char *value,
                                                         CORBA_Environment *opt_ev);
gchar*              bonobo_ui_component_get_prop        (BonoboUIComponent *component,
                                                         const char *path,
                                                         const char *prop,
                                                         CORBA_Environment *opt_ev);
void                bonobo_ui_component_set_status      (BonoboUIComponent *component,
                                                         const char *text,
                                                         CORBA_Environment *opt_ev);
                    BonoboUIVerb;
#define             BONOBO_UI_VERB                      (name,cb)
#define             BONOBO_UI_VERB_DATA                 (name,cb,data)
#define             BONOBO_UI_UNSAFE_VERB               (name,cb)
#define             BONOBO_UI_UNSAFE_VERB_DATA          (name,cb,data)
#define             BONOBO_UI_VERB_END
void                bonobo_ui_component_add_verb_list   (BonoboUIComponent *component,
                                                         const BonoboUIVerb *list);
void                bonobo_ui_component_add_verb_list_with_data
                                                        (BonoboUIComponent *component,
                                                         const BonoboUIVerb *list,
                                                         gpointer user_data);
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 4. 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 5. 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.
void (*BonoboUIListenerFn) (BonoboUIComponent *component, const char *path, Bonobo_UIComponent_EventType type, const char *state, gpointer user_data);
| 
 | |
| 
 | |
| 
 | |
| 
 | |
| 
 | 
void (*BonoboUIVerbFn) (BonoboUIComponent *component, gpointer user_data, const char *cname);
| 
 | |
| 
 | |
| 
 | 
typedef struct {
	BonoboObjectClass          parent_class;
	POA_Bonobo_UIComponent__epv epv;
	gpointer dummy[6];
	/* Signals */
	void (*exec_verb) (BonoboUIComponent *comp,
			   const char        *cname);
	void (*ui_event)  (BonoboUIComponent *comp,
			   const char        *path,
			   Bonobo_UIComponent_EventType type,
			   const char        *state);
	/* Virtual XML Methods */
	void (*freeze)    (BonoboUIComponent *component,
			   CORBA_Environment *opt_ev);
	void (*thaw)      (BonoboUIComponent *component,
			   CORBA_Environment *opt_ev);
	void (*xml_set)   (BonoboUIComponent *component,
			   const char        *path,
			   const char        *xml,
			   CORBA_Environment *ev);
	CORBA_char *(*xml_get) (BonoboUIComponent *component,
				const char        *path,
				gboolean           recurse,
				CORBA_Environment *ev);
	void (*xml_rm)    (BonoboUIComponent *component,
			   const char        *path,
			   CORBA_Environment *ev);
	void (*set_prop)  (BonoboUIComponent *component,
			   const char        *path,
			   const char        *prop,
			   const char        *value,
			   CORBA_Environment *opt_ev);
	
	gchar *(*get_prop) (BonoboUIComponent *component,
			    const char        *path,
			    const char        *prop,
			    CORBA_Environment *opt_ev);
	gboolean (*exists) (BonoboUIComponent *component,
			    const char        *path,
			    CORBA_Environment *ev);
} BonoboUIComponentClass;
BonoboUIComponent* bonobo_ui_component_construct (BonoboUIComponent *component, const char *name);
Construct the UI component with name name
| 
 | |
| 
 | the name of the UI component | 
| Returns : | a constructed UI component or NULL on error | 
BonoboUIComponent* bonobo_ui_component_new (const char *name);
Create a new UI component with the specified name
| 
 | the name of the UI component | 
| Returns : | a new UI component | 
BonoboUIComponent* bonobo_ui_component_new_default (void);
Create a UI component with a unique default name constructed from various available system properties.
| Returns : | a new UI component | 
void bonobo_ui_component_set_name (BonoboUIComponent *component, const char *name);
Set the name of the UI component
| 
 | the UI component | 
| 
 | the new name | 
const char* bonobo_ui_component_get_name (BonoboUIComponent *component);
| 
 | the UI component | 
| Returns : | the name of the UI component | 
void bonobo_ui_component_set_container (BonoboUIComponent *component, Bonobo_UIContainer container, CORBA_Environment *opt_ev);
This associates this component with a remote container
object.
| 
 | the component | 
| 
 | a remote container object. | 
| 
 | 
void bonobo_ui_component_unset_container (BonoboUIComponent *component, CORBA_Environment *opt_ev);
This dis-associates the component from its associated
BonoboUIContainer.
| 
 | the component | 
| 
 | 
Bonobo_UIContainer bonobo_ui_component_get_container (BonoboUIComponent *component);
| 
 | the component. | 
| Returns : | the associated remote container | 
void bonobo_ui_component_add_verb (BonoboUIComponent *component, const char *cname, BonoboUIVerbFn fn, gpointer user_data);
Add a verb to the UI component, that can be invoked by the container.
| 
 | the component to add it to | 
| 
 | the programmatic name of the verb | 
| 
 | the callback function for invoking it | 
| 
 | the associated user data for the callback | 
void bonobo_ui_component_add_verb_full (BonoboUIComponent *component, const char *cname, GClosure *closure);
Add a verb to the UI component, that can be invoked by the container.
| 
 | the component to add it to | 
| 
 | the programmatic name of the verb | 
| 
 | 
void bonobo_ui_component_remove_verb (BonoboUIComponent *component, const char *cname);
Remove a verb by it's unique name
| 
 | the component to add it to | 
| 
 | the programmatic name of the verb | 
void                bonobo_ui_component_remove_verb_by_closure
                                                        (BonoboUIComponent *component,
                                                         GClosure *closure);
remove any verb handled by fn.
| 
 | the component to add it to | 
| 
 | 
void bonobo_ui_component_add_listener (BonoboUIComponent *component, const char *id, BonoboUIListenerFn fn, gpointer user_data);
Add a listener for stateful events.
| 
 | the component to add it to | 
| 
 | the programmatic name of the id | 
| 
 | the callback function for invoking it | 
| 
 | the associated user data for the callback | 
void                bonobo_ui_component_add_listener_full
                                                        (BonoboUIComponent *component,
                                                         const char *id,
                                                         GClosure *closure);
Add a listener for stateful events.
| 
 | the component to add it to | 
| 
 | the programmatic name of the id | 
| 
 | 
void bonobo_ui_component_remove_listener (BonoboUIComponent *component, const char *cname);
Remove any listener by its unique id
| 
 | the component to add it to | 
| 
 | the programmatic name of the id | 
void                bonobo_ui_component_remove_listener_by_closure
                                                        (BonoboUIComponent *component,
                                                         GClosure *closure);
| 
 | |
| 
 | 
void bonobo_ui_component_set (BonoboUIComponent *component, const char *path, const char *xml, CORBA_Environment *opt_ev);
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.
| 
 | the component | 
| 
 | the path to set | 
| 
 | the xml to set | 
| 
 | the (optional) CORBA exception environment | 
void bonobo_ui_component_set_translate (BonoboUIComponent *component, const char *path, const char *xml, CORBA_Environment *opt_ev);
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.
| 
 | the component | 
| 
 | the path to set | 
| 
 | the non translated xml to set | 
| 
 | the (optional) CORBA exception environment | 
void bonobo_ui_component_set_tree (BonoboUIComponent *component, const char *path, BonoboUINode *node, CORBA_Environment *ev);
Set the xml fragment into the remote BonoboUIContainer's tree
attached to component at the specified path
| 
 | the component | 
| 
 | the path to set | 
| 
 | the BonoboUINode representation of an xml tree to set | 
| 
 | the (optional) CORBA exception environment | 
void bonobo_ui_component_rm (BonoboUIComponent *component, const char *path, CORBA_Environment *ev);
This routine removes a chunk of the XML tree in the
BonoboUIContainer associated with component pointed
to by path.
| 
 | the component | 
| 
 | the path to set | 
| 
 | the (optional) CORBA exception environment | 
gboolean bonobo_ui_component_path_exists (BonoboUIComponent *component, const char *path, CORBA_Environment *ev);
| 
 | the component | 
| 
 | the path to set the property on | 
| 
 | the (optional) CORBA exception environment | 
| Returns : | TRUE if the path exists in the container. | 
CORBA_char* bonobo_ui_component_get (BonoboUIComponent *component, const char *path, gboolean recurse, CORBA_Environment *opt_ev);
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.
| 
 | the component | 
| 
 | the path to get | 
| 
 | whether to get child nodes of path | 
| 
 | the (optional) CORBA exception environment | 
| Returns : | an XML string (CORBA allocated) | 
BonoboUINode* bonobo_ui_component_get_tree (BonoboUIComponent *component, const char *path, gboolean recurse, CORBA_Environment *opt_ev);
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.
| 
 | the component | 
| 
 | the path to get | 
| 
 | whether to get child nodes of path | 
| 
 | the (optional) CORBA exception environment | 
| Returns : | an BonoboUINode XML representation | 
void bonobo_ui_component_object_set (BonoboUIComponent *component, const char *path, Bonobo_Unknown control, CORBA_Environment *opt_ev);
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.
| 
 | the component | 
| 
 | the path to set | 
| 
 | a CORBA object reference | 
| 
 | the (optional) CORBA exception environment | 
Bonobo_Unknown bonobo_ui_component_object_get (BonoboUIComponent *component, const char *path, CORBA_Environment *opt_ev);
This returns the control CORBA object registered with the
BonoboUIContainer associated with this component at
the specified path.
| 
 | the component | 
| 
 | the path to set | 
| 
 | |
| Returns : | the associated remote CORBA object. | 
void bonobo_ui_component_widget_set (BonoboUIComponent *component, const char *path, GtkWidget *widget, CORBA_Environment *opt_ev);
| 
 | |
| 
 | |
| 
 | |
| 
 | 
void bonobo_ui_component_freeze (BonoboUIComponent *component, CORBA_Environment *opt_ev);
This increments the freeze count on the associated BonoboUIContainer, (if not already frozen) 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/
| 
 | the component | 
| 
 | 
void bonobo_ui_component_thaw (BonoboUIComponent *component, CORBA_Environment *opt_ev);
This decrements the freeze count on the remote associated BonoboUIContainer, (if frozen). 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/
| 
 | the component | 
| 
 | 
void bonobo_ui_component_set_prop (BonoboUIComponent *component, const char *path, const char *prop, const char *value, CORBA_Environment *opt_ev);
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.
| 
 | the component | 
| 
 | the path to set the property on | 
| 
 | the property name | 
| 
 | the property value | 
| 
 | the (optional) CORBA exception environment | 
gchar* bonobo_ui_component_get_prop (BonoboUIComponent *component, const char *path, const char *prop, CORBA_Environment *opt_ev);
This helper function fetches an XML property ( or attribute )
from the XML node pointed at by path in the BonoboUIContainer
associated with component
| 
 | the component | 
| 
 | the path to set the property on | 
| 
 | the property name | 
| 
 | the (optional) CORBA exception environment | 
| Returns : | the xml property value or NULL - free with g_free. | 
void bonobo_ui_component_set_status (BonoboUIComponent *component, const char *text, CORBA_Environment *opt_ev);
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.
| 
 | the component | 
| 
 | the new status text | 
| 
 | 
typedef struct {
	const char    *cname;
	BonoboUIVerbFn cb;
	gpointer       user_data;
	gpointer       dummy;
} BonoboUIVerb;
#define BONOBO_UI_VERB(name,cb)                  { (name), (cb), NULL   }
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.
| 
 | the verb name | 
| 
 | the callback function. | 
#define BONOBO_UI_VERB_DATA(name,cb,data)        { (name), (cb), (data) }
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.
| 
 | the verb name | 
| 
 | the callback function | 
| 
 | some associated user_data | 
#define BONOBO_UI_UNSAFE_VERB(name,cb)           { (name), ((BonoboUIVerbFn)(cb)), NULL   }
As BONOBO_UI_VERB, but unsafely casts cb to the correct type
| 
 | the verb name | 
| 
 | the callback function. | 
#define BONOBO_UI_UNSAFE_VERB_DATA(name,cb,data) { (name), ((BonoboUIVerbFn)(cb)), (data) }
As BONOBO_UI_VERB_DATA, but unsafely casts cb to the correct type
| 
 | the verb name | 
| 
 | the callback function | 
| 
 | some associated user_data | 
#define BONOBO_UI_VERB_END                       { NULL, NULL, NULL }
The terminator BonoboUIVerb structure for a list of BonoboUIVerbs.
void bonobo_ui_component_add_verb_list (BonoboUIComponent *component, const BonoboUIVerb *list);
Add a list of verbs with no associated user_data, you probably want bonobo_ui_component_add_verb_list_with_data
| 
 | the component | 
| 
 | the list of verbs. | 
void                bonobo_ui_component_add_verb_list_with_data
                                                        (BonoboUIComponent *component,
                                                         const BonoboUIVerb *list,
                                                         gpointer user_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
| 
 | the component | 
| 
 | the list of verbs | 
| 
 | the user data passed to the verb callbacks | 
"exec-verb" signalvoid user_function (BonoboUIComponent *bonobouicomponent, gchar *arg1, gpointer user_data) : Run First
| 
 | the object which received the signal. | 
| 
 | |
| 
 | user data set when the signal handler was connected. | 
"ui-event" signalvoid user_function (BonoboUIComponent *bonobouicomponent, gchar *arg1, gint arg2, gchar *arg3, gpointer user_data) : Run First
| 
 | the object which received the signal. | 
| 
 | |
| 
 | |
| 
 | |
| 
 | user data set when the signal handler was connected. |