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