![]() | ![]() | ![]() | 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.
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.
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 >> |