## SwamiControlProp SwamiControlProp |

## Synopsis

                        SwamiControlProp;
    SwamiControl *      swami_get_control_prop              (GObject *object,
                                                             GParamSpec *pspec);
    SwamiControl *      swami_get_control_prop_by_name      (GObject *object,
                                                             const char *name);
    void                swami_control_prop_connect_objects  (GObject *src,
                                                             const char *propname1,
                                                             GObject *dest,
                                                             const char *propname2,
                                                             guint flags);
    void                swami_control_prop_connect_to_control
                                                            (GObject *src,
                                                             const char *propname,
                                                             SwamiControl *dest,
                                                             guint flags);
    void                swami_control_prop_connect_from_control
                                                            (SwamiControl *src,
                                                             GObject *dest,
                                                             const char *propname,
                                                             guint flags);
    SwamiControlProp *  swami_control_prop_new              (GObject *object,
                                                             GParamSpec *pspec);
    void                swami_control_prop_assign           (SwamiControlProp *ctrlprop,
                                                             GObject *object,
                                                             GParamSpec *pspec,
                                                             gboolean send_events);
    void                swami_control_prop_assign_by_name   (SwamiControlProp *ctrlprop,
                                                             GObject *object,
                                                             const char *prop_name);

## Object Hierarchy

      GObject
       +----SwamiLock
             +----SwamiControl
                   +----SwamiControlProp

## Description

## Details

### SwamiControlProp

    typedef struct _SwamiControlProp SwamiControlProp;

### swami_get_control_prop ()

    SwamiControl *      swami_get_control_prop              (GObject *object,
                                                             GParamSpec *pspec);

Gets the SwamiControlProp object associated with an object's GObject property by `pspec`. If a control for the given `object` and `pspec` does not yet exist, then it is created and returned. Passing `NULL` for `object` and/or `pspec` create's a wildcard control which receives property change events for a specific property of all items (`object` is `NULL`), any property of a specifc item (`pspec` is `NULL`) or all item property changes (both are `NULL`). Note that wildcard property controls only work for IpatchItem derived objects currently.

`object` : | Object to get property control from (`NULL` for wildcard, IpatchItem only)
`pspec` : | Property parameter spec of `object` to get control for (`NULL` for wildcard, IpatchItem only)
Returns : | The control associated with the `object` and property `pspec`. Caller owns a reference to the returned object and should unref it when finished.

### swami_get_control_prop_by_name ()

    SwamiControl *      swami_get_control_prop_by_name      (GObject *object,
                                                             const char *name);

Like `swami_get_control_prop()` but takes a property name instead. It is also therefore not possible to specify a wildcard `object` (`NULL`).

`object` : | Object to get property control from
`name` : | A property of `object` to get the control for (or `NULL` for wildcard, IpatchItem derived objects only)
Returns : | The control associated with the `object` and property `name`. Caller owns a reference to the returned object and should unref it when finished.

### swami_control_prop_connect_objects ()

    void                swami_control_prop_connect_objects  (GObject *src,
                                                             const char *propname1,
                                                             GObject *dest,
                                                             const char *propname2,
                                                             guint flags);

Connect the properties of two objects together using SwamiControlProp controls.

`src` : | Source object
`propname1` : | Property of source object (and `dest` if `propname2` is `NULL`).
`dest` : | Destination object
`propname2` : | Property of destination object (`NULL` to use `propname1`).
`flags` : | Same flags as for `swami_control_connect()`.

### swami_control_prop_connect_to_control ()

    void                swami_control_prop_connect_to_control
                                                            (GObject *src,
                                                             const char *propname,
                                                             SwamiControl *dest,
                                                             guint flags);

A convenience function to connect an object property as the source control to another SwamiControl.

`src` : | Object with property to connect as source
`propname` : | Property of `object` to use as source control
`dest` : | Destination control to connect the object property to
`flags` : | Same flags as for `swami_control_connect()`.

### swami_control_prop_connect_from_control ()

    void                swami_control_prop_connect_from_control
                                                            (SwamiControl *src,
                                                             GObject *dest,
                                                             const char *propname,
                                                             guint flags);

A convenience function to connect a SwamiControl to an object property as the destination control.

`src` : | Source control to connect to an object property
`dest` : | Object with property to connect to
`propname` : | Property of `object` to use as destination control
`flags` : | Same flags as for `swami_control_connect()`.

### swami_control_prop_new ()

    SwamiControlProp *  swami_control_prop_new              (GObject *object,
                                                             GParamSpec *pspec);

Create a new GObject property control. Note that `swami_get_control_prop()` is likely more desireable to use, since it will return an existing control if one already exists for the given `object` and `pspec`.

If one of `object` or `pspec` is `NULL` then it acts as a wildcard and the control will send only (transmit changes for matching properties). If both are `NULL` however, the control has no active property to control (use `swami_get_control_prop()` if a IpatchItem entirely wildcard callback is desired). If `object` and/or `pspec` is wildcard then the control will use SwamiEventPropChange events instead of just the property value.

`object` : | Object with property to control or `NULL` for wildcard
`pspec` : | Parameter spec of property to control or `NULL` for wildcard
Returns : | New GObject property control with a refcount of 1 which the caller owns.

### swami_control_prop_assign ()

    void                swami_control_prop_assign           (SwamiControlProp *ctrlprop,
                                                             GObject *object,
                                                             GParamSpec *pspec,
                                                             gboolean send_events);

Assign the object property to control for a SwamiControlProp object. If a property is already set for the control the new object property must honor existing input/output connections by being writable/readable respectively and have the same value type.

If one of `object` or `pspec` is `NULL` then it acts as a wildcard and the control will send only (transmit changes for matching properties). If both are `NULL` however, the control has no active property to control.

`ctrlprop` : | Swami property control object
`object` : | Object containing the property to control (`NULL` = wildcard)
`pspec` : | Parameter spec of the property of `object` to control (`NULL` = wildcard)
`send_events` : | Set to `TRUE` to send/receive SwamiEventPropChange events for the `ctrlprop`, `FALSE` will use just the property value.

### swami_control_prop_assign_by_name ()

    void                swami_control_prop_assign_by_name   (SwamiControlProp *ctrlprop,
                                                             GObject *object,
                                                             const char *prop_name);

Like `swami_control_prop_assign()` but accepts a name of a property instead of the param spec. Note also that `object` may not be wildcard, contrary to the other function.

`ctrlprop` : | Swami property control object
`object` : | Object containing the property to control (or `NULL` to un-assign)
`prop_name` : | Name of property to assign to property control (or `NULL` for wildcard, IpatchItem types only, or to un-assign if `object` is also `NULL`)