MateComponentUIComponent

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

## Synopsis

    struct              MateComponentUIComponent;
                        MateComponentUIComponentPrivate;
    void                (*MateComponentUIListenerFn)               (MateComponentUIComponent *component,
                                                             const char *path,
                                                             MateComponent_UIComponent_EventType type,
                                                             const char *state,
                                                             gpointer user_data);
    void                (*MateComponentUIVerbFn)                   (MateComponentUIComponent *component,
                                                             gpointer user_data,
                                                             const char *cname);
                        MateComponentUIComponentClass;
    MateComponentUIComponent * matecomponent_ui_component_construct       (MateComponentUIComponent *component,
                                                             const char *name);
    MateComponentUIComponent * matecomponent_ui_component_new             (const char *name);
    MateComponentUIComponent * matecomponent_ui_component_new_default     (void);
    void                matecomponent_ui_component_set_name        (MateComponentUIComponent *component,
                                                             const char *name);
    const char *        matecomponent_ui_component_get_name        (MateComponentUIComponent *component);
    void                matecomponent_ui_component_set_container   (MateComponentUIComponent *component,
                                                             MateComponent_UIContainer container,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_unset_container (MateComponentUIComponent *component,
                                                             CORBA_Environment *opt_ev);
    MateComponent_UIContainer  matecomponent_ui_component_get_container   (MateComponentUIComponent *component);
    void                matecomponent_ui_component_add_verb        (MateComponentUIComponent *component,
                                                             const char *cname,
                                                             MateComponentUIVerbFn fn,
                                                             gpointer user_data);
    void                matecomponent_ui_component_add_verb_full   (MateComponentUIComponent *component,
                                                             const char *cname,
                                                             GClosure *closure);
    void                matecomponent_ui_component_remove_verb     (MateComponentUIComponent *component,
                                                             const char *cname);
    void                matecomponent_ui_component_remove_verb_by_closure
                                                            (MateComponentUIComponent *component,
                                                             GClosure *closure);
    void                matecomponent_ui_component_add_listener    (MateComponentUIComponent *component,
                                                             const char *id,
                                                             MateComponentUIListenerFn fn,
                                                             gpointer user_data);
    void                matecomponent_ui_component_add_listener_full
                                                            (MateComponentUIComponent *component,
                                                             const char *id,
                                                             GClosure *closure);
    void                matecomponent_ui_component_remove_listener (MateComponentUIComponent *component,
                                                             const char *cname);
    void                matecomponent_ui_component_remove_listener_by_closure
                                                            (MateComponentUIComponent *component,
                                                             GClosure *closure);
    void                matecomponent_ui_component_set             (MateComponentUIComponent *component,
                                                             const char *path,
                                                             const char *xml,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_set_translate   (MateComponentUIComponent *component,
                                                             const char *path,
                                                             const char *xml,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_set_tree        (MateComponentUIComponent *component,
                                                             const char *path,
                                                             MateComponentUINode *node,
                                                             CORBA_Environment *ev);
    void                matecomponent_ui_component_rm              (MateComponentUIComponent *component,
                                                             const char *path,
                                                             CORBA_Environment *ev);
    gboolean            matecomponent_ui_component_path_exists     (MateComponentUIComponent *component,
                                                             const char *path,
                                                             CORBA_Environment *ev);
    CORBA_char *        matecomponent_ui_component_get             (MateComponentUIComponent *component,
                                                             const char *path,
                                                             gboolean recurse,
                                                             CORBA_Environment *opt_ev);
    MateComponentUINode *      matecomponent_ui_component_get_tree        (MateComponentUIComponent *component,
                                                             const char *path,
                                                             gboolean recurse,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_object_set      (MateComponentUIComponent *component,
                                                             const char *path,
                                                             MateComponent_Unknown control,
                                                             CORBA_Environment *opt_ev);
    MateComponent_Unknown      matecomponent_ui_component_object_get      (MateComponentUIComponent *component,
                                                             const char *path,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_widget_set      (MateComponentUIComponent *component,
                                                             const char *path,
                                                             GtkWidget *widget,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_freeze          (MateComponentUIComponent *component,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_thaw            (MateComponentUIComponent *component,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_set_prop        (MateComponentUIComponent *component,
                                                             const char *path,
                                                             const char *prop,
                                                             const char *value,
                                                             CORBA_Environment *opt_ev);
    gchar *             matecomponent_ui_component_get_prop        (MateComponentUIComponent *component,
                                                             const char *path,
                                                             const char *prop,
                                                             CORBA_Environment *opt_ev);
    void                matecomponent_ui_component_set_status      (MateComponentUIComponent *component,
                                                             const char *text,
                                                             CORBA_Environment *opt_ev);
                        MateComponentUIVerb;
    #define             MATECOMPONENT_UI_VERB                      (name,
                                                             cb)
    #define             MATECOMPONENT_UI_VERB_DATA                 (name,
                                                             cb,
                                                             data)
    #define             MATECOMPONENT_UI_UNSAFE_VERB               (name,
                                                             cb)
    #define             MATECOMPONENT_UI_UNSAFE_VERB_DATA          (name,
                                                             cb,
                                                             data)
    #define             MATECOMPONENT_UI_VERB_END
    void                matecomponent_ui_component_add_verb_list   (MateComponentUIComponent *component,
                                                             const MateComponentUIVerb *list);
    void                matecomponent_ui_component_add_verb_list_with_data
                                                            (MateComponentUIComponent *component,
                                                             const MateComponentUIVerb *list,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----MateComponentObject
             +----MateComponentUIComponent

## Signals

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

## Description

The MateComponentUIComponent 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 MateComponentUIContainer. 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 MateComponentUIComponent, if you implement a Control eg. a MateComponentUIComponent 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 matecomponent/doc/xml-ui.txt
     * For a standard template to base your UI on see matecomponent/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 (MateComponentControl *object,
                         gboolean       state,
                         gpointer       user_data)
    {
            MateComponentUIComponent *ui_component;
            /* Get UIComponent from control */
            ui_component = matecomponent_control_get_ui_component (control);
            if (state) /* Activate */
                    matecomponent_ui_component_set_translate (
                            ui_component, "/menu/File", my_ui_elements, NULL);
            else /* De-activate */
                    matecomponent_ui_component_unset_container (ui_component);
    }
    static void
    verb_foo_cb (MateComponentUIComponent *ui_container,
                 gpointer           user_data,
                 const              char *cname)
    {
            MateComponentControl *control = user_data;
            g_print ("FileFoo !\n");
    }
    static MateComponentUIVerb my_ui_verbs[] = {
            MATECOMPONENT_UI_VERB ("FileFoo", verb_foo_cb),
            MATECOMPONENT_UI_VERB_END
    };
    MateComponentObject *
    create_ui_control (void)
    {
            MateComponentControl     *control;
            MateComponentUIComponent *ui_component;
            GtkWidget         *widget;
            control = matecomponent_control_new ((widget = gtk_widget_new_label ("Hello World")));
            /* Automaticaly associate the remote UIContainer for us on activate */
            matecomponent_control_set_automerge (control, TRUE);
            ui_component = matecomponent_control_get_ui_component (control);
            /* Register the verbs with the UI Component */
            matecomponent_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 MATECOMPONENT_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 MateComponentUIComponent in this way, there is a `matecomponent_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 (MateComponentControl *object,
                         gboolean       state,
                         gpointer       user_data)
    {
            MateComponentUIComponent *ui_component;
            /* Get UIComponent from control */
            ui_component = matecomponent_control_get_ui_component (control);
            if (state) /* Activate */
                    /*
                     * Use a helper function to setup your UI from a file:
                     */
                    matecomponent_ui_util_set_ui (
                            ui_component, MY_COMPILE_TIME_PREFIX,
                            "MATE_MyApp.ui", "my-app");
            else /* De-activate */
                    matecomponent_ui_component_unset_container (ui_component);
    }

In this example "MATE_MyApp.ui" is the correctly namespaced UI xml filename, ( see doc/NAMESPACE to register your name ), and "my-app" is the mate application name, from which a path to your installed help files can be deduced.

## Details

### struct MateComponentUIComponent

    struct MateComponentUIComponent;

### MateComponentUIComponentPrivate

    typedef struct _MateComponentUIComponentPrivate MateComponentUIComponentPrivate;

### MateComponentUIListenerFn ()

    void                (*MateComponentUIListenerFn)               (MateComponentUIComponent *component,
                                                             const char *path,
                                                             MateComponent_UIComponent_EventType type,
                                                             const char *state,
                                                             gpointer user_data);

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

### MateComponentUIVerbFn ()

    void                (*MateComponentUIVerbFn)                   (MateComponentUIComponent *component,
                                                             gpointer user_data,
                                                             const char *cname);

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

### MateComponentUIComponentClass

    typedef struct {
    	MateComponentObjectClass          parent_class;

    	POA_MateComponent_UIComponent__epv epv;

    	gpointer dummy[6];

    	/* Signals */
    	void (*exec_verb) (MateComponentUIComponent *comp,
    			   const char        *cname);

    	void (*ui_event)  (MateComponentUIComponent *comp,
    			   const char        *path,
    			   MateComponent_UIComponent_EventType type,
    			   const char        *state);
    	/* Virtual XML Methods */
    	void (*freeze)    (MateComponentUIComponent *component,
    			   CORBA_Environment *opt_ev);

    	void (*thaw)      (MateComponentUIComponent *component,
    			   CORBA_Environment *opt_ev);

    	void (*xml_set)   (MateComponentUIComponent *component,
    			   const char        *path,
    			   const char        *xml,
    			   CORBA_Environment *ev);

    	CORBA_char *(*xml_get) (MateComponentUIComponent *component,
    				const char        *path,
    				gboolean           recurse,
    				CORBA_Environment *ev);

    	void (*xml_rm)    (MateComponentUIComponent *component,
    			   const char        *path,
    			   CORBA_Environment *ev);

    	void (*set_prop)  (MateComponentUIComponent *component,
    			   const char        *path,
    			   const char        *prop,
    			   const char        *value,
    			   CORBA_Environment *opt_ev);

    	gchar *(*get_prop) (MateComponentUIComponent *component,
    			    const char        *path,
    			    const char        *prop,
    			    CORBA_Environment *opt_ev);

    	gboolean (*exists) (MateComponentUIComponent *component,
    			    const char        *path,
    			    CORBA_Environment *ev);
    } MateComponentUIComponentClass;

### matecomponent_ui_component_construct ()

    MateComponentUIComponent * matecomponent_ui_component_construct       (MateComponentUIComponent *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

### matecomponent_ui_component_new ()

    MateComponentUIComponent * matecomponent_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

### matecomponent_ui_component_new_default ()

    MateComponentUIComponent * matecomponent_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

### matecomponent_ui_component_set_name ()

    void                matecomponent_ui_component_set_name        (MateComponentUIComponent *component,
                                                             const char *name);

Set the `name` of the UI `component`

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

### matecomponent_ui_component_get_name ()

    const char *        matecomponent_ui_component_get_name        (MateComponentUIComponent *component);

`component` : | the UI component
Returns : | the name of the UI `component`

### matecomponent_ui_component_set_container ()

    void                matecomponent_ui_component_set_container   (MateComponentUIComponent *component,
                                                             MateComponent_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` : |

### matecomponent_ui_component_unset_container ()

    void                matecomponent_ui_component_unset_container (MateComponentUIComponent *component,
                                                             CORBA_Environment *opt_ev);

This dis-associates the `component` from its associated MateComponentUIContainer.

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

### matecomponent_ui_component_get_container ()

    MateComponent_UIContainer  matecomponent_ui_component_get_container   (MateComponentUIComponent *component);

`component` : | the component.
Returns : | the associated remote container

### matecomponent_ui_component_add_verb ()

    void                matecomponent_ui_component_add_verb        (MateComponentUIComponent *component,
                                                             const char *cname,
                                                             MateComponentUIVerbFn 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

### matecomponent_ui_component_add_verb_full ()

    void                matecomponent_ui_component_add_verb_full   (MateComponentUIComponent *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` : |

### matecomponent_ui_component_remove_verb ()

    void                matecomponent_ui_component_remove_verb     (MateComponentUIComponent *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

### matecomponent_ui_component_remove_verb_by_closure ()

    void                matecomponent_ui_component_remove_verb_by_closure
                                                            (MateComponentUIComponent *component,
                                                             GClosure *closure);

remove any verb handled by `fn`.

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

### matecomponent_ui_component_add_listener ()

    void                matecomponent_ui_component_add_listener    (MateComponentUIComponent *component,
                                                             const char *id,
                                                             MateComponentUIListenerFn 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

### matecomponent_ui_component_add_listener_full ()

    void                matecomponent_ui_component_add_listener_full
                                                            (MateComponentUIComponent *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` : |

### matecomponent_ui_component_remove_listener ()

    void                matecomponent_ui_component_remove_listener (MateComponentUIComponent *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

### matecomponent_ui_component_remove_listener_by_closure ()

    void                matecomponent_ui_component_remove_listener_by_closure
                                                            (MateComponentUIComponent *component,
                                                             GClosure *closure);

`component` : |
`closure` : |

### matecomponent_ui_component_set ()

    void                matecomponent_ui_component_set             (MateComponentUIComponent *component,
                                                             const char *path,
                                                             const char *xml,
                                                             CORBA_Environment *opt_ev);

Set the `xml` fragment into the remote MateComponentUIContainer'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 matecomponent_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

### matecomponent_ui_component_set_translate ()

    void                matecomponent_ui_component_set_translate   (MateComponentUIComponent *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 MateComponentUIContainer.

`component` : | the component
`path` : | the path to set
`xml` : | the non translated xml to set
`opt_ev` : | the (optional) CORBA exception environment

### matecomponent_ui_component_set_tree ()

    void                matecomponent_ui_component_set_tree        (MateComponentUIComponent *component,
                                                             const char *path,
                                                             MateComponentUINode *node,
                                                             CORBA_Environment *ev);

Set the `xml` fragment into the remote MateComponentUIContainer's tree attached to `component` at the specified `path`

`component` : | the component
`path` : | the path to set
`node` : | the MateComponentUINode representation of an xml tree to set
`ev` : | the (optional) CORBA exception environment

### matecomponent_ui_component_rm ()

    void                matecomponent_ui_component_rm              (MateComponentUIComponent *component,
                                                             const char *path,
                                                             CORBA_Environment *ev);

This routine removes a chunk of the XML tree in the MateComponentUIContainer associated with `component` pointed to by `path`.

`component` : | the component
`path` : | the path to set
`ev` : | the (optional) CORBA exception environment

### matecomponent_ui_component_path_exists ()

    gboolean            matecomponent_ui_component_path_exists     (MateComponentUIComponent *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.

### matecomponent_ui_component_get ()

    CORBA_char *        matecomponent_ui_component_get             (MateComponentUIComponent *component,
                                                             const char *path,
                                                             gboolean recurse,
                                                             CORBA_Environment *opt_ev);

This routine fetches a chunk of the XML tree in the MateComponentUIContainer 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)

### matecomponent_ui_component_get_tree ()

    MateComponentUINode *      matecomponent_ui_component_get_tree        (MateComponentUIComponent *component,
                                                             const char *path,
                                                             gboolean recurse,
                                                             CORBA_Environment *opt_ev);

This routine fetches a chunk of the XML tree in the MateComponentUIContainer 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 MateComponentUINode XML representation

### matecomponent_ui_component_object_set ()

    void                matecomponent_ui_component_object_set      (MateComponentUIComponent *component,
                                                             const char *path,
                                                             MateComponent_Unknown control,
                                                             CORBA_Environment *opt_ev);

This registers the `control` CORBA object into the MateComponentUIContainer 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

### matecomponent_ui_component_object_get ()

    MateComponent_Unknown      matecomponent_ui_component_object_get      (MateComponentUIComponent *component,
                                                             const char *path,
                                                             CORBA_Environment *opt_ev);

This returns the `control` CORBA object registered with the MateComponentUIContainer associated with this `component` at the specified `path`.

`component` : | the component
`path` : | the path to set
`opt_ev` : |
Returns : | the associated remote CORBA object.

### matecomponent_ui_component_widget_set ()

    void                matecomponent_ui_component_widget_set      (MateComponentUIComponent *component,
                                                             const char *path,
                                                             GtkWidget *widget,
                                                             CORBA_Environment *opt_ev);

`component` : |
`path` : |
`widget` : |
`opt_ev` : |

### matecomponent_ui_component_freeze ()

    void                matecomponent_ui_component_freeze          (MateComponentUIComponent *component,
                                                             CORBA_Environment *opt_ev);

This increments the freeze count on the associated MateComponentUIContainer, (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` : |

### matecomponent_ui_component_thaw ()

    void                matecomponent_ui_component_thaw            (MateComponentUIComponent *component,
                                                             CORBA_Environment *opt_ev);

This decrements the freeze count on the remote associated MateComponentUIContainer, (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` : |

### matecomponent_ui_component_set_prop ()

    void                matecomponent_ui_component_set_prop        (MateComponentUIComponent *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

### matecomponent_ui_component_get_prop ()

    gchar *             matecomponent_ui_component_get_prop        (MateComponentUIComponent *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 MateComponentUIContainer 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.

### matecomponent_ui_component_set_status ()

    void                matecomponent_ui_component_set_status      (MateComponentUIComponent *component,
                                                             const char *text,
                                                             CORBA_Environment *opt_ev);

This sets the contents of the status bar to `text` in the remote MateComponentUIContainer 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` : |

### MateComponentUIVerb

    typedef struct {
    	const char    *cname;
    	MateComponentUIVerbFn cb;
    	gpointer       user_data;
    	gpointer       dummy;
    } MateComponentUIVerb;

### MATECOMPONENT_UI_VERB()

    #define MATECOMPONENT_UI_VERB(name,cb)                  { (name), (cb), NULL, NULL   }

This declares and fills a MateComponentUIVerb structure suitable for use in constructing a lost of verbs to add with matecomponent_ui_component_add_verb_list_with_data.

`name` : | the verb name
`cb` : | the callback function.

### MATECOMPONENT_UI_VERB_DATA()

    #define MATECOMPONENT_UI_VERB_DATA(name,cb,data)        { (name), (cb), (data), NULL }

This declares and fills a MateComponentUIVerb structure suitable for use in constructing a lost of verbs to add with matecomponent_ui_component_add_verb_list.

`name` : | the verb name
`cb` : | the callback function
`data` : | some associated user_data

### MATECOMPONENT_UI_UNSAFE_VERB()

    #define MATECOMPONENT_UI_UNSAFE_VERB(name,cb)           { (name), ((MateComponentUIVerbFn)(cb)), NULL, NULL   }

As MATECOMPONENT_UI_VERB, but unsafely casts `cb` to the correct type

`name` : | the verb name
`cb` : | the callback function.

### MATECOMPONENT_UI_UNSAFE_VERB_DATA()

    #define MATECOMPONENT_UI_UNSAFE_VERB_DATA(name,cb,data) { (name), ((MateComponentUIVerbFn)(cb)), (data), NULL }

As MATECOMPONENT_UI_VERB_DATA, but unsafely casts `cb` to the correct type

`name` : | the verb name
`cb` : | the callback function
`data` : | some associated user_data

### MATECOMPONENT_UI_VERB_END

    #define MATECOMPONENT_UI_VERB_END                       { NULL, NULL, NULL, NULL }

The terminator MateComponentUIVerb structure for a list of MateComponentUIVerbs.

### matecomponent_ui_component_add_verb_list ()

    void                matecomponent_ui_component_add_verb_list   (MateComponentUIComponent *component,
                                                             const MateComponentUIVerb *list);

Add a list of verbs with no associated user_data, you probably want matecomponent_ui_component_add_verb_list_with_data

`component` : | the component
`list` : | the list of verbs.

### matecomponent_ui_component_add_verb_list_with_data ()

    void                matecomponent_ui_component_add_verb_list_with_data
                                                            (MateComponentUIComponent *component,
                                                             const MateComponentUIVerb *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 MateComponentUIVerb terminated by MATECOMPONENT_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                      (MateComponentUIComponent *matecomponentuicomponent,
                                                            gchar             *arg1,
                                                            gpointer           user_data)              : Run First

`matecomponentuicomponent` : | 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                      (MateComponentUIComponent *matecomponentuicomponent,
                                                            gchar             *arg1,
                                                            gint               arg2,
                                                            gchar             *arg3,
                                                            gpointer           user_data)              : Run First

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

## See Also

MateComponentUIContainer, matecomponent-ui-util(3), MateComponentControl