## SwamiPropTree SwamiPropTree |

## Synopsis

                        SwamiPropTreeNode;
                        SwamiPropTreeValue;
                        SwamiPropTree;
    SwamiPropTree *     swami_prop_tree_new                 (void);
    void                swami_prop_tree_set_root            (SwamiPropTree *proptree,
                                                             GObject *root);
    void                swami_prop_tree_prepend             (SwamiPropTree *proptree,
                                                             GObject *parent,
                                                             GObject *obj);
    #define             swami_prop_tree_append              (proptree, parent, obj)
    void                swami_prop_tree_insert_before       (SwamiPropTree *proptree,
                                                             GObject *parent,
                                                             GObject *sibling,
                                                             GObject *obj);
    void                swami_prop_tree_remove              (SwamiPropTree *proptree,
                                                             GObject *obj);
    void                swami_prop_tree_remove_recursive    (SwamiPropTree *proptree,
                                                             GObject *obj);
    void                swami_prop_tree_replace             (SwamiPropTree *proptree,
                                                             GObject *old,
                                                             GObject *new);
    IpatchList *        swami_prop_tree_get_children        (SwamiPropTree *proptree,
                                                             GObject *obj);
    GNode *             swami_prop_tree_object_get_node     (SwamiPropTree *proptree,
                                                             GObject *obj);
    void                swami_prop_tree_add_value           (SwamiPropTree *proptree,
                                                             GObject *obj,
                                                             GType prop_type,
                                                             const char *prop_name,
                                                             SwamiControl *control);
    void                swami_prop_tree_remove_value        (SwamiPropTree *proptree,
                                                             GObject *obj,
                                                             GType prop_type,
                                                             const char *prop_name);

## Object Hierarchy

      GObject
       +----SwamiLock
             +----SwamiPropTree

## Description

## Details

### SwamiPropTreeNode

    typedef struct {
      GObject *object;	  /* pointer to the object the node manages */
      GSList *values;	/* list of SwamiPropTreeValue for this node */
      GSList *cache; /* cached values for object (struct in SwamiPropTree.c) */
      guint16 flags;
      guint16 reserved;
    } SwamiPropTreeNode;

### SwamiPropTreeValue

    typedef struct {
      GType prop_type; /* instance type owning property to match (0 = wildcard) */
      char *prop_name;		/* name of property to match */
      SwamiControl *control; /* source value control (defines the value) */
    } SwamiPropTreeValue;

### SwamiPropTree

    typedef struct _SwamiPropTree SwamiPropTree;

### swami_prop_tree_new ()

    SwamiPropTree *     swami_prop_tree_new                 (void);

Create a new property tree object.

Returns : | New property tree object with a refcount of 1.

### swami_prop_tree_set_root ()

    void                swami_prop_tree_set_root            (SwamiPropTree *proptree,
                                                             GObject *root);

Set the root object of a property tree. Should only be set once.

`proptree` : | Property tree object
`root` : | Object to make the root object of the tree

### swami_prop_tree_prepend ()

    void                swami_prop_tree_prepend             (SwamiPropTree *proptree,
                                                             GObject *parent,
                                                             GObject *obj);

Prepends an object to a property tree.

`proptree` : | Property tree object
`parent` : | Object in `proptree` to parent to
`obj` : | Object to prepend to `proptree`

### swami_prop_tree_append()

    #define             swami_prop_tree_append(proptree, parent, obj)

### swami_prop_tree_insert_before ()

    void                swami_prop_tree_insert_before       (SwamiPropTree *proptree,
                                                             GObject *parent,
                                                             GObject *sibling,
                                                             GObject *obj);

Inserts an object to a property tree before `sibling` and parented to `parent`.

`proptree` : | Property tree object
`parent` : | Object in `proptree` to parent to
`sibling` : | Object in `proptree` to insert before or `NULL` to append
`obj` : | Object to prepend to `proptree`

### swami_prop_tree_remove ()

    void                swami_prop_tree_remove              (SwamiPropTree *proptree,
                                                             GObject *obj);

Removes an `obj`, and all values bound to it, from a property tree. All child nodes are moved up to the next parent node.

`proptree` : | Property tree object
`obj` : | Object in `proptree` to remove

### swami_prop_tree_remove_recursive ()

    void                swami_prop_tree_remove_recursive    (SwamiPropTree *proptree,
                                                             GObject *obj);

Recursively removes an `object`, and all values bound to it, from a property tree.

`proptree` : | Property tree object
`obj` : | Object in `proptree` to recursively remove

### swami_prop_tree_replace ()

    void                swami_prop_tree_replace             (SwamiPropTree *proptree,
                                                             GObject *old,
                                                             GObject *new);

Replaces an `old` object with a `new` object in a property tree.

`proptree` : | Property tree object
`old` : | Old object in `proptree` to replace
`new` : | New object to replace `old` object with

### swami_prop_tree_get_children ()

    IpatchList *        swami_prop_tree_get_children        (SwamiPropTree *proptree,
                                                             GObject *obj);

Gets the list of GObject children of `obj` in a property tree.

`proptree` : | Property tree object
`obj` : | Object in `proptree` to get children of
Returns : | A new object list populated with the children of `obj` in `proptree`. The new list has a reference count of 1 which the caller owns, remember to unref it when finished.

### swami_prop_tree_object_get_node ()

    GNode *             swami_prop_tree_object_get_node     (SwamiPropTree *proptree,
                                                             GObject *obj);

### swami_prop_tree_add_value ()

    void                swami_prop_tree_add_value           (SwamiPropTree *proptree,
                                                             GObject *obj,
                                                             GType prop_type,
                                                             const char *prop_name,
                                                             SwamiControl *control);

Adds a value to an object in a property tree. If a value already exists with the same `prop_type` and `prop_name` its `control` value is replaced.

`proptree` : | Property tree object
`obj` : | Object in `proptree`
`prop_type` : | GObject derived type the value should match (0 = wildcard)
`prop_name` : | Property name to match
`control` : | Active value control

### swami_prop_tree_remove_value ()

    void                swami_prop_tree_remove_value        (SwamiPropTree *proptree,
                                                             GObject *obj,
                                                             GType prop_type,
                                                             const char *prop_name);

Removes a value from an object in a property tree. The `prop_type` and `prop_name` parameters are used to find the value to remove.

`proptree` : | Property tree object
`obj` : | Object in `proptree`
`prop_type` : | GObject derived type field of existing value
`prop_name` : | Property name field of existing value