bonobo-ui-node

## bonobo-ui-node bonobo-ui-node — Simplified XML Node manipulation API |

## Synopsis

                        BonoboUINode;
    BonoboUINode *      bonobo_ui_node_new                  (const char *name);
    BonoboUINode *      bonobo_ui_node_new_child            (BonoboUINode *parent,
                                                             const char *name);
    BonoboUINode *      bonobo_ui_node_copy                 (BonoboUINode *node,
                                                             gboolean recursive);
    void                bonobo_ui_node_free                 (BonoboUINode *node);
    void                bonobo_ui_node_set_data             (BonoboUINode *node,
                                                             gpointer data);
    gpointer            bonobo_ui_node_get_data             (BonoboUINode *node);
    void                bonobo_ui_node_set_attr             (BonoboUINode *node,
                                                             const char *name,
                                                             const char *value);
    char *              bonobo_ui_node_get_attr             (BonoboUINode *node,
                                                             const char *name);
    gboolean            bonobo_ui_node_has_attr             (BonoboUINode *node,
                                                             const char *name);
    void                bonobo_ui_node_remove_attr          (BonoboUINode *node,
                                                             const char *name);
    void                bonobo_ui_node_add_child            (BonoboUINode *parent,
                                                             BonoboUINode *child);
    void                bonobo_ui_node_insert_before        (BonoboUINode *after,
                                                             BonoboUINode *new_before);
    void                bonobo_ui_node_unlink               (BonoboUINode *node);
    void                bonobo_ui_node_replace              (BonoboUINode *old_node,
                                                             BonoboUINode *new_node);
    void                bonobo_ui_node_set_content          (BonoboUINode *node,
                                                             const char *content);
    char *              bonobo_ui_node_get_content          (BonoboUINode *node);
    BonoboUINode *      bonobo_ui_node_next                 (BonoboUINode *node);
    BonoboUINode *      bonobo_ui_node_prev                 (BonoboUINode *node);
    BonoboUINode *      bonobo_ui_node_children             (BonoboUINode *node);
    BonoboUINode *      bonobo_ui_node_parent               (BonoboUINode *node);
    const char *        bonobo_ui_node_get_name             (BonoboUINode *node);
    gboolean            bonobo_ui_node_has_name             (BonoboUINode *node,
                                                             const char *name);
    gboolean            bonobo_ui_node_transparent          (BonoboUINode *node);
    void                bonobo_ui_node_copy_attrs           (const BonoboUINode *src,
                                                             BonoboUINode *dest);
    void                bonobo_ui_node_free_string          (char *str);
    void                bonobo_ui_node_strip                (BonoboUINode **node);
    char *              bonobo_ui_node_to_string            (BonoboUINode *node,
                                                             gboolean recurse);
    BonoboUINode*       bonobo_ui_node_from_string          (const char *str);
    BonoboUINode*       bonobo_ui_node_from_file            (const char *filename);

## Description

The BonoboUINode API is designed to make XML node manipulation simple, and to hide the underlying implementation of the XML tree. This is to allow the use of some more efficient internal representation than libxml's at some later date.

## Details

### BonoboUINode

    typedef struct _BonoboUINode BonoboUINode;

The BonoboUINode structure is fully opaque to stop any code depending on libxml inadvertantly.

### bonobo_ui_node_new ()

    BonoboUINode *      bonobo_ui_node_new                  (const char *name);

Creates a new node with name `name`

`name` : | The name for the node
Returns : | a new node pointer

### bonobo_ui_node_new_child ()

    BonoboUINode *      bonobo_ui_node_new_child            (BonoboUINode *parent,
                                                             const char *name);

Create a new node as a child of `parent` with name `name`

`parent` : | the parent
`name` : | the name of the new child
Returns : | pointer to the new child

### bonobo_ui_node_copy ()

    BonoboUINode *      bonobo_ui_node_copy                 (BonoboUINode *node,
                                                             gboolean recursive);

Copy an XML node, if `recursive` do a deep copy, otherwise just dup the node itself.

`node` : | the node
`recursive` : | whether to dup children too.
Returns : | a copy of the noce

### bonobo_ui_node_free ()

    void                bonobo_ui_node_free                 (BonoboUINode *node);

Frees the memory associated with the `node` and unlink it from the tree

`node` : | a node.

### bonobo_ui_node_set_data ()

    void                bonobo_ui_node_set_data             (BonoboUINode *node,
                                                             gpointer data);

Associates some user data with the node pointer

`node` : | the node
`data` : | user data

### bonobo_ui_node_get_data ()

    gpointer            bonobo_ui_node_get_data             (BonoboUINode *node);

Gets user data associated with `node`

`node` : | the node
Returns : | the user data, see bonobo_ui_node_set_data

### bonobo_ui_node_set_attr ()

    void                bonobo_ui_node_set_attr             (BonoboUINode *node,
                                                             const char *name,
                                                             const char *value);

Set the attribute of `name` on `node` to `value` overriding any previous values of that attr.

`node` : | The node
`name` : | the name of the attr
`value` : | the value for the attr

### bonobo_ui_node_get_attr ()

    char *              bonobo_ui_node_get_attr             (BonoboUINode *node,
                                                             const char *name);

Fetch the value of an attr of name `name` from `node` see also: bonobo_ui_node_free_string

`node` : | the node
`name` : | the name of the attr to get
Returns : | the attr text.

### bonobo_ui_node_has_attr ()

    gboolean            bonobo_ui_node_has_attr             (BonoboUINode *node,
                                                             const char *name);

Determines whether the `node` has an attribute of name `name`

`node` : | the node
`name` : | the name of the attr to detect
Returns : | TRUE if the attr exists

### bonobo_ui_node_remove_attr ()

    void                bonobo_ui_node_remove_attr          (BonoboUINode *node,
                                                             const char *name);

remove any attribute with name `name` from `node`

`node` : | the node
`name` : | name of the attribute

### bonobo_ui_node_add_child ()

    void                bonobo_ui_node_add_child            (BonoboUINode *parent,
                                                             BonoboUINode *child);

Add a `child` node to the `parent` node ( after the other children )

`parent` : | the parent
`child` : | the new child

### bonobo_ui_node_insert_before ()

    void                bonobo_ui_node_insert_before        (BonoboUINode *after,
                                                             BonoboUINode *new_before);

Insert a `sibling` before `prev_sibling` in a node list

`after` : | the placeholder for insertion
`new_before` : | the node to insert

### bonobo_ui_node_unlink ()

    void                bonobo_ui_node_unlink               (BonoboUINode *node);

Unlink `node` from its tree, ie. disassociate it with its parent

`node` : | the node

### bonobo_ui_node_replace ()

    void                bonobo_ui_node_replace              (BonoboUINode *old_node,
                                                             BonoboUINode *new_node);

Replace `old_node` with `new_node` in the tree. `old_node` is left unlinked and floating with its children.

`old_node` : | node to be replaced
`new_node` : | node to replace with

### bonobo_ui_node_set_content ()

    void                bonobo_ui_node_set_content          (BonoboUINode *node,
                                                             const char *content);

Set the textual content of `node` to `content`

`node` : | the node
`content` : | the new content

### bonobo_ui_node_get_content ()

    char *              bonobo_ui_node_get_content          (BonoboUINode *node);

see also: bonobo_ui_node_free_string

`node` : | the node
Returns : | the content of `node`

### bonobo_ui_node_next ()

    BonoboUINode *      bonobo_ui_node_next                 (BonoboUINode *node);

`node` : | the node
Returns : | the node after `node` in the list

### bonobo_ui_node_prev ()

    BonoboUINode *      bonobo_ui_node_prev                 (BonoboUINode *node);

`node` : | the node
Returns : | the node after `node` in the list

### bonobo_ui_node_children ()

    BonoboUINode *      bonobo_ui_node_children             (BonoboUINode *node);

`node` : | the node
Returns : | the first child of `node`

### bonobo_ui_node_parent ()

    BonoboUINode *      bonobo_ui_node_parent               (BonoboUINode *node);

`node` : | the node
Returns : | the parent node of `node`

### bonobo_ui_node_get_name ()

    const char *        bonobo_ui_node_get_name             (BonoboUINode *node);

`node` : | the node
Returns : | the name of `node`

### bonobo_ui_node_has_name ()

    gboolean            bonobo_ui_node_has_name             (BonoboUINode *node,
                                                             const char *name);

`node` : | the node
`name` : | a name the node might have
Returns : | TRUE if `node` has name == `name`

### bonobo_ui_node_transparent ()

    gboolean            bonobo_ui_node_transparent          (BonoboUINode *node);

Determines whether `node` is transparent. A node is transparent if it has no content and either no attributes or a single 'name' attribute.

`node` : | the node
Returns : | TRUE if transparent

### bonobo_ui_node_copy_attrs ()

    void                bonobo_ui_node_copy_attrs           (const BonoboUINode *src,
                                                             BonoboUINode *dest);

This function copies all the attributes from `src` to `dest` effectively cloning the `src` node as `dest`

`src` : | the attr source node
`dest` : | where to dump the attrs.

### bonobo_ui_node_free_string ()

    void                bonobo_ui_node_free_string          (char *str);

Frees a string returned by any of the get routines.

`str` : | the string to free.

### bonobo_ui_node_strip ()

    void                bonobo_ui_node_strip                (BonoboUINode **node);

A compat function for legacy reasons.

`node` : | a pointer to the node's pointer

### bonobo_ui_node_to_string ()

    char *              bonobo_ui_node_to_string            (BonoboUINode *node,
                                                             gboolean recurse);

Convert the node to its XML string representation.

`node` : | the node tree
`recurse` : | whether to dump its children as well
Returns : | the string representation or NULL on error Use g_free to free.

### bonobo_ui_node_from_string ()

    BonoboUINode*       bonobo_ui_node_from_string          (const char *str);

Parses a string into an XML tree

`str` : |
Returns : | the xml tree.

### bonobo_ui_node_from_file ()

    BonoboUINode*       bonobo_ui_node_from_file            (const char *filename);

Loads and parses the filename into an XML tree

`filename` : |
Returns : | the xml tree.

## See Also

BonoboUIComponent, bonobo-ui-util