MateComponentUISync

## MateComponentUISync MateComponentUISync — A Synchronizer object to keep a widget tree in sync with an XML tree. |

## Synopsis

    struct              MateComponentUISync;
    void                (*MateComponentUISyncStateFn)              (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             GtkWidget *widget,
                                                             GtkWidget *parent);
    GtkWidget *         (*MateComponentUISyncBuildFn)              (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             int *pos,
                                                             GtkWidget *parent);
                        MateComponentUISyncPrivate;
                        MateComponentUISyncClass;
    MateComponentUISync *      matecomponent_ui_sync_construct            (MateComponentUISync *sync,
                                                             MateComponentUIEngine *engine,
                                                             gboolean is_recursive,
                                                             gboolean has_widgets);
    gboolean            matecomponent_ui_sync_is_recursive         (MateComponentUISync *sync);
    gboolean            matecomponent_ui_sync_has_widgets          (MateComponentUISync *sync);
    void                matecomponent_ui_sync_remove_root          (MateComponentUISync *sync,
                                                             MateComponentUINode *root);
    void                matecomponent_ui_sync_update_root          (MateComponentUISync *sync,
                                                             MateComponentUINode *root);
    void                matecomponent_ui_sync_state                (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             GtkWidget *widget,
                                                             GtkWidget *parent);
    void                matecomponent_ui_sync_state_placeholder    (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             GtkWidget *widget,
                                                             GtkWidget *parent);
    GtkWidget *         matecomponent_ui_sync_build                (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             int *pos,
                                                             GtkWidget *parent);
    GtkWidget *         matecomponent_ui_sync_build_placeholder    (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             int *pos,
                                                             GtkWidget *parent);
    gboolean            matecomponent_ui_sync_ignore_widget        (MateComponentUISync *sync,
                                                             GtkWidget *widget);
    GList *             matecomponent_ui_sync_get_widgets          (MateComponentUISync *sync,
                                                             MateComponentUINode *node);
    void                matecomponent_ui_sync_stamp_root           (MateComponentUISync *sync);
    gboolean            matecomponent_ui_sync_can_handle           (MateComponentUISync *sync,
                                                             MateComponentUINode *node);
    GtkWidget *         matecomponent_ui_sync_get_attached         (MateComponentUISync *sync,
                                                             GtkWidget *widget,
                                                             MateComponentUINode *node);
    void                matecomponent_ui_sync_state_update         (MateComponentUISync *sync,
                                                             GtkWidget *widget,
                                                             const char *new_state);
    gboolean            matecomponent_ui_sync_do_show_hide         (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             GtkWidget *widget);
    GtkWidget *         matecomponent_ui_sync_wrap_widget          (MateComponentUISync *sync,
                                                             GtkWidget *custom_widget);
    GType               matecomponent_ui_sync_keys_get_type        (void);
    GType               matecomponent_ui_sync_menu_get_type        (void);
    GType               matecomponent_ui_sync_status_get_type      (void);
    GType               matecomponent_ui_sync_toolbar_get_type     (void);

## Object Hierarchy

      GObject
       +----MateComponentUISync

## Description

The MateComponentUISynchronizer is used internaly by the MateComponentUIEngine. 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

### struct MateComponentUISync

    struct MateComponentUISync;

### MateComponentUISyncStateFn ()

    void                (*MateComponentUISyncStateFn)              (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             GtkWidget *widget,
                                                             GtkWidget *parent);

`sync` : |
`node` : |
`cmd_node` : |
`widget` : |
`parent` : |

### MateComponentUISyncBuildFn ()

    GtkWidget *         (*MateComponentUISyncBuildFn)              (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             int *pos,
                                                             GtkWidget *parent);

`sync` : |
`node` : |
`cmd_node` : |
`pos` : |
`parent` : |
Returns : |

### MateComponentUISyncPrivate

    typedef struct _MateComponentUISyncPrivate MateComponentUISyncPrivate;

### MateComponentUISyncClass

    typedef struct {
    	GObjectClass parent_class;

    	MateComponentUISyncStateFn sync_state;
    	MateComponentUISyncStateFn sync_state_placeholder;
    	MateComponentUISyncBuildFn build;
    	MateComponentUISyncBuildFn build_placeholder;

    	void          (*update_root)     (MateComponentUISync     *sync,
    					  MateComponentUINode     *root);

    	void          (*remove_root)     (MateComponentUISync     *sync,
    					  MateComponentUINode     *root);

    	GList        *(*get_widgets)     (MateComponentUISync     *sync,
    					  MateComponentUINode     *node);

    	void          (*state_update)    (MateComponentUISync     *sync,
    					  GtkWidget        *widget,
    					  const char       *new_state);

    	gboolean      (*ignore_widget)   (MateComponentUISync     *sync,
    					  GtkWidget        *widget);

    	gboolean      (*can_handle)      (MateComponentUISync     *sync,
    					  MateComponentUINode     *node);

            void          (*stamp_root)      (MateComponentUISync     *sync);

    	GtkWidget    *(*get_attached)    (MateComponentUISync     *sync,
    					  GtkWidget        *widget,
    					  MateComponentUINode     *node);

    	GtkWidget    *(*wrap_widget)     (MateComponentUISync     *sync,
    					  GtkWidget        *custom_widget);
    } MateComponentUISyncClass;

### matecomponent_ui_sync_construct ()

    MateComponentUISync *      matecomponent_ui_sync_construct            (MateComponentUISync *sync,
                                                             MateComponentUIEngine *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.

### matecomponent_ui_sync_is_recursive ()

    gboolean            matecomponent_ui_sync_is_recursive         (MateComponentUISync *sync);

`sync` : | the synchronizer
Returns : | whether this deals with its children recursively

### matecomponent_ui_sync_has_widgets ()

    gboolean            matecomponent_ui_sync_has_widgets          (MateComponentUISync *sync);

`sync` : | the synchronizer
Returns : | whether this deals with widgets

### matecomponent_ui_sync_remove_root ()

    void                matecomponent_ui_sync_remove_root          (MateComponentUISync *sync,
                                                             MateComponentUINode *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.

### matecomponent_ui_sync_update_root ()

    void                matecomponent_ui_sync_update_root          (MateComponentUISync *sync,
                                                             MateComponentUINode *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

### matecomponent_ui_sync_state ()

    void                matecomponent_ui_sync_state                (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *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`

### matecomponent_ui_sync_state_placeholder ()

    void                matecomponent_ui_sync_state_placeholder    (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *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`

### matecomponent_ui_sync_build ()

    GtkWidget *         matecomponent_ui_sync_build                (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *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.

### matecomponent_ui_sync_build_placeholder ()

    GtkWidget *         matecomponent_ui_sync_build_placeholder    (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *cmd_node,
                                                             int *pos,
                                                             GtkWidget *parent);

As for matecomponent_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.

### matecomponent_ui_sync_ignore_widget ()

    gboolean            matecomponent_ui_sync_ignore_widget        (MateComponentUISync *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.

### matecomponent_ui_sync_get_widgets ()

    GList *             matecomponent_ui_sync_get_widgets          (MateComponentUISync *sync,
                                                             MateComponentUINode *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`

### matecomponent_ui_sync_stamp_root ()

    void                matecomponent_ui_sync_stamp_root           (MateComponentUISync *sync);

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

`sync` : | the synchronizer

### matecomponent_ui_sync_can_handle ()

    gboolean            matecomponent_ui_sync_can_handle           (MateComponentUISync *sync,
                                                             MateComponentUINode *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

### matecomponent_ui_sync_get_attached ()

    GtkWidget *         matecomponent_ui_sync_get_attached         (MateComponentUISync *sync,
                                                             GtkWidget *widget,
                                                             MateComponentUINode *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.

### matecomponent_ui_sync_state_update ()

    void                matecomponent_ui_sync_state_update         (MateComponentUISync *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

### matecomponent_ui_sync_do_show_hide ()

    gboolean            matecomponent_ui_sync_do_show_hide         (MateComponentUISync *sync,
                                                             MateComponentUINode *node,
                                                             MateComponentUINode *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.

### matecomponent_ui_sync_wrap_widget ()

    GtkWidget *         matecomponent_ui_sync_wrap_widget          (MateComponentUISync *sync,
                                                             GtkWidget *custom_widget);

`sync` : |
`custom_widget` : |
Returns : |

### matecomponent_ui_sync_keys_get_type ()

    GType               matecomponent_ui_sync_keys_get_type        (void);

Returns : |

### matecomponent_ui_sync_menu_get_type ()

    GType               matecomponent_ui_sync_menu_get_type        (void);

Returns : |

### matecomponent_ui_sync_status_get_type ()

    GType               matecomponent_ui_sync_status_get_type      (void);

Returns : |

### matecomponent_ui_sync_toolbar_get_type ()

    GType               matecomponent_ui_sync_toolbar_get_type     (void);

Returns : |