![]() |
![]() |
![]() |
LibBonoboUI API Reference Manual | ![]() |
---|
BonoboUIComponentBonoboUIComponent — A UI interface that handles UI merging for a component |
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);
"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 : |
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
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 : |
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.
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 >> |