BonoboUIComponent

BonoboUIComponent — A UI interface that handles UI merging for a component

Functions

void (*BonoboUIListenerFn) ()
void (*BonoboUIVerbFn) ()
BonoboUIComponent * bonobo_ui_component_construct ()
BonoboUIComponent * bonobo_ui_component_new ()
BonoboUIComponent * bonobo_ui_component_new_default ()
void bonobo_ui_component_set_name ()
const char * bonobo_ui_component_get_name ()
void bonobo_ui_component_set_container ()
void bonobo_ui_component_unset_container ()
Bonobo_UIContainer bonobo_ui_component_get_container ()
void bonobo_ui_component_add_verb ()
void bonobo_ui_component_add_verb_full ()
void bonobo_ui_component_remove_verb ()
void bonobo_ui_component_remove_verb_by_closure ()
void bonobo_ui_component_add_listener ()
void bonobo_ui_component_add_listener_full ()
void bonobo_ui_component_remove_listener ()
void bonobo_ui_component_remove_listener_by_closure ()
void bonobo_ui_component_set ()
void bonobo_ui_component_set_translate ()
void bonobo_ui_component_set_tree ()
void bonobo_ui_component_rm ()
gboolean bonobo_ui_component_path_exists ()
CORBA_char * bonobo_ui_component_get ()
BonoboUINode * bonobo_ui_component_get_tree ()
void bonobo_ui_component_object_set ()
Bonobo_Unknown bonobo_ui_component_object_get ()
void bonobo_ui_component_widget_set ()
void bonobo_ui_component_freeze ()
void bonobo_ui_component_thaw ()
void bonobo_ui_component_set_prop ()
gchar * bonobo_ui_component_get_prop ()
void bonobo_ui_component_set_status ()
#define BONOBO_UI_VERB()
#define BONOBO_UI_VERB_DATA()
#define BONOBO_UI_UNSAFE_VERB()
#define BONOBO_UI_UNSAFE_VERB_DATA()
void bonobo_ui_component_add_verb_list ()
void bonobo_ui_component_add_verb_list_with_data ()

Signals

void exec-verb Run First
void ui-event Run First

Types and Values

Object Hierarchy

    GObject
    ╰── BonoboObject
        ╰── BonoboUIComponent

Description

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.

Functions

BonoboUIListenerFn ()

void
(*BonoboUIListenerFn) (BonoboUIComponent *component,
                       const char *path,
                       Bonobo_UIComponent_EventType type,
                       const char *state,
                       gpointer user_data);


BonoboUIVerbFn ()

void
(*BonoboUIVerbFn) (BonoboUIComponent *component,
                   gpointer user_data,
                   const char *cname);


bonobo_ui_component_construct ()

BonoboUIComponent *
bonobo_ui_component_construct (BonoboUIComponent *component,
                               const char *name);

Construct the UI component with name name

Parameters

name

the name of the UI component

 

Returns

a constructed UI component or NULL on error


bonobo_ui_component_new ()

BonoboUIComponent *
bonobo_ui_component_new (const char *name);

Create a new UI component with the specified name

Parameters

name

the name of the UI component

 

Returns

a new UI component


bonobo_ui_component_new_default ()

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


bonobo_ui_component_set_name ()

void
bonobo_ui_component_set_name (BonoboUIComponent *component,
                              const char *name);

Set the name of the UI component

Parameters

component

the UI component

 

name

the new name

 

bonobo_ui_component_get_name ()

const char *
bonobo_ui_component_get_name (BonoboUIComponent *component);

Parameters

component

the UI component

 

Returns

the name of the UI component


bonobo_ui_component_set_container ()

void
bonobo_ui_component_set_container (BonoboUIComponent *component,
                                   Bonobo_UIContainer container,
                                   CORBA_Environment *opt_ev);

This associates this component with a remote container object.

Parameters

component

the component

 

container

a remote container object.

 

bonobo_ui_component_unset_container ()

void
bonobo_ui_component_unset_container (BonoboUIComponent *component,
                                     CORBA_Environment *opt_ev);

This dis-associates the component from its associated BonoboUIContainer.

Parameters

component

the component

 

bonobo_ui_component_get_container ()

Bonobo_UIContainer
bonobo_ui_component_get_container (BonoboUIComponent *component);

Parameters

component

the component.

 

Returns

the associated remote container


bonobo_ui_component_add_verb ()

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.

Parameters

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

 

bonobo_ui_component_add_verb_full ()

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.

Parameters

component

the component to add it to

 

cname

the programmatic name of the verb

 

bonobo_ui_component_remove_verb ()

void
bonobo_ui_component_remove_verb (BonoboUIComponent *component,
                                 const char *cname);

Remove a verb by it's unique name

Parameters

component

the component to add it to

 

cname

the programmatic name of the verb

 

bonobo_ui_component_remove_verb_by_closure ()

void
bonobo_ui_component_remove_verb_by_closure
                               (BonoboUIComponent *component,
                                GClosure *closure);

remove any verb handled by fn .

Parameters

component

the component to add it to

 

bonobo_ui_component_add_listener ()

void
bonobo_ui_component_add_listener (BonoboUIComponent *component,
                                  const char *id,
                                  BonoboUIListenerFn fn,
                                  gpointer user_data);

Add a listener for stateful events.

Parameters

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

 

bonobo_ui_component_add_listener_full ()

void
bonobo_ui_component_add_listener_full (BonoboUIComponent *component,
                                       const char *id,
                                       GClosure *closure);

Add a listener for stateful events.

Parameters

component

the component to add it to

 

id

the programmatic name of the id

 

bonobo_ui_component_remove_listener ()

void
bonobo_ui_component_remove_listener (BonoboUIComponent *component,
                                     const char *cname);

Remove any listener by its unique id

Parameters

component

the component to add it to

 

cname

the programmatic name of the id

 

bonobo_ui_component_remove_listener_by_closure ()

void
bonobo_ui_component_remove_listener_by_closure
                               (BonoboUIComponent *component,
                                GClosure *closure);


bonobo_ui_component_set ()

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.

Parameters

component

the component

 

path

the path to set

 

xml

the xml to set

 

opt_ev

the (optional) CORBA exception environment

 

bonobo_ui_component_set_translate ()

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.

Parameters

component

the component

 

path

the path to set

 

xml

the non translated xml to set

 

opt_ev

the (optional) CORBA exception environment

 

bonobo_ui_component_set_tree ()

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

Parameters

component

the component

 

path

the path to set

 

node

the BonoboUINode representation of an xml tree to set

 

ev

the (optional) CORBA exception environment

 

bonobo_ui_component_rm ()

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 .

Parameters

component

the component

 

path

the path to set

 

ev

the (optional) CORBA exception environment

 

bonobo_ui_component_path_exists ()

gboolean
bonobo_ui_component_path_exists (BonoboUIComponent *component,
                                 const char *path,
                                 CORBA_Environment *ev);

Parameters

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.


bonobo_ui_component_get ()

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.

Parameters

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)


bonobo_ui_component_get_tree ()

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.

Parameters

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


bonobo_ui_component_object_set ()

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.

Parameters

component

the component

 

path

the path to set

 

control

a CORBA object reference

 

opt_ev

the (optional) CORBA exception environment

 

bonobo_ui_component_object_get ()

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 .

Parameters

component

the component

 

path

the path to set

 

Returns

the associated remote CORBA object.


bonobo_ui_component_widget_set ()

void
bonobo_ui_component_widget_set (BonoboUIComponent *component,
                                const char *path,
                                GtkWidget *widget,
                                CORBA_Environment *opt_ev);


bonobo_ui_component_freeze ()

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/

Parameters

component

the component

 

bonobo_ui_component_thaw ()

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/

Parameters

component

the component

 

bonobo_ui_component_set_prop ()

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.

Parameters

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

 

bonobo_ui_component_get_prop ()

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

Parameters

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.


bonobo_ui_component_set_status ()

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.

Parameters

component

the component

 

text

the new status text

 

BONOBO_UI_VERB()

#define BONOBO_UI_VERB(name,cb)                  { (name), (cb), NULL, 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.

Parameters

name

the verb name

 

cb

the callback function.

 

BONOBO_UI_VERB_DATA()

#define BONOBO_UI_VERB_DATA(name,cb,data)        { (name), (cb), (data), 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.

Parameters

name

the verb name

 

cb

the callback function

 

data

some associated user_data

 

BONOBO_UI_UNSAFE_VERB()

#define BONOBO_UI_UNSAFE_VERB(name,cb)           { (name), ((BonoboUIVerbFn)(cb)), NULL, NULL   }

As BONOBO_UI_VERB, but unsafely casts cb to the correct type

Parameters

name

the verb name

 

cb

the callback function.

 

BONOBO_UI_UNSAFE_VERB_DATA()

#define BONOBO_UI_UNSAFE_VERB_DATA(name,cb,data) { (name), ((BonoboUIVerbFn)(cb)), (data), NULL }

As BONOBO_UI_VERB_DATA, but unsafely casts cb to the correct type

Parameters

name

the verb name

 

cb

the callback function

 

data

some associated user_data

 

bonobo_ui_component_add_verb_list ()

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

Parameters

component

the component

 

list

the list of verbs.

 

bonobo_ui_component_add_verb_list_with_data ()

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

Parameters

component

the component

 

list

the list of verbs

 

user_data

the user data passed to the verb callbacks

 

Types and Values

struct BonoboUIComponent

struct BonoboUIComponent;


BonoboUIComponentPrivate

typedef struct _BonoboUIComponentPrivate BonoboUIComponentPrivate;


BonoboUIComponentClass

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;


BonoboUIVerb

typedef struct {
	const char    *cname;
	BonoboUIVerbFn cb;
	gpointer       user_data;
	gpointer       dummy;
} BonoboUIVerb;


BONOBO_UI_VERB_END

#define BONOBO_UI_VERB_END                       { NULL, NULL, NULL, NULL }

The terminator BonoboUIVerb structure for a list of BonoboUIVerbs.

Signal Details

The “exec-verb” signal

void
user_function (BonoboUIComponent *bonobouicomponent,
               gchar             *arg1,
               gpointer           user_data)

Parameters

bonobouicomponent

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “ui-event” signal

void
user_function (BonoboUIComponent *bonobouicomponent,
               gchar             *arg1,
               gint               arg2,
               gchar             *arg3,
               gpointer           user_data)

Parameters

bonobouicomponent

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

See Also

BonoboUIContainer, bonobo-ui-util(3), BonoboControl