## BonoboUIEngine

BonoboUIEngine — The guts of the UI handler

## Synopsis

                BonoboUIEngine;
    void        bonobo_ui_engine_deregister_dead_components
                                                (BonoboUIEngine *engine);
    void        bonobo_ui_engine_deregister_component_by_ref
                                                (BonoboUIEngine *engine,
                                                 Bonobo_Unknown ref);
    void        bonobo_ui_engine_deregister_component
                                                (BonoboUIEngine *engine,
                                                 const char *name);
    void        bonobo_ui_engine_register_component
                                                (BonoboUIEngine *engine,
                                                 const char *name,
                                                 Bonobo_Unknown component);
    GList*      bonobo_ui_engine_get_component_names
                                                (BonoboUIEngine *engine);
    Bonobo_Unknown bonobo_ui_engine_get_component
                                                (BonoboUIEngine *engine,
                                                 const char *name);
    void        bonobo_ui_engine_config_set_path
                                                (BonoboUIEngine *engine,
                                                 const char *path);
    const char* bonobo_ui_engine_config_get_path
                                                (BonoboUIEngine *engine);
    void        bonobo_ui_engine_set_ui_container
                                                (BonoboUIEngine *engine,
                                                 BonoboUIContainer *ui_container);
    BonoboUIContainer* bonobo_ui_engine_get_ui_container
                                                (BonoboUIEngine *engine);
    void        bonobo_ui_engine_freeze         (BonoboUIEngine *engine);
    void        bonobo_ui_engine_thaw           (BonoboUIEngine *engine);
    void        bonobo_ui_engine_update         (BonoboUIEngine *engine);
    enum        BonoboUIError;
                BonoboUIEnginePrivate;
                BonoboUIEngineClass;
    BonoboUIEngine* bonobo_ui_engine_construct  (BonoboUIEngine *engine,
                                                 GObject *view);
    BonoboUIEngine* bonobo_ui_engine_new        (GObject *view);
    GObject*    bonobo_ui_engine_get_view       (BonoboUIEngine *engine);
    void        bonobo_ui_engine_add_sync       (BonoboUIEngine *engine,
                                                 BonoboUISync *sync);
    void        bonobo_ui_engine_remove_sync    (BonoboUIEngine *engine,
                                                 BonoboUISync *sync);
    GSList*     bonobo_ui_engine_get_syncs      (BonoboUIEngine *engine);
    void        bonobo_ui_engine_update_node    (BonoboUIEngine *engine,
                                                 BonoboUISync *sync,
                                                 BonoboUINode *node);
    void        bonobo_ui_engine_queue_update   (BonoboUIEngine *engine,
                                                 GtkWidget *widget,
                                                 BonoboUINode *node,
                                                 BonoboUINode *cmd_node);
    GtkWidget*  bonobo_ui_engine_build_control  (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    BonoboUINode* bonobo_ui_engine_widget_get_node
                                                (GtkWidget *widget);
    void        bonobo_ui_engine_widget_set_node
                                                (BonoboUIEngine *engine,
                                                 GtkWidget *widget,
                                                 BonoboUINode *node);
    BonoboUIError bonobo_ui_engine_xml_set_prop (BonoboUIEngine *engine,
                                                 const char *path,
                                                 const char *property,
                                                 const char *value,
                                                 const char *component);
    CORBA_char* bonobo_ui_engine_xml_get_prop   (BonoboUIEngine *engine,
                                                 const char *path,
                                                 const char *prop,
                                                 gboolean *invalid_path);
    void        bonobo_ui_engine_prune_widget_info
                                                (BonoboUIEngine *engine,
                                                 BonoboUINode *node,
                                                 gboolean save_custom);
    BonoboUINode* bonobo_ui_engine_get_path     (BonoboUIEngine *engine,
                                                 const char *path);
    void        bonobo_ui_engine_dirty_tree     (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    void        bonobo_ui_engine_clean_tree     (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    void        bonobo_ui_engine_dump           (BonoboUIEngine *engine,
                                                 FILE *out,
                                                 const char *msg);
    CORBA_Object bonobo_ui_engine_node_get_object
                                                (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    gboolean    bonobo_ui_engine_node_is_dirty  (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    GtkWidget*  bonobo_ui_engine_node_get_widget
                                                (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    const char* bonobo_ui_engine_node_get_id    (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    BonoboUINode* bonobo_ui_engine_get_cmd_node (BonoboUIEngine *engine,
                                                 BonoboUINode *from_node);
    void        bonobo_ui_engine_node_set_dirty (BonoboUIEngine *engine,
                                                 BonoboUINode *node,
                                                 gboolean dirty);
    void        bonobo_ui_engine_stamp_custom   (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    void        bonobo_ui_engine_widget_set     (BonoboUIEngine *engine,
                                                 const char *path,
                                                 GtkWidget *widget);
    void        bonobo_ui_engine_stamp_root     (BonoboUIEngine *engine,
                                                 BonoboUINode *node,
                                                 GtkWidget *widget);
    void        bonobo_ui_engine_add_hint       (BonoboUIEngine *engine,
                                                 const char *str);
    void        bonobo_ui_engine_remove_hint    (BonoboUIEngine *engine);
    void        bonobo_ui_engine_emit_verb_on   (BonoboUIEngine *engine,
                                                 BonoboUINode *node);
    void        bonobo_ui_engine_emit_event_on  (BonoboUIEngine *engine,
                                                 BonoboUINode *node,
                                                 const char *state);
    void        bonobo_ui_engine_emit_verb_on_w (BonoboUIEngine *engine,
                                                 GtkWidget *widget);
    void        bonobo_ui_engine_emit_event_on_w
                                                (BonoboUIEngine *engine,
                                                 GtkWidget *widget,
                                                 const char *state);
    char*       bonobo_ui_engine_get_attr       (BonoboUINode *node,
                                                 BonoboUINode *cmd_node,
                                                 const char *attr);
    void        bonobo_ui_engine_widget_attach_node
                                                (GtkWidget *widget,
                                                 BonoboUINode *node);
    CORBA_char* bonobo_ui_engine_xml_get        (BonoboUIEngine *engine,
                                                 const char *path,
                                                 gboolean node_only);
    gboolean    bonobo_ui_engine_xml_node_exists
                                                (BonoboUIEngine *engine,
                                                 const char *path);
    BonoboUIError bonobo_ui_engine_xml_merge_tree
                                                (BonoboUIEngine *engine,
                                                 const char *path,
                                                 BonoboUINode *tree,
                                                 const char *component);
    BonoboUIError bonobo_ui_engine_xml_rm       (BonoboUIEngine *engine,
                                                 const char *path,
                                                 const char *by_component);
    BonoboUIError bonobo_ui_engine_object_set   (BonoboUIEngine *engine,
                                                 const char *path,
                                                 Bonobo_Unknown object,
                                                 CORBA_Environment *ev);
    BonoboUIError bonobo_ui_engine_object_get   (BonoboUIEngine *engine,
                                                 const char *path,
                                                 Bonobo_Unknown *object,
                                                 CORBA_Environment *ev);
    void        bonobo_ui_engine_exec_verb      (BonoboUIEngine *engine,
                                                 const CORBA_char *cname,
                                                 CORBA_Environment *ev);
    void        bonobo_ui_engine_ui_event       (BonoboUIEngine *engine,
                                                 const CORBA_char *id,
                                                 const Bonobo_UIComponent_EventType type,
                                                 const CORBA_char *state,
                                                 CORBA_Environment *ev);

## Object Hierarchy

      GObject
       +----BonoboUIEngine

## Signals

    "add-hint"  void        user_function      (BonoboUIEngine *bonobouiengine,
                                                gchar          *arg1,
                                                gpointer        user_data)           : Run last
    "destroy"   void        user_function      (BonoboUIEngine *bonobouiengine,
                                                gpointer        user_data)           : Run last
    "emit-event-on"
                void        user_function      (BonoboUIEngine *bonobouiengine,
                                                gpointer        arg1,
                                                gchar          *arg2,
                                                gpointer        user_data)           : Run last
    "emit-verb-on"
                void        user_function      (BonoboUIEngine *bonobouiengine,
                                                gpointer        arg1,
                                                gpointer        user_data)           : Run last
    "remove-hint"
                void        user_function      (BonoboUIEngine *bonobouiengine,
                                                gpointer        user_data)           : Run last

## Description

The Bonobo UI code as exposed through the BonoboWindow, BonoboUIComponent and BonoboUIContainer API's use the BonoboUIEngine. The Engine effectively maintains a BonoboUIXml tree internaly, and a list of BonoboUISync synchronizers that, when the tree changes are used to re-sync the associated widgets with the XML model.

The Engine can be tweaked by getting its pointer from an associated BonoboWindow eg. this can be useful for setting the configuration path. To allow a BonoboWindow to be configurable you need to do:

Example 4. How to make your UI user configurable

    bonobo_ui_engine_config_set_path (
    	bonobo_window_get_ui_engine (win),
    	"/my-application-name/UIConfig/kvps");

where "UIConfig/kvps" is some convenient path into your gnome_config file.

Key value pairs (kvps) are stored in this, mangled into a comma delimited string and these are used to clobber the XML on merges, eg.

Example 5. User configuration format

    [UIConfig]
    kvps=/Toolbar:look:both

inside your ~/.gnome/my-application-name file, will ensure that whenever the item with path '/Toolbar' is modified the 'look="both"' attribute will be stamped onto it, effecively forcing a certain look.

## Details

### BonoboUIEngine

    typedef struct _BonoboUIEngine BonoboUIEngine;

### bonobo_ui_engine_deregister_dead_components ()

    void        bonobo_ui_engine_deregister_dead_components
                                                (BonoboUIEngine *engine);

Detect any components that have died and deregister them - unmerging their UI elements.

`engine` : | the engine

### bonobo_ui_engine_deregister_component_by_ref ()

    void        bonobo_ui_engine_deregister_component_by_ref
                                                (BonoboUIEngine *engine,
                                                 Bonobo_Unknown ref);

Deregisters component with reference `ref` from `engine`.

`engine` : | the engine
`ref` : | the ref.

### bonobo_ui_engine_deregister_component ()

    void        bonobo_ui_engine_deregister_component
                                                (BonoboUIEngine *engine,
                                                 const char *name);

Deregisters component of `name` from `engine`.

`engine` : | the engine
`name` : | the component name

### bonobo_ui_engine_register_component ()

    void        bonobo_ui_engine_register_component
                                                (BonoboUIEngine *engine,
                                                 const char *name,
                                                 Bonobo_Unknown component);

Registers `component` with `engine` by `name`.

`engine` : | the engine
`name` : | a name to associate a component with
`component` : | the component

### bonobo_ui_engine_get_component_names ()

    GList*      bonobo_ui_engine_get_component_names
                                                (BonoboUIEngine *engine);

`engine` : | the engine
Returns : | the names of all registered components

### bonobo_ui_engine_get_component ()

    Bonobo_Unknown bonobo_ui_engine_get_component
                                                (BonoboUIEngine *engine,
                                                 const char *name);

`engine` : | the engine
`name` : | the name of the component to fetch
Returns : | the component with name `name`

### bonobo_ui_engine_config_set_path ()

    void        bonobo_ui_engine_config_set_path
                                                (BonoboUIEngine *engine,
                                                 const char *path);

`engine` : |
`path` : |

### bonobo_ui_engine_config_get_path ()

    const char* bonobo_ui_engine_config_get_path
                                                (BonoboUIEngine *engine);

`engine` : |
Returns : |

### bonobo_ui_engine_set_ui_container ()

    void        bonobo_ui_engine_set_ui_container
                                                (BonoboUIEngine *engine,
                                                 BonoboUIContainer *ui_container);

Associates a given UI Container with this BonoboUIEngine.

`engine` : | the engine
`ui_container` : | a UI Container bonobo object.

### bonobo_ui_engine_get_ui_container ()

    BonoboUIContainer* bonobo_ui_engine_get_ui_container
                                                (BonoboUIEngine *engine);

Fetches the associated UI Container

`engine` : | the engine
Returns : | the associated UI container.

### bonobo_ui_engine_freeze ()

    void        bonobo_ui_engine_freeze         (BonoboUIEngine *engine);

### Warning

`bonobo_ui_engine_freeze` is deprecated and should not be used in newly-written code.

This increments the freeze count on the tree, while this count > 0 no syncronization between the internal XML model and the widget views occurs. This means that many simple merges can be glupped together with little performance impact and overhead.

`engine` : | the engine

### bonobo_ui_engine_thaw ()

    void        bonobo_ui_engine_thaw           (BonoboUIEngine *engine);

### Warning

`bonobo_ui_engine_thaw` is deprecated and should not be used in newly-written code.

This decrements the freeze count and if it is 0 causes the UI widgets to be re-synched with the XML model, see also bonobo_ui_engine_freeze

`engine` : | the engine

### bonobo_ui_engine_update ()

    void        bonobo_ui_engine_update         (BonoboUIEngine *engine);

### Warning

`bonobo_ui_engine_update` is deprecated and should not be used in newly-written code.

This function is called to update the entire UI model synchronizing any changes in it with the widget tree where neccessary

`engine` : | the engine.

### enum BonoboUIError

    typedef enum {
    	BONOBO_UI_ERROR_OK = 0,
    	BONOBO_UI_ERROR_BAD_PARAM,
    	BONOBO_UI_ERROR_INVALID_PATH,
    	BONOBO_UI_ERROR_INVALID_XML
    } BonoboUIError;

### BonoboUIEnginePrivate

    typedef struct _BonoboUIEnginePrivate BonoboUIEnginePrivate;

### BonoboUIEngineClass

    typedef struct {
    	GObjectClass parent_class;

    	/* Signals */
    	void (*add_hint)      (BonoboUIEngine *engine,
    			       const char     *str);
    	void (*remove_hint)   (BonoboUIEngine *engine);

    	void (*emit_verb_on)  (BonoboUIEngine *engine,
    			       BonoboUINode   *node);

    	void (*emit_event_on) (BonoboUIEngine *engine,
    			       BonoboUINode   *node,
    			       const char     *state);

    	void (*destroy)       (BonoboUIEngine *engine);
    } BonoboUIEngineClass;

### bonobo_ui_engine_construct ()

    BonoboUIEngine* bonobo_ui_engine_construct  (BonoboUIEngine *engine,
                                                 GObject *view);

Construct a new bonobo_ui_engine

`engine` : | the engine.
`view` : | the view [ often a BonoboWindow ]
Returns : | the constructed engine.

### bonobo_ui_engine_new ()

    BonoboUIEngine* bonobo_ui_engine_new        (GObject *view);

Create a new BonoboUIEngine structure

`view` : |
Returns : | the new UI Engine.

### bonobo_ui_engine_get_view ()

    GObject*    bonobo_ui_engine_get_view       (BonoboUIEngine *engine);

This returns the associated view, often a BonoboWindow

`engine` : | the engine
Returns : | the view widget.

### bonobo_ui_engine_add_sync ()

    void        bonobo_ui_engine_add_sync       (BonoboUIEngine *engine,
                                                 BonoboUISync *sync);

Add a BonoboUISync synchronizer to the engine

`engine` : | the enginer
`sync` : | the synchronizer

### bonobo_ui_engine_remove_sync ()

    void        bonobo_ui_engine_remove_sync    (BonoboUIEngine *engine,
                                                 BonoboUISync *sync);

Remove a specified BonoboUISync synchronizer from the engine

`engine` : | the engine
`sync` : | the sync

### bonobo_ui_engine_get_syncs ()

    GSList*     bonobo_ui_engine_get_syncs      (BonoboUIEngine *engine);

Retrieve a list of available synchronizers.

`engine` : | the engine
Returns : | a GSList of BonoboUISync s

### bonobo_ui_engine_update_node ()

    void        bonobo_ui_engine_update_node    (BonoboUIEngine *engine,
                                                 BonoboUISync *sync,
                                                 BonoboUINode *node);

This function is used to write recursive synchronizers and is intended only for internal / privilaged use.

By the time this returns, due to re-enterancy, node points at undefined memory.

`engine` : | the engine
`sync` : |
`node` : | the node to start updating.

### bonobo_ui_engine_queue_update ()

    void        bonobo_ui_engine_queue_update   (BonoboUIEngine *engine,
                                                 GtkWidget *widget,
                                                 BonoboUINode *node,
                                                 BonoboUINode *cmd_node);

This function is used to queue a state update on `widget`, essentialy transfering any state from the XML model into the widget view. This is queued to avoid re-enterancy problems.

`engine` : | the engine
`widget` : | the widget to update later
`node` : | the node
`cmd_node` : | the associated command's node

### bonobo_ui_engine_build_control ()

    GtkWidget*  bonobo_ui_engine_build_control  (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

A helper function for synchronizers, this creates a control if possible from the node's associated object, stamps the node as containing a control and sets its widget.

`engine` : | the engine
`node` : | the control node.
Returns : | a Control's GtkWidget.

### bonobo_ui_engine_widget_get_node ()

    BonoboUINode* bonobo_ui_engine_widget_get_node
                                                (GtkWidget *widget);

`widget` : | the widget
Returns : | the BonoboUINode associated with this widget

### bonobo_ui_engine_widget_set_node ()

    void        bonobo_ui_engine_widget_set_node
                                                (BonoboUIEngine *engine,
                                                 GtkWidget *widget,
                                                 BonoboUINode *node);

Used internaly to associate a widget with a node, some synchronisers need to be able to execute code on widget creation.

`engine` : | the engine
`widget` : | the widget
`node` : | the node

### bonobo_ui_engine_xml_set_prop ()

    BonoboUIError bonobo_ui_engine_xml_set_prop (BonoboUIEngine *engine,
                                                 const char *path,
                                                 const char *property,
                                                 const char *value,
                                                 const char *component);

This function sets the property of a node in the internal tree representation at `path` in `engine`.

`engine` : | the engine
`path` : | the path into the tree
`property` : | The property to set
`value` : | The new value of the property
`component` : | the component ID associated with the nodes.
Returns : | flag on error

### bonobo_ui_engine_xml_get_prop ()

    CORBA_char* bonobo_ui_engine_xml_get_prop   (BonoboUIEngine *engine,
                                                 const char *path,
                                                 const char *prop,
                                                 gboolean *invalid_path);

This function fetches the property `prop` at node at `path` in the internal structure.

`engine` : | the engine
`path` : | the path into the tree
`prop` : | The property
`invalid_path` : |
Returns : | a CORBA allocated string

### bonobo_ui_engine_prune_widget_info ()

    void        bonobo_ui_engine_prune_widget_info
                                                (BonoboUIEngine *engine,
                                                 BonoboUINode *node,
                                                 gboolean save_custom);

This function destroys any widgets associated with `node` and all its children, if `save_custom`, any widget that is a custom widget ( such as a control ) will be preserved. All widgets flagged ROOT are preserved always.

`engine` : | the engine
`node` : | the node
`save_custom` : | whether to save custom widgets

### bonobo_ui_engine_get_path ()

    BonoboUINode* bonobo_ui_engine_get_path     (BonoboUIEngine *engine,
                                                 const char *path);

This routine gets a node from the internal XML tree pointed at by `path`

`engine` : | the engine.
`path` : | the path into the tree
Returns : | the node.

### bonobo_ui_engine_dirty_tree ()

    void        bonobo_ui_engine_dirty_tree     (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

Mark all the node's children as being dirty and needing a re-synch with their widget views.

`engine` : | the engine
`node` : | the node

### bonobo_ui_engine_clean_tree ()

    void        bonobo_ui_engine_clean_tree     (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

This cleans the tree, marking the node and its children as not needing a re-synch with their widget views.

`engine` : | the engine
`node` : | the node

### bonobo_ui_engine_dump ()

    void        bonobo_ui_engine_dump           (BonoboUIEngine *engine,
                                                 FILE *out,
                                                 const char *msg);

This is a debugging function mostly for internal and testing use, it dumps the XML tree, including the associated, and overridden nodes in a wierd hackish format to the `out` stream with the helpful `msg` prepended.

`engine` : | the engine
`out` : | the FILE stream to dump to
`msg` : | user visible message

### bonobo_ui_engine_node_get_object ()

    CORBA_Object bonobo_ui_engine_node_get_object
                                                (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

`engine` : | the engine
`node` : | the node
Returns : | the CORBA_Object associated with a `node`

### bonobo_ui_engine_node_is_dirty ()

    gboolean    bonobo_ui_engine_node_is_dirty  (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

`engine` : | the engine
`node` : | the node
Returns : | whether the `node` is marked dirty

### bonobo_ui_engine_node_get_widget ()

    GtkWidget*  bonobo_ui_engine_node_get_widget
                                                (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

Gets the widget associated with `node`

`engine` : | the engine
`node` : | the node
Returns : | the widget

### bonobo_ui_engine_node_get_id ()

    const char* bonobo_ui_engine_node_get_id    (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

Each component has an associated textual id or name - see bonobo_ui_engine_register_component

`engine` : | the engine
`node` : | the node
Returns : | the component id associated with the node

### bonobo_ui_engine_get_cmd_node ()

    BonoboUINode* bonobo_ui_engine_get_cmd_node (BonoboUIEngine *engine,
                                                 BonoboUINode *from_node);

This function seeks the command node associated with `from_node` in `engine` 's internal tree.

`engine` : | the engine
`from_node` : | the node
Returns : | the command node or NULL

### bonobo_ui_engine_node_set_dirty ()

    void        bonobo_ui_engine_node_set_dirty (BonoboUIEngine *engine,
                                                 BonoboUINode *node,
                                                 gboolean dirty);

Set `node` s dirty bit to `dirty`.

`engine` : | the engine
`node` : | the node
`dirty` : | whether the node should be dirty.

### bonobo_ui_engine_stamp_custom ()

    void        bonobo_ui_engine_stamp_custom   (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

Marks a node as containing a custom widget.

`engine` : | the engine
`node` : | the node

### bonobo_ui_engine_widget_set ()

    void        bonobo_ui_engine_widget_set     (BonoboUIEngine *engine,
                                                 const char *path,
                                                 GtkWidget *widget);

`engine` : |
`path` : |
`widget` : |

### bonobo_ui_engine_stamp_root ()

    void        bonobo_ui_engine_stamp_root     (BonoboUIEngine *engine,
                                                 BonoboUINode *node,
                                                 GtkWidget *widget);

This stamps `node` with `widget` which is marked as being a ROOT node, so the engine will never destroy it.

`engine` : | the engine
`node` : | the node
`widget` : | the root widget

### bonobo_ui_engine_add_hint ()

    void        bonobo_ui_engine_add_hint       (BonoboUIEngine *engine,
                                                 const char *str);

This fires the 'add_hint' signal.

`engine` : | the engine
`str` : | the hint string

### bonobo_ui_engine_remove_hint ()

    void        bonobo_ui_engine_remove_hint    (BonoboUIEngine *engine);

This fires the 'remove_hint' signal

`engine` : | the engine

### bonobo_ui_engine_emit_verb_on ()

    void        bonobo_ui_engine_emit_verb_on   (BonoboUIEngine *engine,
                                                 BonoboUINode *node);

This fires the 'emit_verb' signal

`engine` : | the engine
`node` : | the node

### bonobo_ui_engine_emit_event_on ()

    void        bonobo_ui_engine_emit_event_on  (BonoboUIEngine *engine,
                                                 BonoboUINode *node,
                                                 const char *state);

This fires the 'emit_event_on' signal

`engine` : | the engine
`node` : | the node
`state` : | the new state of the node

### bonobo_ui_engine_emit_verb_on_w ()

    void        bonobo_ui_engine_emit_verb_on_w (BonoboUIEngine *engine,
                                                 GtkWidget *widget);

This function looks up the node from `widget` and emits the 'emit_verb_on' signal on that node.

`engine` : | the engine
`widget` : | the widget

### bonobo_ui_engine_emit_event_on_w ()

    void        bonobo_ui_engine_emit_event_on_w
                                                (BonoboUIEngine *engine,
                                                 GtkWidget *widget,
                                                 const char *state);

This function looks up the node from `widget` and emits the 'emit_event_on' signal on that node passint `state` as the new state.

`engine` : | the engine
`widget` : | the widget
`state` : | the new state

### bonobo_ui_engine_get_attr ()

    char*       bonobo_ui_engine_get_attr       (BonoboUINode *node,
                                                 BonoboUINode *cmd_node,
                                                 const char *attr);

This function is used to get node attributes in many UI synchronizers, it first attempts to get the attribute from `node`, and if this fails falls back to `cmd_node`.

`node` : | the node
`cmd_node` : | the command's node
`attr` : | the attribute name
Returns : | the attr or NULL if it doesn't exist.

### bonobo_ui_engine_widget_attach_node ()

    void        bonobo_ui_engine_widget_attach_node
                                                (GtkWidget *widget,
                                                 BonoboUINode *node);

Associate `node` with `widget`

`widget` : | the widget
`node` : | the node

### bonobo_ui_engine_xml_get ()

    CORBA_char* bonobo_ui_engine_xml_get        (BonoboUIEngine *engine,
                                                 const char *path,
                                                 gboolean node_only);

This function fetches the node at `path` in the internal structure, and if `node_only` dumps the node to an XML string, otherwise it dumps it and its children.

`engine` : | the engine
`path` : | the path into the tree
`node_only` : | just the node, or children too.
Returns : | the XML string - use CORBA_free to free

### bonobo_ui_engine_xml_node_exists ()

    gboolean    bonobo_ui_engine_xml_node_exists
                                                (BonoboUIEngine *engine,
                                                 const char *path);

`engine` : | the engine
`path` : | the path into the tree
Returns : | true if the node at `path` exists

### bonobo_ui_engine_xml_merge_tree ()

    BonoboUIError bonobo_ui_engine_xml_merge_tree
                                                (BonoboUIEngine *engine,
                                                 const char *path,
                                                 BonoboUINode *tree,
                                                 const char *component);

This function merges the XML `tree` into the internal tree representation as children of the node at `path` in `engine`.

`engine` : | the engine
`path` : | the path into the tree
`tree` : | the nodes
`component` : | the component ID associated with these nodes.
Returns : | flag on error

### bonobo_ui_engine_xml_rm ()

    BonoboUIError bonobo_ui_engine_xml_rm       (BonoboUIEngine *engine,
                                                 const char *path,
                                                 const char *by_component);

Remove a chunk of the xml tree pointed at by `path` in `engine`, if `by_component` then only remove items associated with that component - possibly revealing other overridden items.

`engine` : | the engine
`path` : | the path into the tree
`by_component` : | whether to remove elements from only a specific component
Returns : | flag on error

### bonobo_ui_engine_object_set ()

    BonoboUIError bonobo_ui_engine_object_set   (BonoboUIEngine *engine,
                                                 const char *path,
                                                 Bonobo_Unknown object,
                                                 CORBA_Environment *ev);

This associates a CORBA Object reference with a node in the tree, most often this is done to insert a Control's reference into a 'control' element.

`engine` : | the engine
`path` : | the path into the tree
`object` : | an object reference
`ev` : | CORBA exception environment
Returns : | flag if success

### bonobo_ui_engine_object_get ()

    BonoboUIError bonobo_ui_engine_object_get   (BonoboUIEngine *engine,
                                                 const char *path,
                                                 Bonobo_Unknown *object,
                                                 CORBA_Environment *ev);

This extracts a CORBA object reference associated with the node at `path` in `engine`, and returns it in the reference pointed to by `object`.

`engine` : | the engine
`path` : | the path into the tree
`object` : | an pointer to an object reference
`ev` : | CORBA exception environment
Returns : | flag if success

### bonobo_ui_engine_exec_verb ()

    void        bonobo_ui_engine_exec_verb      (BonoboUIEngine *engine,
                                                 const CORBA_char *cname,
                                                 CORBA_Environment *ev);

`engine` : |
`cname` : |
`ev` : |

### bonobo_ui_engine_ui_event ()

    void        bonobo_ui_engine_ui_event       (BonoboUIEngine *engine,
                                                 const CORBA_char *id,
                                                 const Bonobo_UIComponent_EventType type,
                                                 const CORBA_char *state,
                                                 CORBA_Environment *ev);

`engine` : |
`id` : |
`type` : |
`state` : |
`ev` : |

## Signal Details

### The "add-hint" signal

    void        user_function                  (BonoboUIEngine *bonobouiengine,
                                                gchar          *arg1,
                                                gpointer        user_data)           : Run last

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

### The "destroy" signal

    void        user_function                  (BonoboUIEngine *bonobouiengine,
                                                gpointer        user_data)           : Run last

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

### The "emit-event-on" signal

    void        user_function                  (BonoboUIEngine *bonobouiengine,
                                                gpointer        arg1,
                                                gchar          *arg2,
                                                gpointer        user_data)           : Run last

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

### The "emit-verb-on" signal

    void        user_function                  (BonoboUIEngine *bonobouiengine,
                                                gpointer        arg1,
                                                gpointer        user_data)           : Run last

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

### The "remove-hint" signal

    void        user_function                  (BonoboUIEngine *bonobouiengine,
                                                gpointer        user_data)           : Run last

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