|  |  |  | LibBonoboUI API Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Signals | ||||
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
| 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 | /* * 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
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | 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. |