Bonobo API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# BonoboUISync

## Name

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

## Synopsis

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

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

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

### 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 assoicated 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.

<<< Previous Page | Home | Up | Next Page >>>
BonoboUIEngine | Writing Monikers