| LibBonoboUI API Reference Manual |
|---|
BonoboUIEngine — The guts of the UI handler
struct 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; struct BonoboUIEnginePrivate; typedef 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, constCORBA_char *cname,CORBA_Environment *ev); void bonobo_ui_engine_ui_event (BonoboUIEngine *engine, constCORBA_char *id, constBonobo_UIComponent_EventType type, constCORBA_char *state,CORBA_Environment *ev);
GObject +----BonoboUIEngine
"add-hint" void user_function (BonoboUIEngine *bonobouiengine,gchar *arg1,gpointer user_data); "destroy" void user_function (BonoboUIEngine *bonobouiengine,gpointer user_data); "emit-event-on" void user_function (BonoboUIEngine *bonobouiengine,gpointer arg1,gchar *arg2,gpointer user_data); "emit-verb-on" void user_function (BonoboUIEngine *bonobouiengine,gpointer arg1,gpointer user_data); "remove-hint" void user_function (BonoboUIEngine *bonobouiengine,gpointer user_data);
The Bonobo UI code as exposed through the BonoboWindow,
BonoboUIComponent and BonoboUIContainer API's use the
BonoboUIEngine. The Engine effectively maintains a
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.
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.
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 |
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. |
void bonobo_ui_engine_deregister_component
(BonoboUIEngine *engine,
const char *name);Deregisters component of name from engine.
| engine : | the engine |
| name : | the component name |
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 |
GList * bonobo_ui_engine_get_component_names (BonoboUIEngine *engine);
| engine : | the engine |
| Returns : | the names of all registered components |
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 |
void bonobo_ui_engine_config_set_path
(BonoboUIEngine *engine,
const char *path);
| engine : | |
| path : |
const char* bonobo_ui_engine_config_get_path
(BonoboUIEngine *engine);
| engine : | |
| Returns : |
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. |
BonoboUIContainer* bonobo_ui_engine_get_ui_container (BonoboUIEngine *engine);
Fetches the associated UI Container
| engine : | the engine |
| Returns : | the associated UI container. |
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.
| engine : | the engine |
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
| engine : | the engine |
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
| engine : | the engine. |
typedef enum {
BONOBO_UI_ERROR_OK = 0,
BONOBO_UI_ERROR_BAD_PARAM,
BONOBO_UI_ERROR_INVALID_PATH,
BONOBO_UI_ERROR_INVALID_XML
} BonoboUIError;
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;
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. |
BonoboUIEngine* bonobo_ui_engine_new (GObject *view);
Create a new BonoboUIEngine structure
| view : | |
| Returns : | the new UI Engine. |
GObject * bonobo_ui_engine_get_view (BonoboUIEngine *engine);
This returns the associated view, often a BonoboWindow
| engine : | the engine |
| Returns : | the view widget. |
void bonobo_ui_engine_add_sync (BonoboUIEngine *engine, BonoboUISync *sync);
Add a BonoboUISync synchronizer to the engine
| engine : | the enginer |
| sync : | the synchronizer |
void bonobo_ui_engine_remove_sync (BonoboUIEngine *engine, BonoboUISync *sync);
Remove a specified BonoboUISync synchronizer from the engine
| engine : | the engine |
| sync : | the sync |
GSList * bonobo_ui_engine_get_syncs (BonoboUIEngine *engine);
Retrieve a list of available synchronizers.
| engine : | the engine |
| Returns : | a GSList of BonoboUISync s |
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. |
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 |
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. |
BonoboUINode* bonobo_ui_engine_widget_get_node (GtkWidget *widget);
| widget : | the widget |
| Returns : | the BonoboUINode associated with this widget |
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 |
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 |
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 |
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 |
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. |
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 |
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 |
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 assoicated, 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 |
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 |
gboolean bonobo_ui_engine_node_is_dirty (BonoboUIEngine *engine, BonoboUINode *node);
| engine : | the engine |
| node : | the node |
| Returns : | whether the node is marked dirty |
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 |
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 |
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 |
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. |
void bonobo_ui_engine_stamp_custom (BonoboUIEngine *engine, BonoboUINode *node);
Marks a node as containing a custom widget.
| engine : | the engine |
| node : | the node |
void bonobo_ui_engine_widget_set (BonoboUIEngine *engine, const char *path,GtkWidget *widget);
| engine : | |
| path : | |
| widget : |
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 |
void bonobo_ui_engine_add_hint (BonoboUIEngine *engine, const char *str);
This fires the 'add_hint' signal.
| engine : | the engine |
| str : | the hint string |
void bonobo_ui_engine_remove_hint (BonoboUIEngine *engine);
This fires the 'remove_hint' signal
| engine : | the engine |
void bonobo_ui_engine_emit_verb_on (BonoboUIEngine *engine, BonoboUINode *node);
This fires the 'emit_verb' signal
| engine : | the engine |
| node : | the node |
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 |
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 |
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 |
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. |
void bonobo_ui_engine_widget_attach_node
(GtkWidget *widget,
BonoboUINode *node);Associate node with widget
| widget : | the widget |
| node : | the node |
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 |
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 |
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 |
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 |
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 |
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 |
void bonobo_ui_engine_exec_verb (BonoboUIEngine *engine, constCORBA_char *cname,CORBA_Environment *ev);
| engine : | |
| cname : | |
| ev : |
void bonobo_ui_engine_ui_event (BonoboUIEngine *engine, constCORBA_char *id, constBonobo_UIComponent_EventType type, constCORBA_char *state,CORBA_Environment *ev);
| engine : | |
| id : | |
| type : | |
| state : | |
| ev : |
void user_function (BonoboUIEngine *bonobouiengine,gchar *arg1,gpointer user_data);
| bonobouiengine : | the object which received the signal. |
| arg1 : | |
| user_data : | user data set when the signal handler was connected. |
void user_function (BonoboUIEngine *bonobouiengine,gpointer user_data);
| bonobouiengine : | the object which received the signal. |
| user_data : | user data set when the signal handler was connected. |
void user_function (BonoboUIEngine *bonobouiengine,gpointer arg1,gchar *arg2,gpointer user_data);
| bonobouiengine : | the object which received the signal. |
| arg1 : | |
| arg2 : | |
| user_data : | user data set when the signal handler was connected. |
void user_function (BonoboUIEngine *bonobouiengine,gpointer arg1,gpointer user_data);
| bonobouiengine : | the object which received the signal. |
| arg1 : | |
| user_data : | user data set when the signal handler was connected. |
void user_function (BonoboUIEngine *bonobouiengine,gpointer user_data);
| bonobouiengine : | the object which received the signal. |
| user_data : | user data set when the signal handler was connected. |
| << bonobo-ui-node | bonobo-ui-engine-config >> |