Parameter Specification

## Parameter Specification Parameter Specification — Custom plugin parameter type |

## Synopsis

    #include <gnome-scan.h>

    #define             GS_DEFINE_PARAM                     (prefix, Prefix, param_name, ParamName, VALUE_TYPE)
    #define             GS_PARAM_GROUP_SCANNER_FRONT
    #define             GS_PARAM_GROUP_FORMAT
    #define             GS_PARAM_GROUP_SINK_FRONT
    #define             GS_PARAM_GROUP_PREVIEW
    #define             GS_PARAM_GROUP_HIDDEN
    GQuark              gs_param_spec_get_group             (GParamSpec *spec);
    const gchar*        gs_param_spec_get_group_string      (GParamSpec *spec);
    void                gs_param_spec_set_group             (GParamSpec *spec,
                                                             GQuark group);
    void                gs_param_spec_set_group_from_string (GParamSpec *spec,
                                                             const gchar *group);
    void                gs_param_spec_set_domain            (GParamSpec *spec,
                                                             const gchar *domain);
    const gchar*        gs_param_spec_get_domain            (GParamSpec *spec);
    void                gs_param_spec_set_unit              (GParamSpec *spec,
                                                             GnomeScanUnit unit);
    GnomeScanUnit       gs_param_spec_get_unit              (GParamSpec *spec);
    void                gs_param_spec_set_index             (GParamSpec *spec,
                                                             guint index);
    guint               gs_param_spec_get_index             (GParamSpec *spec);
    void                gs_param_spec_set_widget_type       (GParamSpec *spec,
                                                             GType type);
    GParamSpec*         gs_param_spec_boolean               (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             gboolean default_value,
                                                             GParamFlags flags);
    GParamSpec*         gs_param_spec_int                   (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             gint minimum,
                                                             gint maximum,
                                                             gint default_value,
                                                             GParamFlags flags);
    GParamSpec*         gs_param_spec_double                (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             gdouble minimum,
                                                             gdouble maximum,
                                                             gdouble default_value,
                                                             GParamFlags flags);
    GParamSpec*         gs_param_spec_string                (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             const gchar *default_value,
                                                             GParamFlags flags);
    GParamSpec*         gs_param_spec_pointer               (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             GType widget,
                                                             GParamFlags flags);
    GParamSpec*         gs_param_spec_range                 (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             GValue *minimum,
                                                             GValue *maximum,
                                                             GValue *step,
                                                             GValue *default_value,
                                                             GParamFlags flags);
    GParamSpec*         gs_param_spec_enum                  (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             GValueArray *values,
                                                             GValue *default_value,
                                                             GParamFlags flags);
    GParamSpec*         gs_param_spec_paper_size            (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             GtkPaperSize *default_ps,
                                                             GSList *enumeration,
                                                             GParamFlags flags);
    GParamSpec*         gs_param_spec_page_orientation      (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             guint default_value,
                                                             GParamFlags flags);

## Description

Instead of using a all-in-one option object (like in Gnome Scan 0.4), Gnome Scan now use regular GParamSpecs. Gnome Scan GParamSpecs (referred as GSParamSpecs) have been designed in order to build generic widget for plugins parameters (like Gegl and other projects does). A common attribute added to each GSParamSpec is the `group` quark. The `group` quark is computed from the translated group title.

Also, GSParamSpecs are much more high-level than it's parent GParamSpec in order to build complex param widgets (range, area, paper-size, …).

Current implementation makes a heavy use of `g_param_spec_set_qdata()`, because GParamSpec is a shallow type. Future implementation might break thing for either creating its own GSParamSpec fundamental type or simply using a common struct right after the `parent_instance` field.

## Details

### GS_DEFINE_PARAM()

    #define             GS_DEFINE_PARAM(prefix, Prefix, param_name, ParamName, VALUE_TYPE)

Convenient function that avoid duplicated bug writing GLib boiler plate for GType registration for a custom GParamSpec.

For example:

     GS_DEFINE_PARAM (foo, Foo,bar, Bar, G_TYPE_INT);

expands to:

     GType
     foo_param_bar_get_type () {
     static GType type = 0;
     if (!type) {
     const GParamSpecTypeInfo info = {
     sizeof (FooParamBarSpec),
     0, NULL, G_TYPE_INT,
     NULL, NULL, NULL, NULL };
     type = g_param_type_register_static ("FooParamBarSpec", &info);
     }
     return type;
     }

You'll then have to declare a FooParamSpecBar structure as well as declaring `foo_param_bar_get_type()` and writing some macros.

`prefix` : |
`Prefix` : |
`param_name` : | param prefix
`ParamName` : | Capitalized param name
`VALUE_TYPE` : | The macro returning the value GType

### GS_PARAM_GROUP_SCANNER_FRONT

    #define	GS_PARAM_GROUP_SCANNER_FRONT	(gs_scanner_front_quark ())

Scanner option group for not every user

### GS_PARAM_GROUP_FORMAT

    #define	GS_PARAM_GROUP_FORMAT			(gs_format_quark ())

### GS_PARAM_GROUP_SINK_FRONT

    #define	GS_PARAM_GROUP_SINK_FRONT		(gs_sink_front_quark ())

### GS_PARAM_GROUP_PREVIEW

    #define	GS_PARAM_GROUP_PREVIEW			(gs_preview_quark())

Scanner option group for preview page. Option that's needs instant view of the effect of selecting them

### GS_PARAM_GROUP_HIDDEN

    #define	GS_PARAM_GROUP_HIDDEN			(gs_hidden_quark())

Scanner option group not shown to user

### gs_param_spec_get_group ()

    GQuark              gs_param_spec_get_group             (GParamSpec *spec);

Retrieve the `spec` group. Since the `group` is not store in a struct, but using qdata, just cast `spec` to GParamSpec.

`spec` : | The GSParamSpec
Returns : | `spec` group's quark

### gs_param_spec_get_group_string ()

    const gchar*        gs_param_spec_get_group_string      (GParamSpec *spec);

Retrieve the `spec` group string. Since the `group` is not store in a struct, but using qdata, just cast `spec` to GParamSpec. The string is not translated.

See: `gs_param_spec_get_group()`

`spec` : | The GSParamSpec
Returns : | `spec` group's quark

### gs_param_spec_set_group ()

    void                gs_param_spec_set_group             (GParamSpec *spec,
                                                             GQuark group);

`spec` : | a GSParamSpec
`group` : | new `spec` group's GQuark.

### gs_param_spec_set_group_from_string ()

    void                gs_param_spec_set_group_from_string (GParamSpec *spec,
                                                             const gchar *group);

`spec` : | a GSParamSpec
`group` : | new `spec` group name

### gs_param_spec_set_domain ()

    void                gs_param_spec_set_domain            (GParamSpec *spec,
                                                             const gchar *domain);

`spec` : | a GSParamSpec
`domain` : | `domain` for translating `spec` `nick` and `blurb`

### gs_param_spec_get_domain ()

    const gchar*        gs_param_spec_get_domain            (GParamSpec *spec);

`spec` : | a GSParamSpec
Returns : |

### gs_param_spec_set_unit ()

    void                gs_param_spec_set_unit              (GParamSpec *spec,
                                                             GnomeScanUnit unit);

Parameter unit is specified for UI, but can also be need for e.g. length of scan ROI where unit translation might occur.

`spec` : | a GSParamSpec
`unit` : | GnomeScanUnit fo `spec`

### gs_param_spec_get_unit ()

    GnomeScanUnit       gs_param_spec_get_unit              (GParamSpec *spec);

`spec` : | a GSParamSpec
Returns : | a GnomeScanUnit

### gs_param_spec_set_index ()

    void                gs_param_spec_set_index             (GParamSpec *spec,
                                                             guint index);

`spec` : | a GSParamSpec
`index` : | new `spec`'index

### gs_param_spec_get_index ()

    guint               gs_param_spec_get_index             (GParamSpec *spec);

`spec` : | a GSParamSpec
Returns : | an integer.

### gs_param_spec_set_widget_type ()

    void                gs_param_spec_set_widget_type       (GParamSpec *spec,
                                                             GType type);

This part is the only bound from backend to frontend. It might be removed later. The idea is to have widget per param, not per type.

`spec` : | a GSParamSpec
`type` : | a widget GType

### gs_param_spec_boolean ()

    GParamSpec*         gs_param_spec_boolean               (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             gboolean default_value,
                                                             GParamFlags flags);

Create a new GSParamSpec of for boolean value. `name` is for use internally (e.g. gconf key) while nick and `blurb` should be marked for translation.

`name` : | param name
`nick` : | param nickname
`blurb` : | description of the parameter
`group` : | param group quark
`default_value` : | default value
`flags` : | Flags
Returns : | a new GSParamSpec

### gs_param_spec_int ()

    GParamSpec*         gs_param_spec_int                   (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             gint minimum,
                                                             gint maximum,
                                                             gint default_value,
                                                             GParamFlags flags);

Create a new GSParamSpec of for integer value. `name` is for use internally (e.g. gconf key) while nick and `blurb` should be marked for translation.

`name` : | param name
`nick` : | param nickname
`blurb` : | description of the parameter
`group` : | param group quark
`minimum` : | minimum value
`maximum` : | maximum value
`default_value` : | default value
`flags` : | Flags
Returns : | a new GSParamSpec

### gs_param_spec_double ()

    GParamSpec*         gs_param_spec_double                (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             gdouble minimum,
                                                             gdouble maximum,
                                                             gdouble default_value,
                                                             GParamFlags flags);

Create a new GSParamSpec of for double value. `name` is for use internally (e.g. gconf key) while nick and `blurb` should be marked for translation.

`name` : | param name
`nick` : | param nickname
`blurb` : | description of the parameter
`group` : | param group quark
`minimum` : | minimum value
`maximum` : | maximum value
`default_value` : | default value
`flags` : | Flags
Returns : | a new GSParamSpec

### gs_param_spec_string ()

    GParamSpec*         gs_param_spec_string                (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             const gchar *default_value,
                                                             GParamFlags flags);

Create a new GSParamSpec of for string value. `name` is for use internally (e.g. gconf key) while nick and `blurb` should be marked for translation.

`name` : | param name
`nick` : | param nickname
`blurb` : | description of the parameter
`group` : | param group quark
`default_value` : | default value
`flags` : | Flags
Returns : | a new GSParamSpec

### gs_param_spec_pointer ()

    GParamSpec*         gs_param_spec_pointer               (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             GType widget,
                                                             GParamFlags flags);

Create a new GSParamSpec of for boolean value. `name` is for use internally (e.g. gconf key) while nick and `blurb` should be marked for translation.

Other GSParamSpec have predefined widget type. Pointer spec allow to store alsmost everything and thus needs specific widget type.

`name` : | param name
`nick` : | param nickname
`blurb` : | description of the parameter
`group` : | param group quark
`widget` : | widget type
`flags` : | Flags
Returns : | a new GSParamSpec

### gs_param_spec_range ()

    GParamSpec*         gs_param_spec_range                 (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             GValue *minimum,
                                                             GValue *maximum,
                                                             GValue *step,
                                                             GValue *default_value,
                                                             GParamFlags flags);

Create a new GSParamSpecRange. This spec has been designed to store both integer and float value. Ensure all GValue have the same type.

`name` : | spec name
`nick` : | spec nick
`blurb` : | spec blurb
`group` : | The quark of the group the param belong to
`minimum` : | value of the lowest allowed value
`maximum` : | value of the highed allowed value
`step` : | lenght between two values
`default_value` : |
`flags` : | Param flags.
Returns : | the new GSParamSpecRange

### gs_param_spec_enum ()

    GParamSpec*         gs_param_spec_enum                  (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             GValueArray *values,
                                                             GValue *default_value,
                                                             GParamFlags flags);

Create a new GSParamSpecEnum . This parameter spec has been designed to handle integer, float and string value.

`name` : | spec name
`nick` : | spec nick
`blurb` : | spec blurb
`group` : | The quark of the group the param belong to
`values` : | Allowed values
`default_value` : | default value;
`flags` : | Param flags.
Returns : | the new GSParamSpecEnum

### gs_param_spec_paper_size ()

    GParamSpec*         gs_param_spec_paper_size            (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             GtkPaperSize *default_ps,
                                                             GSList *enumeration,
                                                             GParamFlags flags);

Create a new GSParamSpec of for GtkPaperSize value. `name` is for use internally (e.g. gconf key) while nick and `blurb` should be marked for translation.

`name` : | param name
`nick` : | param nickname
`blurb` : | description of the parameter
`group` : | param group quark
`default_ps` : | default paper size
`enumeration` : | available paper size
`flags` : | Flags
Returns : | a new GSParamSpec

### gs_param_spec_page_orientation ()

    GParamSpec*         gs_param_spec_page_orientation      (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GQuark group,
                                                             guint default_value,
                                                             GParamFlags flags);

Create a new GSParamSpec of for GtkPageOrientation value. `name` is for use internally (e.g. gconf key) while nick and `blurb` should be marked for translation.

`name` : | param name
`nick` : | param nickname
`blurb` : | description of the parameter
`group` : | param group quark
`default_value` : | default value
`flags` : | Flags
Returns : | a new GSParamSpec