## SwamiguiControl SwamiguiControl |

## Synopsis

    enum                SwamiguiControlRank;
    #define             SWAMIGUI_CONTROL_RANK_DEFAULT
    #define             SWAMIGUI_CONTROL_RANK_MASK
    enum                SwamiguiControlFlags;
    #define             SWAMIGUI_CONTROL_CTRLVIEW
    enum                SwamiguiControlObjectFlags;
    SwamiControl *      (*SwamiguiControlHandler)           (GObject *widget,
                                                             GType value_type,
                                                             GParamSpec *pspec,
                                                             SwamiguiControlFlags flags);
    extern              GQuark swamigui_control_quark;
    SwamiControl *      swamigui_control_new                (GType type);
    SwamiControl *      swamigui_control_new_for_widget     (GObject *widget);
    SwamiControl *      swamigui_control_new_for_widget_full
                                                            (GObject *widget,
                                                             GType value_type,
                                                             GParamSpec *pspec,
                                                             SwamiguiControlFlags flags);
    SwamiControl *      swamigui_control_lookup             (GObject *widget);
    void                swamigui_control_prop_connect_widget
                                                            (GObject *object,
                                                             const char *propname,
                                                             GObject *widget);
    GObject *           swamigui_control_create_widget      (GType widg_type,
                                                             GType value_type,
                                                             GParamSpec *pspec,
                                                             SwamiguiControlFlags flags);
    void                swamigui_control_set_queue          (SwamiControl *control);
    void                swamigui_control_register           (GType widg_type,
                                                             GType value_type,
                                                             SwamiguiControlHandler handler,
                                                             guint flags);
    void                swamigui_control_unregister         (GType widg_type,
                                                             GType value_type);
    void                swamigui_control_glade_prop_connect (GtkWidget *widget,
                                                             GObject *obj);
    GType               swamigui_control_get_alias_value_type
                                                            (GType type);

## Description

## Details

### enum SwamiguiControlRank

    typedef enum
    {
      SWAMIGUI_CONTROL_RANK_LOWEST  = 1,
      SWAMIGUI_CONTROL_RANK_LOW     = 16,
      SWAMIGUI_CONTROL_RANK_NORMAL  = 32,
      SWAMIGUI_CONTROL_RANK_HIGH    = 48,
      SWAMIGUI_CONTROL_RANK_HIGHEST = 63
    } SwamiguiControlRank;

### SWAMIGUI_CONTROL_RANK_DEFAULT

    #define SWAMIGUI_CONTROL_RANK_DEFAULT SWAMIGUI_CONTROL_RANK_NORMAL

### SWAMIGUI_CONTROL_RANK_MASK

    #define SWAMIGUI_CONTROL_RANK_MASK 0x3F

### enum SwamiguiControlFlags

    typedef enum
    {
      SWAMIGUI_CONTROL_CTRL      =  0x40, /* controls values */
      SWAMIGUI_CONTROL_VIEW      =  0x80, /* displays values */
      SWAMIGUI_CONTROL_NO_CREATE = 0x100 /* don't create control, cfg UI obj only */
    } SwamiguiControlFlags;

### SWAMIGUI_CONTROL_CTRLVIEW

    #define SWAMIGUI_CONTROL_CTRLVIEW  (SWAMIGUI_CONTROL_CTRL | SWAMIGUI_CONTROL_VIEW)

### enum SwamiguiControlObjectFlags

    typedef enum  /*< flags >*/
    {
      SWAMIGUI_CONTROL_OBJECT_NO_LABELS   = 1 << 0,
      SWAMIGUI_CONTROL_OBJECT_NO_SORT     = 1 << 1,
      SWAMIGUI_CONTROL_OBJECT_PROP_LABELS = 1 << 2
    } SwamiguiControlObjectFlags;

### SwamiguiControlHandler ()

    SwamiControl *      (*SwamiguiControlHandler)           (GObject *widget,
                                                             GType value_type,
                                                             GParamSpec *pspec,
                                                             SwamiguiControlFlags flags);

This is a function type to handle the creation of a control that is bound to a GUI interface `widget`. The control should be configured according to `flags` (if its display only then UI control changes should be ignored or preferably disabled, control only flag will occur only with handlers that don't display value changes). The UI `widget` may be modified to conform to `pspec` (valid range, max string length, etc) and should be done in a manner that allows `widget` to be re-configured (i.e., set default values if `pspec` not supplied).

`widget` : | GUI widget to create a control for
`value_type` : | Control value type (useful to handler functions that can handle multiple value types)
`pspec` : | Parameter spec defining the control parameters (value type, valid range, etc), will be a GParamSpec of the specified `value_type` or `NULL` for defaults
`flags` : | Flags indicating if control should display values or control and display values. If the SWAMIGUI_CONTROL_NO_CREATE flag is specified then a control should not be created, but `widget` should be configured to conform to `pspec` (or reset to defaults if `NULL`).
Returns : | Should return the new control which is controlling the GUI interface `widget`.

### swamigui_control_quark

    extern GQuark swamigui_control_quark;

### swamigui_control_new ()

    SwamiControl *      swamigui_control_new                (GType type);

Create a control of the given `type` which should be a SwamiControl derived type. The created control is automatically added to the SwamiguiRoot GUI control event queue. Just a convenience function really.

`type` : | A SwamiControl derived GType of control to create
Returns : | New control with a refcount of 1 which the caller owns.

### swamigui_control_new_for_widget ()

    SwamiControl *      swamigui_control_new_for_widget     (GObject *widget);

Creates a new control for a GUI widget. Use `swami_control_new_for_widget_full()` for additional parameters.

`widget` : | GUI widget to create a control for
Returns : | The new control or `NULL` if `widget` not handled. The returned control does NOT have a reference since the `widget` is the owner of the control. Destroying the `widget` will cause the control to be disconnected and unref'd, if there are no more references the control will be freed.

### swamigui_control_new_for_widget_full ()

    SwamiControl *      swamigui_control_new_for_widget_full
                                                            (GObject *widget,
                                                             GType value_type,
                                                             GParamSpec *pspec,
                                                             SwamiguiControlFlags flags);

Creates a new control for a GUI widget, provided there is a registered handler for the `widget` type/value type combination. The new control is automatically assigned to the GUI queue in swamigui_root. A widget's control can be retrieved with `swamigui_control_lookup()`. If the given `widget` already has a control it is returned. The `pspec` parameter allows for additional settings to be applied to the `widget` and/or control (such as a valid range or max string length, etc).

`widget` : | GUI widget to control
`value_type` : | Control value type or 0 for default
`pspec` : | Parameter spec to define valid ranges and other parameters, should be a GParamSpec of `value_type` or `NULL` for defaults
`flags` : | Flags for creating the new control. To create a display only control just the SWAMIGUI_CONTROL_VIEW flag can be specified, 0 means both control and view (SWAMIGUI_CONTROL_CTRLVIEW).
Returns : | The new control or `NULL` if `widget`/`value_type` not handled. The returned control does NOT have a reference since the `widget` is the owner of the control. Destroying the `widget` will cause the control to be disconnected and unref'd, if there are no more references the control will be freed.

### swamigui_control_lookup ()

    SwamiControl *      swamigui_control_lookup             (GObject *widget);

`widget` : | User interface widget to lookup the SwamiControl of
Returns : | The associated SwamiControl or NULL if none. The return control is NOT referenced for the caller (don't unref it).

### swamigui_control_prop_connect_widget ()

    void                swamigui_control_prop_connect_widget
                                                            (GObject *object,
                                                             const char *propname,
                                                             GObject *widget);

A convenience function which connects a widget as a control for a given `object` property. Use `swamigui_control_prop_connect_widget_full()` for additional options.

`object` : | Object with property to connect
`propname` : | Property of `object` to connect
`widg` : | Widget to control object property

### swamigui_control_create_widget ()

    GObject *           swamigui_control_create_widget      (GType widg_type,
                                                             GType value_type,
                                                             GParamSpec *pspec,
                                                             SwamiguiControlFlags flags);

Creates a GUI widget suitable for controlling values of type `value_type`. The `widg_type` parameter is used to specify what base type of widget to create, GTK_TYPE_WIDGET is assumed if 0.

`widg_type` : | A base type of new widget (GtkWidget, GnomeCanvasItem, etc) or 0 for default GtkWidget derived types.
`value_type` : | Control value type
`pspec` : | Parameter spec to define valid ranges and other parameters, should be a GParamSpec of `value_type` or `NULL` for defaults
`flags` : | Can be used to specify view only controls by passing SWAMIGUI_CONTROL_VIEW in which case view only control handlers will be preferred. A value of 0 assumes control and view mode (SWAMIGUI_CONTROL_CTRLVIEW).
Returns : | The new GUI widget derived from `widg_type` and suitable for controlling values of type `value_type` or `NULL` if `value_type`/`widg_type` not handled. The new object uses the Gtk reference counting behavior.

### swamigui_control_set_queue ()

    void                swamigui_control_set_queue          (SwamiControl *control);

Set a control to use a GUI queue which is required for all controls that may be controlled from a non-GUI thread.

`control` : | Control to assign to the GUI queue

### swamigui_control_register ()

    void                swamigui_control_register           (GType widg_type,
                                                             GType value_type,
                                                             SwamiguiControlHandler handler,
                                                             guint flags);

This function registers new GUI control types. It is multi-thread safe and can be called outside of the GUI thread (from a plugin for instance). If the given `widg_type`/`value_type` already exists then the new `handler` is used. The `flags` parameter specifies the rank to give preference to handlers with the same `value_type` and also contains control/view capability flags.

`widg_type` : | Type of object control to register
`value_type` : | The control value type
`handler` : | Handler function for creating the control
`flags` : | A rank value between 1:lowest to 63:highest, 0:default (see SwamiguiControlRank) or'ed with SwamiguiControlFlags defining the view/control capabilities of this handler. The rank allows preferred object types to be chosen when there are multiple object control handlers for the same value and base object types. If neither SWAMIGUI_CONTROL_VIEW or SWAMIGUI_CONTROL_CTRL are specified then control/view is assumed (SWAMIGUI_CONTROL_CTRLVIEW).

### swamigui_control_unregister ()

    void                swamigui_control_unregister         (GType widg_type,
                                                             GType value_type);

Unregisters a previous `widg_type`/`value_type` GUI control handler. It is multi-thread safe and can be called outside of GUI thread (from a plugin for instance).

`widg_type` : | Object type of control handler to unregister
`value_type` : | The value type of the control handler

### swamigui_control_glade_prop_connect ()

    void                swamigui_control_glade_prop_connect (GtkWidget *widget,
                                                             GObject *obj);

This function connects a libglade created `widget`, with child widgets whose names are of the form "PROP::[prop-name]", to the corresponding GObject properties of `obj` ([prop-name] values). An example child widget name would be "PROP::volume" which would control the "volume" property of an object. This allows for object GUI interfaces to be created with a minimum of code.

`widget` : | A GTK widget created by libglade
`obj` : | Object to control properties of or `NULL` to unset active object

### swamigui_control_get_alias_value_type ()

    GType               swamigui_control_get_alias_value_type
                                                            (GType type);