| Bonobo API Reference Manual | |||
|---|---|---|---|
| <<< Previous Page | Home | Up | Next Page >>> |
struct BonoboUIComponent; void (*BonoboUIListenerFn) ( |
"exec-verb" void user_function ( |
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);
}
|
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);
}
|
void (*BonoboUIListenerFn) ( |
| component : | |
| path : | |
| type : | |
| state : | |
| user_data : |
|
void (*BonoboUIVerbFn) ( |
| component : | |
| user_data : | |
| cname : |
|
typedef struct {
BonoboXObjectClass parent_class;
POA_Bonobo_UIComponent__epv epv;
/* 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);
gpointer dummy;
} BonoboUIComponentClass; |
|
Construct the UI component with name name
| component : | |
| name : | the name of the UI component |
| Returns : | a constructed UI component or NULL on error |
|
Create a new UI component with the specified name
| name : | the name of the UI component |
| Returns : | a new UI component |
|
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 ( |
Set the name of the UI component
| component : | the UI component |
| name : | the new name |
const char* bonobo_ui_component_get_name ( |
| component : | the UI component |
| Returns : | the name of the UI component |
void bonobo_ui_component_set_container
( |
This associates this component with a remote container object.
| component : | the component |
| container : | a remote container object. |
void bonobo_ui_component_unset_container
( |
This dis-associates the component from its associated BonoboUIContainer.
| component : | the component |
|
| component : | the component. |
| Returns : | the associated remote container |
void bonobo_ui_component_add_verb ( |
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
( |
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 |
| destroy_fn : | a destroy function for the callback data |
void bonobo_ui_component_remove_verb ( |
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_func
( |
remove any verb with associated user_data pointer
| component : | the component to add it to |
| fn : |
|
void bonobo_ui_component_remove_verb_by_data
( |
| component : | |
| user_data : |
|
void bonobo_ui_component_add_listener
( |
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
( |
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 |
| destroy_fn : | a destroy function for the callback data |
void bonobo_ui_component_remove_listener
( |
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_func
( |
| component : | |
| fn : |
|
void bonobo_ui_component_remove_listener_by_data
( |
| component : | |
| user_data : |
|
void bonobo_ui_component_set ( |
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 |
| ev : | the (optional) CORBA exception environment |
void bonobo_ui_component_set_translate
( |
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 |
| ev : | the (optional) CORBA exception environment |
void bonobo_ui_component_set_tree ( |
Set the xml fragment into the remote BonoboUIContainer's tree attached to component at the specified path
It is likely that you don't want this routine, but want bonobo_ui_component_set_translate.
| 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 ( |
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 |
|
| 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. |
|
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 |
| ev : | the (optional) CORBA exception environment |
| Returns : | an XML string |
BonoboUINode* bonobo_ui_component_get_tree ( |
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 |
| ev : | the (optional) CORBA exception environment |
| Returns : | an BonoboUINode XML representation |
void bonobo_ui_component_object_set ( |
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 |
| ev : | the (optional) CORBA exception environment |
|
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_freeze ( |
This increments the freeze count on the remote associated BonoboUIContainer, this means that a batch of update operations can be performed without a re-render penalty per update.
NB. if your GUI is frozen / not updating you probably have a freeze / thaw reference leak/
| component : | the component |
| opt_ev : |
|
void bonobo_ui_component_thaw ( |
This decrements the freeze count on the remote associated BonoboUIContainer, this means that a batch of update operations can be performed without a re-render penalty per update.
NB. if your GUI is frozen / not updating you probably have a freeze / thaw reference leak/
| component : | the component |
| opt_ev : |
|
void bonobo_ui_component_set_prop ( |
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 |
|
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 ( |
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 {
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
( |
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
( |
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 : | the object which received the signal. |
| arg1 : | |
| user_data : | user data set when the signal handler was connected. |
void user_function ( |
| bonobouicomponent : | the object which received the signal. |
| arg1 : | |
| arg2 : | |
| arg3 : | |
| user_data : | user data set when the signal handler was connected. |