BonoboUISync
3
LIBBONOBOUI Library

# 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 :