BonoboUIComponent

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

## Synopsis

                        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);

## Object Hierarchy

      GObject
       +----BonoboObject
             +----BonoboUIComponent

## Signals

      "exec-verb"                                      : Run First
      "ui-event"                                       : Run First

## 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.

## Details

### BonoboUIComponent

    typedef struct _BonoboUIComponent BonoboUIComponent;

### BonoboUIComponentPrivate

    typedef struct _BonoboUIComponentPrivate BonoboUIComponentPrivate;

### BonoboUIListenerFn ()

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

`component` : |
`path` : |
`type` : |
`state` : |
`user_data` : |

### BonoboUIVerbFn ()

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

`component` : |
`user_data` : |
`cname` : |

### 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;

### bonobo_ui_component_construct ()

    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

### bonobo_ui_component_new ()

    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

### 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`

`component` : | the UI component
`name` : | the new name

### bonobo_ui_component_get_name ()

    const char *        bonobo_ui_component_get_name        (BonoboUIComponent *component);

`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.

`component` : | the component
`container` : | a remote container object.
`opt_ev` : |

### 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.

`component` : | the component
`opt_ev` : |

### bonobo_ui_component_get_container ()

    Bonobo_UIContainer  bonobo_ui_component_get_container   (BonoboUIComponent *component);

`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.

`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.

`component` : | the component to add it to
`cname` : | the programmatic name of the verb
`closure` : |

### bonobo_ui_component_remove_verb ()

    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

### 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`.

`component` : | the component to add it to
`closure` : |

### 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.

`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.

`component` : | the component to add it to
`id` : | the programmatic name of the id
`closure` : |

### bonobo_ui_component_remove_listener ()

    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

### bonobo_ui_component_remove_listener_by_closure ()

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

`component` : |
`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.

`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.

`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`

`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`.

`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);

`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.

`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.

`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.

`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`.

`component` : | the component
`path` : | the path to set
`opt_ev` : |
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);

`component` : |
`path` : |
`widget` : |
`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/

`component` : | the component
`opt_ev` : |

### 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/

`component` : | the component
`opt_ev` : |

### 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.

`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`

`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.

`component` : | the component
`text` : | the new status text
`opt_ev` : |

### BonoboUIVerb

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

### BONOBO_UI_VERB()

    #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.

### BONOBO_UI_VERB_DATA()

    #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

### BONOBO_UI_UNSAFE_VERB()

    #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.

### BONOBO_UI_UNSAFE_VERB_DATA()

    #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

### BONOBO_UI_VERB_END

    #define BONOBO_UI_VERB_END                       { NULL, NULL, NULL }

The terminator BonoboUIVerb structure for a list of BonoboUIVerbs.

### 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

`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

`component` : | the component
`list` : | the list of verbs
`user_data` : | the user data passed to the verb callbacks

## Signal Details

### The `"exec-verb"` signal

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

`bonobouicomponent` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"ui-event"` signal

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

`bonobouicomponent` : | the object which received the signal.
`arg1` : |
`arg2` : |
`arg3` : |
`user_data` : | user data set when the signal handler was connected.

## See Also

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