![]() | ![]() | ![]() | LibBonoboUI API Reference Manual | ![]() |
---|
BonoboUIComponent — A UI interface that handles UI merging for a component
struct BonoboUIComponent; struct 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); struct 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); struct 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);
GObject +----BonoboObject +----BonoboUIComponent
"exec-verb" void user_function (BonoboUIComponent *bonobouicomponent, gchar *arg1, gpointer user_data); "ui-event" void user_function (BonoboUIComponent *bonobouicomponent, gchar *arg1, gint arg2, gchar *arg3, 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 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.
void (*BonoboUIListenerFn) (BonoboUIComponent *component, const char *path, Bonobo_UIComponent_EventType type, const char *state, gpointer user_data);
component : | |
path : | |
type : | |
state : | |
user_data : |
void (*BonoboUIVerbFn) (BonoboUIComponent *component, gpointer user_data, const char *cname);
component : | |
user_data : | |
cname : |
struct BonoboUIComponentClass { 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); };
BonoboUIComponent* bonobo_ui_component_construct (BonoboUIComponent *component, const char *name);
Construct the UI component with name name
component : | |
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
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
component : | the UI component |
name : | the new name |
const char* bonobo_ui_component_get_name (BonoboUIComponent *component);
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.
component : | the component |
container : | a remote container object. |
opt_ev : |
void bonobo_ui_component_unset_container (BonoboUIComponent *component, CORBA_Environment *opt_ev);
This dis-associates the component from its associated BonoboUIContainer.
component : | the component |
opt_ev : |
Bonobo_UIContainer bonobo_ui_component_get_container (BonoboUIComponent *component);
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.
component : | the component to add it to |
cname : | the programmatic name of the verb |
fn : | the callback function for invoking it |
user_data : | 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.
component : | the component to add it to |
cname : | the programmatic name of the verb |
closure : |
void bonobo_ui_component_remove_verb (BonoboUIComponent *component, const char *cname);
Remove a verb by it's unique name
component : | the component to add it to |
cname : | the programmatic name of the verb |
void bonobo_ui_component_remove_verb_by_closure (BonoboUIComponent *component, GClosure *closure);
remove any verb handled by fn.
component : | the component to add it to |
closure : |
void bonobo_ui_component_add_listener (BonoboUIComponent *component, const char *id, BonoboUIListenerFn fn, gpointer user_data);
Add a listener for stateful events.
component : | the component to add it to |
id : | the programmatic name of the id |
fn : | the callback function for invoking it |
user_data : | 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.
component : | the component to add it to |
id : | the programmatic name of the id |
closure : |
void bonobo_ui_component_remove_listener (BonoboUIComponent *component, const char *cname);
Remove any listener by its unique id
component : | the component to add it to |
cname : | the programmatic name of the id |
void bonobo_ui_component_remove_listener_by_closure (BonoboUIComponent *component, GClosure *closure);
component : | |
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.
component : | the component |
path : | the path to set |
xml : | the xml to set |
opt_ev : | 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.
component : | the component |
path : | the path to set |
xml : | the non translated xml to set |
opt_ev : | 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
component : | the component |
path : | the path to set |
node : | the BonoboUINode representation of an xml tree to set |
ev : | 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.
component : | the component |
path : | the path to set |
ev : | the (optional) CORBA exception environment |
gboolean bonobo_ui_component_path_exists (BonoboUIComponent *component, const char *path, CORBA_Environment *ev);
component : | the component |
path : | the path to set the property on |
ev : | 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.
component : | the component |
path : | the path to get |
recurse : | whether to get child nodes of path |
opt_ev : | 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.
component : | the component |
path : | the path to get |
recurse : | whether to get child nodes of path |
opt_ev : | 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.
component : | the component |
path : | the path to set |
control : | a CORBA object reference |
opt_ev : | 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.
component : | the component |
path : | the path to set |
opt_ev : | |
Returns : | the associated remote CORBA object. |
void bonobo_ui_component_widget_set (BonoboUIComponent *component, const char *path, GtkWidget *widget, CORBA_Environment *opt_ev);
component : | |
path : | |
widget : | |
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/
component : | the component |
opt_ev : |
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/
component : | the component |
opt_ev : |
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.
component : | the component |
path : | the path to set the property on |
prop : | the property name |
value : | the property value |
opt_ev : | 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
component : | the component |
path : | the path to set the property on |
prop : | the property name |
opt_ev : | 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.
component : | the component |
text : | the new status text |
opt_ev : |
struct BonoboUIVerb { const char *cname; BonoboUIVerbFn cb; gpointer user_data; gpointer dummy; };
#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.
name : | the verb name |
cb : | 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.
name : | the verb name |
cb : | the callback function |
data : | 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
name : | the verb name |
cb : | 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
name : | the verb name |
cb : | the callback function |
data : | 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
component : | the component |
list : | 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
component : | the component |
list : | the list of verbs |
user_data : | the user data passed to the verb callbacks |
void user_function (BonoboUIComponent *bonobouicomponent, gchar *arg1, gpointer user_data);
bonobouicomponent : | the object which received the signal. |
arg1 : | |
user_data : | user data set when the signal handler was connected. |
void user_function (BonoboUIComponent *bonobouicomponent, gchar *arg1, gint arg2, gchar *arg3, gpointer user_data);
bonobouicomponent : | the object which received the signal. |
arg1 : | |
arg2 : | |
arg3 : | |
user_data : | user data set when the signal handler was connected. |
<< bonobo-window | BonoboUIContainer >> |