BonoboUIEngine

BonoboUIEngine — The guts of the UI handler

Functions

void bonobo_ui_engine_deregister_dead_components ()
void bonobo_ui_engine_deregister_component_by_ref ()
void bonobo_ui_engine_deregister_component ()
void bonobo_ui_engine_register_component ()
GList * bonobo_ui_engine_get_component_names ()
Bonobo_Unknown bonobo_ui_engine_get_component ()
void bonobo_ui_engine_config_set_path ()
const char * bonobo_ui_engine_config_get_path ()
void bonobo_ui_engine_set_ui_container ()
BonoboUIContainer * bonobo_ui_engine_get_ui_container ()
void bonobo_ui_engine_freeze ()
void bonobo_ui_engine_thaw ()
void bonobo_ui_engine_update ()
BonoboUIEngine * bonobo_ui_engine_construct ()
BonoboUIEngine * bonobo_ui_engine_new ()
GObject * bonobo_ui_engine_get_view ()
void bonobo_ui_engine_add_sync ()
void bonobo_ui_engine_remove_sync ()
GSList * bonobo_ui_engine_get_syncs ()
void bonobo_ui_engine_update_node ()
void bonobo_ui_engine_queue_update ()
GtkWidget * bonobo_ui_engine_build_control ()
BonoboUINode * bonobo_ui_engine_widget_get_node ()
void bonobo_ui_engine_widget_set_node ()
BonoboUIError bonobo_ui_engine_xml_set_prop ()
CORBA_char * bonobo_ui_engine_xml_get_prop ()
void bonobo_ui_engine_prune_widget_info ()
BonoboUINode * bonobo_ui_engine_get_path ()
void bonobo_ui_engine_dirty_tree ()
void bonobo_ui_engine_clean_tree ()
void bonobo_ui_engine_dump ()
CORBA_Object bonobo_ui_engine_node_get_object ()
gboolean bonobo_ui_engine_node_is_dirty ()
GtkWidget * bonobo_ui_engine_node_get_widget ()
const char * bonobo_ui_engine_node_get_id ()
BonoboUINode * bonobo_ui_engine_get_cmd_node ()
void bonobo_ui_engine_node_set_dirty ()
void bonobo_ui_engine_stamp_custom ()
void bonobo_ui_engine_widget_set ()
void bonobo_ui_engine_stamp_root ()
void bonobo_ui_engine_add_hint ()
void bonobo_ui_engine_remove_hint ()
void bonobo_ui_engine_emit_verb_on ()
void bonobo_ui_engine_emit_event_on ()
void bonobo_ui_engine_emit_verb_on_w ()
void bonobo_ui_engine_emit_event_on_w ()
char * bonobo_ui_engine_get_attr ()
void bonobo_ui_engine_widget_attach_node ()
CORBA_char * bonobo_ui_engine_xml_get ()
gboolean bonobo_ui_engine_xml_node_exists ()
BonoboUIError bonobo_ui_engine_xml_merge_tree ()
BonoboUIError bonobo_ui_engine_xml_rm ()
BonoboUIError bonobo_ui_engine_object_set ()
BonoboUIError bonobo_ui_engine_object_get ()
void bonobo_ui_engine_exec_verb ()
void bonobo_ui_engine_ui_event ()

Signals

void add-hint Run Last
void destroy Run Last
void emit-event-on Run Last
void emit-verb-on Run Last
void remove-hint Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── BonoboUIEngine

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 7. How to make your UI user configurable

1
2
3
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 8. User configuration format

1
2
[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.

Functions

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.

Parameters

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 .

Parameters

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 .

Parameters

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 .

Parameters

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

Parameters

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

Parameters

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


bonobo_ui_engine_config_get_path ()

const char *
bonobo_ui_engine_config_get_path (BonoboUIEngine *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.

Parameters

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

Parameters

engine

the engine

 

Returns

the associated UI container.


bonobo_ui_engine_freeze ()

void
bonobo_ui_engine_freeze (BonoboUIEngine *engine);

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.

Parameters

engine

the engine

 

bonobo_ui_engine_thaw ()

void
bonobo_ui_engine_thaw (BonoboUIEngine *engine);

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

Parameters

engine

the engine

 

bonobo_ui_engine_update ()

void
bonobo_ui_engine_update (BonoboUIEngine *engine);

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

Parameters

engine

the engine.

 

bonobo_ui_engine_construct ()

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

Construct a new bonobo_ui_engine

Parameters

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

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

engine

the engine

 

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

engine

the engine

 

path

the path into the tree

 

prop

The property

 

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

engine

the engine

 

node

the node

 

bonobo_ui_engine_widget_set ()

void
bonobo_ui_engine_widget_set (BonoboUIEngine *engine,
                             const char *path,
                             GtkWidget *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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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

Parameters

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.

Parameters

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

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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


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

Types and Values

struct BonoboUIEngine

struct BonoboUIEngine;


enum BonoboUIError

Members

BONOBO_UI_ERROR_OK

   

BONOBO_UI_ERROR_BAD_PARAM

   

BONOBO_UI_ERROR_INVALID_PATH

   

BONOBO_UI_ERROR_INVALID_XML

   

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;

Signal Details

The “add-hint” signal

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

Parameters

bonobouiengine

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “destroy” signal

void
user_function (BonoboUIEngine *bonobouiengine,
               gpointer        user_data)

Parameters

bonobouiengine

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “emit-event-on” signal

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

Parameters

bonobouiengine

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “emit-verb-on” signal

void
user_function (BonoboUIEngine *bonobouiengine,
               gpointer        arg1,
               gpointer        user_data)

Parameters

bonobouiengine

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “remove-hint” signal

void
user_function (BonoboUIEngine *bonobouiengine,
               gpointer        user_data)

Parameters

bonobouiengine

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last