## SwamiObject SwamiObject |

## Synopsis

                        SwamiObjectPropBag;
    enum                SwamiRank;
    enum                SwamiObjectFlags;
    extern              GQuark swami_object_propbag_quark;
    void                swami_type_set_rank                 (GType type,
                                                             GType group_type,
                                                             int rank);
    int                 swami_type_get_rank                 (GType type,
                                                             GType group_type);
    GType *             swami_type_get_children             (GType group_type);
    GType               swami_type_get_default              (GType group_type);
    void                swami_object_set_default            (GObject *object,
                                                             GType type);
    GObject *           swami_object_get_by_name            (GObject *object,
                                                             const char *name);
    IpatchList *        swami_object_find_by_type           (GObject *object,
                                                             const char *type_name);
    GObject *           swami_object_get_by_type            (GObject *object,
                                                             const char *type_name);
    void                swami_object_get_valist             (GObject *object,
                                                             const char *first_property_name,
                                                             va_list var_args);
    void                swami_object_get_property           (GObject *object,
                                                             const char *property_name,
                                                             GValue *value);
    void                swami_object_get                    (gpointer object,
                                                             const char *first_prop_name,
                                                             ...);
    void                swami_object_set_valist             (GObject *object,
                                                             const char *first_property_name,
                                                             va_list var_args);
    void                swami_object_set_property           (GObject *object,
                                                             const char *property_name,
                                                             const GValue *value);
    void                swami_object_set                    (gpointer object,
                                                             const char *first_prop_name,
                                                             ...);
    GParamSpec *        swami_find_object_property          (const char *property_name);
    GParamSpec **       swami_list_object_properties        (guint *n_properties);
    guint               swami_object_get_flags              (GObject *object);
    void                swami_object_set_flags              (GObject *object,
                                                             guint flags);
    void                swami_object_clear_flags            (GObject *object,
                                                             guint flags);
    void                swami_object_set_origin             (GObject *obj,
                                                             GObject *origin);
    GObject *           swami_object_get_origin             (GObject *obj);

## Description

## Details

### SwamiObjectPropBag

    typedef struct {
      SwamiRoot *root;		/* parent swami root object */
      char *name;			/* Swami object property name */
      guint8 rank;			/* Swami object rank property */
      guint8 flags;			/* Swami object flags property */
      guint16 reserved;
    } SwamiObjectPropBag;

### enum SwamiRank

    typedef enum
    {
      SWAMI_RANK_INVALID = 0,
      SWAMI_RANK_LOWEST  = 10,
      SWAMI_RANK_LOW     = 25,
      SWAMI_RANK_NORMAL  = 50,	/* NORMAL default value */
      SWAMI_RANK_DEFAULT = 60,	/* value to elect default objects */
      SWAMI_RANK_HIGH    = 75,
      SWAMI_RANK_HIGHEST = 90
    } SwamiRank;

### enum SwamiObjectFlags

    typedef enum /*< flags >*/
    {
      SWAMI_OBJECT_SAVE = 1 << 0,	/* flags if object state should be saved */
      SWAMI_OBJECT_USER = 1 << 1	/* user visable object (in tree view, etc) */
    } SwamiObjectFlags;

### swami_object_propbag_quark

    extern GQuark swami_object_propbag_quark;

### swami_type_set_rank ()

    void                swami_type_set_rank                 (GType type,
                                                             GType group_type,
                                                             int rank);

Sets the ranking of instance GTypes derived from an ancestor `group_type`. This is useful to set a default instance type or to define order to types. An example of use would be to set a higher rank on a plugin wavetable type to cause it to be used when creating a default wavetable instance.

`type` : | Type to set rank value of
`group_type` : | An ancestor type of `type`
`rank` : | Rank value (see SwamiRank enum).

### swami_type_get_rank ()

    int                 swami_type_get_rank                 (GType type,
                                                             GType group_type);

Gets the instance rank of the given `type` derived from a `group_type`. See `swami_type_set_rank()` for more info.

`type` : | Instance type to get rank of
`group_type` : | Ancestor group type
Returns : | Rank value (SWAMI_RANK_NORMAL if not explicitly set).

### swami_type_get_children ()

    GType *             swami_type_get_children             (GType group_type);

Gets an array of types that are derived from `group_type`, sorted by rank. For types that have not had their rank explicitly set SWAMI_RANK_NORMAL will be assumed.

`group_type` : | Group type to get derived types from
Returns : | Newly allocated and zero terminated array of GTypes sorted by rank or `NULL` if no types found. Should be freed when finished.

### swami_type_get_default ()

    GType               swami_type_get_default              (GType group_type);

Gets the default (highest ranked) type derived from a group_type. Like `swami_type_get_children()` but returns first type instead of an array.

`group_type` : | Group type to get default (highest ranked) instance type from
Returns : | GType of default type or 0 if no types derived from `group_type`.

### swami_object_set_default ()

    void                swami_object_set_default            (GObject *object,
                                                             GType type);

Set an `object` as default amongst its peers of the same `type`. Uses the Swami rank system (see "rank" Swami property) to elect a default object. All other object's registered to the same SwamiRoot and of the same `type` (or derived thereof) are set to SWAMI_RANK_NORMAL and the `object`'s rank is set higher.

`object` : | Object to set as default
`type` : | A type that `object` is derived from (or its type)

### swami_object_get_by_name ()

    GObject *           swami_object_get_by_name            (GObject *object,
                                                             const char *name);

Finds an object by its Swami name property, searches recursively through object tree. The `object` can be either a SwamiRoot or, as an added convenience, an object registered to one.

`object` : | Swami root object (SwamiRoot) or an object added to one
`name` : | Name to look for
Returns : | Object that matched `name` or `NULL` if not found. Remember to unref it when finished.

### swami_object_find_by_type ()

    IpatchList *        swami_object_find_by_type           (GObject *object,
                                                             const char *type_name);

Lookup all objects by `type_name` or derived from `type_name` recursively. The `object` can be either a SwamiRoot or, as an added convenience, an object registered to one. The returned iterator list is sorted by Swami rank (see "rank" Swami property).

`object` : | Swami root object (SwamiRoot) or an object added to one
`type_name` : | Name of GObject derived GType of objects to search for, objects derived from this type will also match.
Returns : | New list of objects of `type_name` and/or derived from it or NULL if no matches to that type. The returned list has a reference count of 1 which the caller owns, remember to unref it when finished.

### swami_object_get_by_type ()

    GObject *           swami_object_get_by_type            (GObject *object,
                                                             const char *type_name);

Lookup the highest ranking (see "rank" Swami property) object of the given `type_name` or derived from it. The returned object's reference count is incremented and the caller is responsible for removing it with g_object_unref when finished with it.

`object` : | Swami root object (SwamiRoot) or an object added to one
`type_name` : | Name of GObject derived GType to search for
Returns : | The highest ranking object of the given type or NULL if none. Remember to unreference it when done.

### swami_object_get_valist ()

    void                swami_object_get_valist             (GObject *object,
                                                             const char *first_property_name,
                                                             va_list var_args);

Get Swami properties from an object.

`object` : | An object
`first_property_name` : | Name of first Swami property to get
`var_args` : | Pointer to store first property value in followed by property name pointer pairs, terminated with a NULL property name.

### swami_object_get_property ()

    void                swami_object_get_property           (GObject *object,
                                                             const char *property_name,
                                                             GValue *value);

Get a Swami property from an object.

`object` : | An object
`property_name` : | Name of Swami property to get
`value` : | An initialized value to store the property value in. The value's type must be a type that the property can be transformed to.

### swami_object_get ()

    void                swami_object_get                    (gpointer object,
                                                             const char *first_prop_name,
                                                             ...);

Get multiple Swami properties from an `object`.

`object` : | A GObject
`first_prop_name` : | Name of first Swami property to get
`...` : | First value should be a pointer to store the first property value into followed by property name and pointer pairs, terminated by a `NULL` property name.

### swami_object_set_valist ()

    void                swami_object_set_valist             (GObject *object,
                                                             const char *first_property_name,
                                                             va_list var_args);

Set Swami properties of an object.

`object` : | An object
`first_property_name` : | Name of first Swami property to set
`var_args` : | Pointer to get first property value from followed by property name pointer pairs, terminated with a NULL property name.

### swami_object_set_property ()

    void                swami_object_set_property           (GObject *object,
                                                             const char *property_name,
                                                             const GValue *value);

Set a Swami property of an object.

`object` : | An object
`property_name` : | Name of Swami property to set
`value` : | Value to set the property to. The value's type must be the same as the property's type.

### swami_object_set ()

    void                swami_object_set                    (gpointer object,
                                                             const char *first_prop_name,
                                                             ...);

Set multiple Swami properties on an `object`.

`object` : | A GObject
`first_prop_name` : | Name of first Swami property to set
`...` : | First parameter should be the value to set the first property value to followed by property name and pointer pairs, terminated by a `NULL` property name.

### swami_find_object_property ()

    GParamSpec *        swami_find_object_property          (const char *property_name);

Find a Swami property.

`property_name` : | Name of Swami property to find
Returns : | Parameter spec with `property_name` or `NULL` if not found. Returned parameter spec is internal and should not be modified or freed.

### swami_list_object_properties ()

    GParamSpec **       swami_list_object_properties        (guint *n_properties);

Get the list of Swami properties.

`n_properties` : | Location to store number of param specs or `NULL`
Returns : | A `NULL` terminated array of GParamSpecs. Free the array when finished with it, but don't mess with the contents.

### swami_object_get_flags ()

    guint               swami_object_get_flags              (GObject *object);

Get Swami flags from an object (see SwamiObjectFlags).

`object` : | Object to get Swami flags from
Returns : | The flags value.

### swami_object_set_flags ()

    void                swami_object_set_flags              (GObject *object,
                                                             guint flags);

Sets Swami `flags` in an `object`. Flag bits are only set, not cleared.

`object` : | Object to set Swami flags on
`flags` : | Flags to set

### swami_object_clear_flags ()

    void                swami_object_clear_flags            (GObject *object,
                                                             guint flags);

Clears Swami `flags` in an `object`. Flag bits are only cleared, not set.

`object` : | Object to clear Swami flags on
`flags` : | Flags to clear

### swami_object_set_origin ()

    void                swami_object_set_origin             (GObject *obj,
                                                             GObject *origin);

This is used for associating an origin object to another object. Currently this is only used for GtkList item selections. The current active item selection is assigned to the swamigui_root object. In order to determine what GUI widget is the source, this function can be used to associate the widget object with the GtkList selection (for example the SwamiguiTree or SwamiguiSplits widgets). In this way, only the selection needs to be assigned to the root object and the source widget can be determined.

`obj` : | Object to assign origin object value
`origin` : | Value to assign as the origin

### swami_object_get_origin ()

    GObject *           swami_object_get_origin             (GObject *obj);

See `swamigui_object_set_origin()` for more details.

`obj` : | Object to get the origin object of
Returns : | The origin object of `obj` or NULL if no origin object assigned. The caller owns a reference to the returned object and should unref it when finished.