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