## SwamiRoot SwamiRoot |

## Synopsis

                        SwamiRoot;
    SwamiRoot *         swami_root_new                      (void);
    #define             swami_root_get_patch_items          (swami)
    SwamiRoot *         swami_get_root                      (gpointer object);
    IpatchList *        swami_root_get_objects              (SwamiRoot *root);
    void                swami_root_add_object               (SwamiRoot *root,
                                                             GObject *object);
    GObject *           swami_root_new_object               (SwamiRoot *root,
                                                             const char *type_name);
    void                swami_root_prepend_object           (SwamiRoot *root,
                                                             GObject *parent,
                                                             GObject *object);
    #define             swami_root_append_object            (root, parent, object)
    void                swami_root_insert_object_before     (SwamiRoot *root,
                                                             GObject *parent,
                                                             GObject *sibling,
                                                             GObject *object);
    gboolean            swami_root_patch_load               (SwamiRoot *root,
                                                             const char *filename,
                                                             IpatchItem **item,
                                                             GError **err);
    gboolean            swami_root_patch_save               (IpatchItem *item,
                                                             const char *filename,
                                                             GError **err);

## Object Hierarchy

      GObject
       +----SwamiLock
             +----SwamiRoot

## Properties

      "patch-path"               gchar*                : Read / Write
      "patch-root"               SwamiContainer*       : Read
      "patch-search-path"        gchar*                : Read / Write
      "sample-format"            gchar*                : Read / Write
      "sample-max-size"          gint                  : Read / Write
      "sample-path"              gchar*                : Read / Write
      "swap-max-waste"           gint                  : Read / Write

## Signals

      "object-add"                                     : Run First
      "swami-prop-notify"                              : Run First / No Recursion / Has Details / No Hooks

## Description

## Details

### SwamiRoot

    typedef struct _SwamiRoot SwamiRoot;

### swami_root_new ()

    SwamiRoot *         swami_root_new                      (void);

Create a new Swami root object which is a toplevel container for patches, objects, configuration data and state history.

Returns : | New Swami root object

### swami_root_get_patch_items()

    #define             swami_root_get_patch_items(swami)

### swami_get_root ()

    SwamiRoot *         swami_get_root                      (gpointer object);

Gets the SwamiRoot object associated with a `object`.

`object` : | An object registered to a SwamiRoot, an IpatchItem contained in a SwamiRoot or the root itself
Returns : | The SwamiRoot object or `NULL` if `object` not registered to a root. Returned root object is not referenced, we assume it won't be destroyed.

### swami_root_get_objects ()

    IpatchList *        swami_root_get_objects              (SwamiRoot *root);

Get an iterator filled with toplevel objects that are the first children of a SwamiRoot object property tree.

`root` : | Swami root object
Returns : | New object list with a reference count of 1 which the caller owns, remember to unref it when finished.

### swami_root_add_object ()

    void                swami_root_add_object               (SwamiRoot *root,
                                                             GObject *object);

Add an object to a Swami root property tree. A reference is held on the object for the `root` object.

`root` : | Swami root object
`object` : | Object to add

### swami_root_new_object ()

    GObject *           swami_root_new_object               (SwamiRoot *root,
                                                             const char *type_name);

Like `swami_root_add_object()` but creates a new object rather than using an existing one.

`root` : | Swami root object
`type_name` : | Name of GObject derived GType of object to create and add to a `root` object.
Returns : | The new GObject created or NULL on error. The caller owns a reference on the new object and should unref it when done. The `root` also owns a reference, until `swami_root_remove_object()` is called on it.

### swami_root_prepend_object ()

    void                swami_root_prepend_object           (SwamiRoot *root,
                                                             GObject *parent,
                                                             GObject *object);

Prepends an object to an object property tree in a `root` object as a child of `parent`. Like `swami_root_add_object()` but allows parent to specified (rather than using the `root` as the parent).

`root` : | Swami root object
`parent` : | New parent of `object`
`object` : | Object to prepend

### swami_root_append_object()

    #define             swami_root_append_object(root, parent, object)

### swami_root_insert_object_before ()

    void                swami_root_insert_object_before     (SwamiRoot *root,
                                                             GObject *parent,
                                                             GObject *sibling,
                                                             GObject *object);

Inserts an object into an object property tree in a `root` object as a child of `parent` and before `sibling`.

`root` : | Swami root object
`parent` : | New parent of `object`
`sibling` : | Sibling to insert object before or `NULL` to append
`object` : | Object to insert

### swami_root_patch_load ()

    gboolean            swami_root_patch_load               (SwamiRoot *root,
                                                             const char *filename,
                                                             IpatchItem **item,
                                                             GError **err);

Load an instrument patch file and append to Swami object tree. The caller owns a reference to the returned patch object and should unref it when done with the object.

`root` : | Swami root object to load into
`filename` : | Name and path of file to load
`item` : | Location to store pointer to object that has been loaded into Swami root object (or `NULL`). Remember to unref the object when done with it (not necessary of course if `NULL` was passed).
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise

### swami_root_patch_save ()

    gboolean            swami_root_patch_save               (IpatchItem *item,
                                                             const char *filename,
                                                             GError **err);

Save a patch item to a file.

`item` : | Patch item to save.
`filename` : | New file name to save to or NULL to use current one.
`err` : | Location to store error info or NULL
Returns : | `TRUE` on success, `FALSE` otherwise

## Property Details

### The `"patch-path"` property

      "patch-path"               gchar*                : Read / Write

Default patch path.

Default value: NULL

### The `"patch-root"` property

      "patch-root"               SwamiContainer*       : Read

Root container of instrument patch tree.

### The `"patch-search-path"` property

      "patch-search-path"        gchar*                : Read / Write

Patch search path.

Default value: NULL

### The `"sample-format"` property

      "sample-format"            gchar*                : Read / Write

Default sample format.

Default value: NULL

### The `"sample-max-size"` property

      "sample-max-size"          gint                  : Read / Write

Max sample size in megabytes.

Allowed values: >= 1

Default value: 32

### The `"sample-path"` property

      "sample-path"              gchar*                : Read / Write

Default sample path.

Default value: NULL

### The `"swap-max-waste"` property

      "swap-max-waste"           gint                  : Read / Write

Max waste of sample swap in megabytes.

Allowed values: >= 1

Default value: 64

## Signal Details

### The `"object-add"` signal

    void                user_function                      (SwamiRoot *swamiroot,
                                                            GObject   *arg1,
                                                            gpointer   user_data)      : Run First

### The `"swami-prop-notify"` signal

    void                user_function                      (SwamiRoot  *swamiroot,
                                                            GParamSpec *arg1,
                                                            gpointer    user_data)      : Run First / No Recursion / Has Details / No Hooks