BonoboUISync

BonoboUISync — A Synchronizer object to keep a widget tree in sync with an XML tree.

Synopsis

                    BonoboUISync;
void                (*BonoboUISyncStateFn)              (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         GtkWidget *widget,
                                                         GtkWidget *parent);
GtkWidget *         (*BonoboUISyncBuildFn)              (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         int *pos,
                                                         GtkWidget *parent);
                    BonoboUISyncPrivate;
                    BonoboUISyncClass;
BonoboUISync *      bonobo_ui_sync_construct            (BonoboUISync *sync,
                                                         BonoboUIEngine *engine,
                                                         gboolean is_recursive,
                                                         gboolean has_widgets);
gboolean            bonobo_ui_sync_is_recursive         (BonoboUISync *sync);
gboolean            bonobo_ui_sync_has_widgets          (BonoboUISync *sync);
void                bonobo_ui_sync_remove_root          (BonoboUISync *sync,
                                                         BonoboUINode *root);
void                bonobo_ui_sync_update_root          (BonoboUISync *sync,
                                                         BonoboUINode *root);
void                bonobo_ui_sync_state                (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         GtkWidget *widget,
                                                         GtkWidget *parent);
void                bonobo_ui_sync_state_placeholder    (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         GtkWidget *widget,
                                                         GtkWidget *parent);
GtkWidget *         bonobo_ui_sync_build                (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         int *pos,
                                                         GtkWidget *parent);
GtkWidget *         bonobo_ui_sync_build_placeholder    (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         int *pos,
                                                         GtkWidget *parent);
gboolean            bonobo_ui_sync_ignore_widget        (BonoboUISync *sync,
                                                         GtkWidget *widget);
GList *             bonobo_ui_sync_get_widgets          (BonoboUISync *sync,
                                                         BonoboUINode *node);
void                bonobo_ui_sync_stamp_root           (BonoboUISync *sync);
gboolean            bonobo_ui_sync_can_handle           (BonoboUISync *sync,
                                                         BonoboUINode *node);
GtkWidget *         bonobo_ui_sync_get_attached         (BonoboUISync *sync,
                                                         GtkWidget *widget,
                                                         BonoboUINode *node);
void                bonobo_ui_sync_state_update         (BonoboUISync *sync,
                                                         GtkWidget *widget,
                                                         const char *new_state);
gboolean            bonobo_ui_sync_do_show_hide         (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         GtkWidget *widget);
GtkWidget *         bonobo_ui_sync_wrap_widget          (BonoboUISync *sync,
                                                         GtkWidget *custom_widget);
GType               bonobo_ui_sync_keys_get_type        (void);
GType               bonobo_ui_sync_menu_get_type        (void);
GType               bonobo_ui_sync_status_get_type      (void);
GType               bonobo_ui_sync_toolbar_get_type     (void);

Object Hierarchy

  GObject
   +----BonoboUISync

Description

The BonoboUISynchronizer is used internaly by the BonoboUIEngine. Writing one is a very advanced topic, and should only be attempted by carefuly study of the code. No normal user should need to write his own synchronizer.

Details

BonoboUISync

typedef struct _BonoboUISync BonoboUISync;


BonoboUISyncStateFn ()

void                (*BonoboUISyncStateFn)              (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         GtkWidget *widget,
                                                         GtkWidget *parent);

sync :

node :

cmd_node :

widget :

parent :


BonoboUISyncBuildFn ()

GtkWidget *         (*BonoboUISyncBuildFn)              (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         int *pos,
                                                         GtkWidget *parent);

sync :

node :

cmd_node :

pos :

parent :

Returns :


BonoboUISyncPrivate

typedef struct _BonoboUISyncPrivate BonoboUISyncPrivate;


BonoboUISyncClass

typedef struct {
	GObjectClass parent_class;

	BonoboUISyncStateFn sync_state;
	BonoboUISyncStateFn sync_state_placeholder;
	BonoboUISyncBuildFn build;
	BonoboUISyncBuildFn build_placeholder;

	void          (*update_root)     (BonoboUISync     *sync,
					  BonoboUINode     *root);

	void          (*remove_root)     (BonoboUISync     *sync,
					  BonoboUINode     *root);

	GList        *(*get_widgets)     (BonoboUISync     *sync,
					  BonoboUINode     *node);

	void          (*state_update)    (BonoboUISync     *sync,
					  GtkWidget        *widget,
					  const char       *new_state);
	
	gboolean      (*ignore_widget)   (BonoboUISync     *sync,
					  GtkWidget        *widget);
	
	gboolean      (*can_handle)      (BonoboUISync     *sync,
					  BonoboUINode     *node);
	
        void          (*stamp_root)      (BonoboUISync     *sync);

	GtkWidget    *(*get_attached)    (BonoboUISync     *sync,
					  GtkWidget        *widget,
					  BonoboUINode     *node);

	GtkWidget    *(*wrap_widget)     (BonoboUISync     *sync,
					  GtkWidget        *custom_widget);
} BonoboUISyncClass;


bonobo_ui_sync_construct ()

BonoboUISync *      bonobo_ui_sync_construct            (BonoboUISync *sync,
                                                         BonoboUIEngine *engine,
                                                         gboolean is_recursive,
                                                         gboolean has_widgets);

Used to construct a new synchronizer object

sync :

the synchronizer

engine :

the associated engine

is_recursive :

whether it deals with its children recursively

has_widgets :

whether it has associated widgets.

Returns :

the new object.

bonobo_ui_sync_is_recursive ()

gboolean            bonobo_ui_sync_is_recursive         (BonoboUISync *sync);

sync :

the synchronizer

Returns :

whether this deals with its children recursively

bonobo_ui_sync_has_widgets ()

gboolean            bonobo_ui_sync_has_widgets          (BonoboUISync *sync);

sync :

the synchronizer

Returns :

whether this deals with widgets

bonobo_ui_sync_remove_root ()

void                bonobo_ui_sync_remove_root          (BonoboUISync *sync,
                                                         BonoboUINode *root);

This is called when a 'root' or toplevel node is removed that this synchronizer deals with. eg. in the toolbar case, this might trigger hiding an associated dock item.

sync :

the synchronizer

root :

the toplevel node to be removed.

bonobo_ui_sync_update_root ()

void                bonobo_ui_sync_update_root          (BonoboUISync *sync,
                                                         BonoboUINode *root);

This flags the fact that a toplevel node has changed and is used primarily by non-recursive handlers, such as the keybinding sync method.

sync :

the synchronizer

root :

the toplevel node

bonobo_ui_sync_state ()

void                bonobo_ui_sync_state                (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         GtkWidget *widget,
                                                         GtkWidget *parent);

This method is used to synchronize the state of a node with that of a widget, by ensuring the pertainant attributes are reflected in the widget view.

sync :

the synchronizer

node :

the node

cmd_node :

the associated command node

widget :

the widget

parent :

the parent of node

bonobo_ui_sync_state_placeholder ()

void                bonobo_ui_sync_state_placeholder    (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         GtkWidget *widget,
                                                         GtkWidget *parent);

This synchronizes the state of a placeholder, there is a default implementation for this method.

sync :

the synchronizer

node :

the node

cmd_node :

the associated command node

widget :

the widget

parent :

the parent of node

bonobo_ui_sync_build ()

GtkWidget *         bonobo_ui_sync_build                (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         int *pos,
                                                         GtkWidget *parent);

This function causes a child widget to be build that matches node's attributes. This should then be inserted by into parent's associated widget at position pos in the container.

sync :

the synchronizer

node :

the node

cmd_node :

the associated command node

pos :

the position in the parent container to insert at

parent :

the parent of node

Returns :

the freshly built widget.

bonobo_ui_sync_build_placeholder ()

GtkWidget *         bonobo_ui_sync_build_placeholder    (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         int *pos,
                                                         GtkWidget *parent);

As for bonobo_ui_sync_build but for placeholders

sync :

the synchronizer

node :

the node

cmd_node :

the associated command node

pos :

position in the parent to insert the built widget

parent :

the parent of node

Returns :

the freshly built widget.

bonobo_ui_sync_ignore_widget ()

gboolean            bonobo_ui_sync_ignore_widget        (BonoboUISync *sync,
                                                         GtkWidget *widget);

sync :

the synchronizer

widget :

the widget

Returns :

TRUE if this widget should be ignored in a container this is the case for eg. menu tearoffs items, and toolbar popout items.

bonobo_ui_sync_get_widgets ()

GList *             bonobo_ui_sync_get_widgets          (BonoboUISync *sync,
                                                         BonoboUINode *node);

This method is used to obtain a sensibly ordered list of child widgets of the container associated with node. Essentialy this does something like gtk_container_children but preserving the visible order of the widgets in the list.

sync :

the synchronizer

node :

the node

Returns :

An ordered list of child widgets of node

bonobo_ui_sync_stamp_root ()

void                bonobo_ui_sync_stamp_root           (BonoboUISync *sync);

This asks the synchronizer to stamp all its associated root widget containers into the XML tree.

sync :

the synchronizer

bonobo_ui_sync_can_handle ()

gboolean            bonobo_ui_sync_can_handle           (BonoboUISync *sync,
                                                         BonoboUINode *node);

This is used to determine which, of multiple synchronizers can be used to deal with a specific node type. Each synchronizer deals with different types of node.

sync :

the synchronizer

node :

the node

Returns :

TRUE if the synchronizer can deal with this node type

bonobo_ui_sync_get_attached ()

GtkWidget *         bonobo_ui_sync_get_attached         (BonoboUISync *sync,
                                                         GtkWidget *widget,
                                                         BonoboUINode *node);

This is used to get an 'attached' widget - some widgets have associated widgets that are coupled in strange ways - eg. GtkMenuItem <-> GtkMenuShell It is neccessary to store the GtkContainer item of these couples in the XML tree, since then we can do things more genericaly and cleanly.

sync :

the synchronizer

widget :

the widget

node :

the node

Returns :

an associated widget or NULL if none exists.

bonobo_ui_sync_state_update ()

void                bonobo_ui_sync_state_update         (BonoboUISync *sync,
                                                         GtkWidget *widget,
                                                         const char *new_state);

This is used to synchronize state with a stateful widget, eg. when a "state" attribute is set, this is not reflected in the normal 'state-sync' process, but occurs later with a set of state_updates to avoid re-enterancy problems.

sync :

the synchronizer

widget :

the widget

new_state :

the new state

bonobo_ui_sync_do_show_hide ()

gboolean            bonobo_ui_sync_do_show_hide         (BonoboUISync *sync,
                                                         BonoboUINode *node,
                                                         BonoboUINode *cmd_node,
                                                         GtkWidget *widget);

This is a helper function that applies the hidden attribute from either the node or fallback to the cmd_node to the widget.

sync :

the synchronizer

node :

the node

cmd_node :

the associated command node

widget :

the widget

Returns :

TRUE if the widget's hidden / shown state changed, this is needed to work around some nasty dock sizing bugs.

bonobo_ui_sync_wrap_widget ()

GtkWidget *         bonobo_ui_sync_wrap_widget          (BonoboUISync *sync,
                                                         GtkWidget *custom_widget);

sync :

custom_widget :

Returns :


bonobo_ui_sync_keys_get_type ()

GType               bonobo_ui_sync_keys_get_type        (void);

Returns :


bonobo_ui_sync_menu_get_type ()

GType               bonobo_ui_sync_menu_get_type        (void);

Returns :


bonobo_ui_sync_status_get_type ()

GType               bonobo_ui_sync_status_get_type      (void);

Returns :


bonobo_ui_sync_toolbar_get_type ()

GType               bonobo_ui_sync_toolbar_get_type     (void);

Returns :