Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

GwyParamDef

GwyParamDef — Module parameter definitions

Functions

gchar * (*GwyRectifyStringFunc) ()
GwyParamDef * gwy_param_def_new ()
void gwy_param_def_set_function_name ()
const gchar * gwy_param_def_get_function_name ()
const gchar * gwy_param_def_get_param_name ()
const gchar * gwy_param_def_get_param_label ()
void gwy_param_def_add_gwyenum ()
void gwy_param_def_add_gwyflags ()
void gwy_param_def_add_enum ()
void gwy_param_def_add_int ()
void gwy_param_def_add_graph_curve ()
void gwy_param_def_add_lawn_curve ()
void gwy_param_def_add_lawn_segment ()
void gwy_param_def_add_active_page ()
void gwy_param_def_add_boolean ()
void gwy_param_def_add_instant_updates ()
void gwy_param_def_add_randomize ()
void gwy_param_def_add_double ()
void gwy_param_def_add_angle ()
void gwy_param_def_add_percentage ()
void gwy_param_def_add_mask_color ()
void gwy_param_def_add_color ()
void gwy_param_def_add_target_graph ()
void gwy_param_def_add_graph_id ()
void gwy_param_def_add_image_id ()
void gwy_param_def_add_volume_id ()
void gwy_param_def_add_xyz_id ()
void gwy_param_def_add_curve_map_id ()
void gwy_param_def_add_report_type ()
void gwy_param_def_add_hold_selection ()
void gwy_param_def_add_seed ()
void gwy_param_def_add_string ()
void gwy_param_def_add_unit ()
void gwy_param_def_add_resource ()
void gwy_param_def_add_grain_groups ()

Types and Values

enum GwyParamStringFlags
struct GwyParamDef
struct GwyParamDefClass

Object Hierarchy

    GObject
    ╰── GwyParamDef

Includes

#include <app/gwyapp.h>

Description

GwyParamDef represents a set of module parameter definitions. Once constructed, it is an immutable object which modules generally keep around (as a static variable) and use it to fetch parameters from settings as GwyParams.

Parameters are idenfitied by integers which must be unique within one set of definitions. The integers are not public interface. They only exist within the module and can change between module versions. In fact, you can assign them run-time (and differently each time Gwyddion is run) if you need. However, the usual way to define the parameters is using an enum:

1
2
3
4
5
enum {
    PARAM_DEGREE,
    PARAM_MASKING,
    PARAM_UPDATE,
};

and the module then refers to the parameters using the enum values. The corresponding parameter definition code could be as follows. Notice specialised parameter types exists for some common settings, such as instant updates:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
static GwyParamDef*
define_module_params()
{
    static GwyParamDef *paramdef = NULL;

    if (paramdef)
        return paramdef;

    paramdef = gwy_param_def_new();
    gwy_param_def_set_function_name(paramdef, gwy_process_func_current());
    gwy_param_def_add_int(paramdef, PARAM_DEGREE, "degree", _("_Degree"), 0, 12, 3);
    gwy_param_def_add_gwyenum(paramdef, PARAM_MASKING, "masking", NULL, GWY_TYPE_MASKING_TYPE, GWY_MASK_IGNORE);
    gwy_param_def_add_instant_updates(paramdef, PARAM_UPDATE, "update", NULL, FALSE);
    return paramdef;
}

Functions such as g_once() and g_once_init_enter() can also be used to ensure a single initialisation, although it is probably overkill here.

In all the parameter definition constructors strings name and desc are not copied. They must exist for the entire lifetime of the pardef objects. Usually they are static strings. In uncommon scenarios the caller must ensure their existence. Alternatively, g_intern_string() can be used to make semantically static versions of the strings.

Functions

GwyRectifyStringFunc ()

gchar *
(*GwyRectifyStringFunc) (const gchar *s);

Type of function returning a valid string, given possibly invalid input.

Either the input and output can be NULL (if the string definition allows it).

Parameters

s

Input string.

 

Returns

Newly allocated string, presumably corrected.

Since: 2.59

gwy_param_def_new ()

GwyParamDef *
gwy_param_def_new (void);

Creates a new empty set of parameter definitions.

Definitions can be added only during construction, i.e. until the first time it is used to create GwyParams. Then the definition set must be considered immutable.

Returns

A newly create paramete definition set.

Since: 2.59

gwy_param_def_set_function_name ()

void
gwy_param_def_set_function_name (GwyParamDef *pardef,
                                 const gchar *name);

Sets the settings function name of a set of parameter definitions.

Usually the function name should be given simply as gwy_process_func_current() (or analogous functions for other module types). The exception is functions with settings keys different from module function name. If the name is unset then GwyParams settings functions like gwy_params_new_from_settings() cannot be used.

The function name can be set freely even after construction. This allows having just a single set of parameter definitions for multiple related module functions which all have the same parameters.

Parameters

pardef

A set of parameter definitions.

 

name

Settings function name, or NULL.

 

Since: 2.59

gwy_param_def_get_function_name ()

const gchar *
gwy_param_def_get_function_name (GwyParamDef *pardef);

Gets the settings function name of a set of parameter definitions.

Parameters

pardef

A set of parameter definitions.

 

Returns

The functions name (possibly NULL).

Since: 2.59

gwy_param_def_get_param_name ()

const gchar *
gwy_param_def_get_param_name (GwyParamDef *pardef,
                              gint id);

Gets the name of an already defined parameter in a set of parameter definitions.

See gwy_param_def_get_param_label() for parameter labels.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

Returns

The parameter name, as a string owned by pardef . It may be NULL if the parameter is not stored to settings.

Since: 2.62

gwy_param_def_get_param_label ()

const gchar *
gwy_param_def_get_param_label (GwyParamDef *pardef,
                               gint id);

Gets the label of an already defined parameter in a set of parameter definitions.

See gwy_param_def_get_param_name() for parameter names (keys).

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

Returns

The parameter name, as a string owned by pardef . It may be NULL if the parameter has no label.

Since: 2.62

gwy_param_def_add_gwyenum ()

void
gwy_param_def_add_gwyenum (GwyParamDef *pardef,
                           gint id,
                           const gchar *name,
                           const gchar *desc,
                           const GwyEnum *values,
                           gint nvalues,
                           gint default_value);

Defines a new parameter with enumerated values defined by a GwyEnum.

See the introduction for name and desc lifetime rules.

See gwy_param_def_add_enum() for predefined enums.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for the list header label in GUI. May be also NULL for no label.

 

values

An array of corresponding string-integer pairs.

 

nvalues

The number of nvalues items. It is possible to pass -1 to count the values automatically if the array is terminated by NULL name.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_gwyflags ()

void
gwy_param_def_add_gwyflags (GwyParamDef *pardef,
                            gint id,
                            const gchar *name,
                            const gchar *desc,
                            const GwyEnum *values,
                            gint nvalues,
                            guint default_value);

Defines a new parameter with bit flag values defined by a GwyEnum.

The values in values must represent a set of flags, i.e. numbers with exactly one 1-bit in binary.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for the list header label in GUI. May be also NULL for no label.

 

values

An array of corresponding string-integer pairs.

 

nvalues

The number of nvalues items. It is possible to pass -1 to count the values automatically if the array is terminated by NULL name.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_enum ()

void
gwy_param_def_add_enum (GwyParamDef *pardef,
                        gint id,
                        const gchar *name,
                        const gchar *desc,
                        GType enum_gtype,
                        gint default_value);

Defines a new parameter with enumerated values from a standard Gwyddion enum.

Supported enums include GwyMaskingType, GwyInterpolationType, GwyOrientation, GwyMergeType, GwyDistanceTransformType, GwyWindowingType and GwyGraphCurveType. They have standard labels allowing to pass NULL as desc .

See the introduction for name and desc lifetime rules.

See gwy_param_def_add_gwyenum() for enums defined by a GwyEnum table.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI. May be NULL for the default label.

 

enum_gtype

Type of the enum, for instance GWY_TYPE_MASKING_TYPE.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_int ()

void
gwy_param_def_add_int (GwyParamDef *pardef,
                       gint id,
                       const gchar *name,
                       const gchar *desc,
                       gint minimum,
                       gint maximum,
                       gint default_value);

Defines a new parameter with integer values.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

minimum

Minimum allowed value (inclusive).

 

maximum

Maximum allowed value (inclusive).

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_graph_curve ()

void
gwy_param_def_add_graph_curve (GwyParamDef *pardef,
                               gint id,
                               const gchar *name,
                               const gchar *desc);

Defines a new parameter with values that are graph curve numbers.

Curve numbers can be any non-negative integers. The upper bound is determined by GwyParamTable once the GUI for choosing a curve from specific graph model is set up. Value -1 is also allowed for empty graph models with no curves, but this should not normally occur.

Curve parameters are stored in settings as curve labels, even though they are treated integers otherwise. This helps selecting a curve with the same function/interpretation the next time the module is invoked – or the first curve if there is none such.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings.

 

desc

Parameter description which will be used for a label in GUI. It may be NULL for the default label.

 

Since: 2.60

gwy_param_def_add_lawn_curve ()

void
gwy_param_def_add_lawn_curve (GwyParamDef *pardef,
                              gint id,
                              const gchar *name,
                              const gchar *desc);

Defines a new parameter with values that are lawn curve numbers.

Curve numbers can be any non-negative integers. The upper bound is determined by GwyParamTable once the GUI for choosing a curve from specific lawn is set up.

Curve parameters are stored in settings as curve labels, even though they are treated integers otherwise. This helps selecting a curve with the same function/interpretation the next time the module is invoked – or the first curve if there is none such.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings.

 

desc

Parameter description which will be used for a label in GUI. It may be NULL for the default label.

 

Since: 2.60

gwy_param_def_add_lawn_segment ()

void
gwy_param_def_add_lawn_segment (GwyParamDef *pardef,
                                gint id,
                                const gchar *name,
                                const gchar *desc);

Defines a new parameter with values that are lawn segment numbers.

Segment numbers can be any non-negative integers. The upper bound is determined by GwyParamTable once the GUI for choosing a segment from specific lawn is set up. Value -1 is also allowed for empty lawns with no segments.

Segment parameters are stored in settings as segment labels, even though they are treated integers otherwise. This helps selecting a segment with the same function/interpretation the next time the module is invoked – or the first segment if there is none such.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings.

 

desc

Parameter description which will be used for a label in GUI. It may be NULL for the default label.

 

Since: 2.60

gwy_param_def_add_active_page ()

void
gwy_param_def_add_active_page (GwyParamDef *pardef,
                               gint id,
                               const gchar *name,
                               const gchar *desc);

Defines a new parameter with integer values representing module dialog active page.

The active page parameter can be connected to a GtkNotebook using the utility function gwy_param_active_page_link_to_notebook(). This is also the only function that should be used with such parameter.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL if not stored in settings, but then the active page parameter would have no reason to exist.

 

desc

Parameter description, usually NULL.

 

Since: 2.59

gwy_param_def_add_boolean ()

void
gwy_param_def_add_boolean (GwyParamDef *pardef,
                           gint id,
                           const gchar *name,
                           const gchar *desc,
                           gboolean default_value);

Defines a new parameter with boolean values.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_instant_updates ()

void
gwy_param_def_add_instant_updates (GwyParamDef *pardef,
                                   gint id,
                                   const gchar *name,
                                   const gchar *desc,
                                   gboolean default_value);

Defines a new boolean parameter representing the instant updates option.

Compared to a plain boolean, a parameter defined using this function has a predefined label and is recognised by GwyDialog. Therefore, it is not necessary to call gwy_dialog_set_instant_updates_param(). If your module GUI needs non-standard update settings then define the parameters manually.

Furthermore, it is normally not necessary (in fact, counterproductive) to call gwy_dialog_invalidate() when the instant updates parameter changes. Recalculation is only necessary when instant updates were just switched on and the current preview is no longer valid. GwyDialog handles this case automatically.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI. Usually NULL for the default label.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_randomize ()

void
gwy_param_def_add_randomize (GwyParamDef *pardef,
                             gint id,
                             gint seed_id,
                             const gchar *name,
                             const gchar *desc,
                             gboolean default_value);

Defines a new boolean parameter representing the randomize option for a random seed.

See gwy_param_def_add_seed() for random seed parameters.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

seed_id

Identifier of the corresponding random seed parameter. It must already be defined.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI. Usually NULL for the default label.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_double ()

void
gwy_param_def_add_double (GwyParamDef *pardef,
                          gint id,
                          const gchar *name,
                          const gchar *desc,
                          gdouble minimum,
                          gdouble maximum,
                          gdouble default_value);

Defines a new parameter with floating point values.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

minimum

Minimum allowed value (inclusive).

 

maximum

Maximum allowed value (inclusive).

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_angle ()

void
gwy_param_def_add_angle (GwyParamDef *pardef,
                         gint id,
                         const gchar *name,
                         const gchar *desc,
                         gboolean positive,
                         gint folding,
                         gdouble default_value);

Defines a new parameter with floating point values representing angles.

Percentages do not have to be defined using this function. You can also set up the conversion factor and unit string directly using gwy_param_table_slider_set_factor() and gwy_param_table_set_unitstr() when constructing the parameter table (this happens automatically for percentage parameters). This function may be somewhat more convenient and it also ensures correct folding when loading angle from settings.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

positive

TRUE for positive angles, FALSE for angles symmetrical around zero.

 

folding

Fraction of the range [0,2π] which should be the range.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_percentage ()

void
gwy_param_def_add_percentage (GwyParamDef *pardef,
                              gint id,
                              const gchar *name,
                              const gchar *desc,
                              gdouble default_value);

Defines a new parameter with floating point values representing fraction of some base value.

The value range is [0,1], but it is displayed in percents in the GUI.

Percentages do not have to be defined using this function. You can also set up the conversion factor and unit string directly using gwy_param_table_slider_set_factor() and gwy_param_table_set_unitstr() when constructing the parameter table (this happens automatically for percentage parameters). This function may be somewhat more convenient.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_mask_color ()

void
gwy_param_def_add_mask_color (GwyParamDef *pardef,
                              gint id,
                              const gchar *name,
                              const gchar *desc);

Defines a new mask colour parameter.

This is usually a parameter not stored in settings, but handled specially by taking the mask colour from the image and then setting mask colours on the output. The default value is the default mask colour.

See gwy_param_def_add_color() for a generic colour parameter.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. Usually it is NULL because the colour is taken from data, not settings.

 

desc

Parameter description which will be used for a label in GUI. Usually NULL for the default label.

 

Since: 2.59

gwy_param_def_add_color ()

void
gwy_param_def_add_color (GwyParamDef *pardef,
                         gint id,
                         const gchar *name,
                         const gchar *desc,
                         gboolean has_alpha,
                         GwyRGBA default_value);

Defines a new colour parameter.

See gwy_param_def_add_mask_color() for the mask colour parameter which is handled specially.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. Usually it is NULL because the colour is taken from data, not settings.

 

desc

Parameter description which will be used for a label in GUI. Usually NULL for the default label.

 

has_alpha

TRUE if semi-transparent colours are allowed; FALSE for fully opaque colours.

 

default_value

Default value of the parameter.

 

Since: 2.64

gwy_param_def_add_target_graph ()

void
gwy_param_def_add_target_graph (GwyParamDef *pardef,
                                gint id,
                                const gchar *name,
                                const gchar *desc);

Defines a new parameter with values that are graph ids.

Data identifier parameters are not stored permanently in settings. However, they are remembered until Gwyddion exits. Hence name does not actually refer to settings, but it should still uniquely identify the parameter as in settings.

See the introduction for name and desc lifetime rules.

See gwy_param_def_add_target_graph() for a generic graph parameter.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI. May be NULL for the default label.

 

Since: 2.59

gwy_param_def_add_graph_id ()

void
gwy_param_def_add_graph_id (GwyParamDef *pardef,
                            gint id,
                            const gchar *name,
                            const gchar *desc);

Defines a new parameter with values that are graph ids.

Data identifier parameters are not stored permanently in settings. However, they are remembered until Gwyddion exits. Hence name does not actually refer to settings, but it should still uniquely identify the parameter as in settings.

See the introduction for name and desc lifetime rules.

See gwy_param_def_add_target_graph() for a specialised parameter for target graphs.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

Since: 2.60

gwy_param_def_add_image_id ()

void
gwy_param_def_add_image_id (GwyParamDef *pardef,
                            gint id,
                            const gchar *name,
                            const gchar *desc);

Defines a new parameter with values that are image ids.

Data identifier parameters are not stored permanently in settings. However, they are remembered until Gwyddion exits. Hence name does not actually refer to settings, but it should still uniquely identify the parameter as in settings.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

Since: 2.59

gwy_param_def_add_volume_id ()

void
gwy_param_def_add_volume_id (GwyParamDef *pardef,
                             gint id,
                             const gchar *name,
                             const gchar *desc);

Defines a new parameter with values that are volume data ids.

Data identifier parameters are not stored permanently in settings. However, they are remembered until Gwyddion exits. Hence name does not actually refer to settings, but it should still uniquely identify the parameter as in settings.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

Since: 2.59

gwy_param_def_add_xyz_id ()

void
gwy_param_def_add_xyz_id (GwyParamDef *pardef,
                          gint id,
                          const gchar *name,
                          const gchar *desc);

Defines a new parameter with values that are xyz data ids.

Data identifier parameters are not stored permanently in settings. However, they are remembered until Gwyddion exits. Hence name does not actually refer to settings, but it should still uniquely identify the parameter as in settings.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

Since: 2.59

gwy_param_def_add_curve_map_id ()

void
gwy_param_def_add_curve_map_id (GwyParamDef *pardef,
                                gint id,
                                const gchar *name,
                                const gchar *desc);

Defines a new parameter with values that are curve map data ids.

Data identifier parameters are not stored permanently in settings. However, they are remembered until Gwyddion exits. Hence name does not actually refer to settings, but it should still uniquely identify the parameter as in settings.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

Since: 2.60

gwy_param_def_add_report_type ()

void
gwy_param_def_add_report_type (GwyParamDef *pardef,
                               gint id,
                               const gchar *name,
                               const gchar *desc,
                               GwyResultsExportStyle style,
                               GwyResultsReportType default_value);

Defines a new parameter with values that are report types.

Report type values are neither pure enumerated values nor flags; they are combinations of both. See GwyResultsExport for discussion.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI. The label, if not NULL, will be used for the save dialogue as the export controls carry no label.

 

style

Report style, defining allowed report types. See gwy_results_export_set_style() for description.

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_hold_selection ()

void
gwy_param_def_add_hold_selection (GwyParamDef *pardef,
                                  gint id,
                                  const gchar *name,
                                  const gchar *desc);

Defines a new flags parameter with values that are selection holding flags.

The values are flags from GwyHoldSelectionFlags. The default is zero.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI. Normally pass NULL for the default label.

 

Since: 2.63

gwy_param_def_add_seed ()

void
gwy_param_def_add_seed (GwyParamDef *pardef,
                        gint id,
                        const gchar *name,
                        const gchar *desc);

Defines a new parameter with values that are random seeds.

Random seeds are integers from the range [1,2³¹-1] which can take random values. They are usually accompanied by a boolean parameter controlling whether the value is random or fixed (taken from settings), added afterwards using gwy_param_def_add_randomize().

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI. Normally pass NULL for the default label.

 

Since: 2.59

gwy_param_def_add_string ()

void
gwy_param_def_add_string (GwyParamDef *pardef,
                          gint id,
                          const gchar *name,
                          const gchar *desc,
                          GwyParamStringFlags flags,
                          GwyRectifyStringFunc rectify,
                          const gchar *default_value);

Defines a new parameter with values that are strings.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

flags

Simple treatment of special values. If any are given they are enforced, i.e. they apply both before and after rectify in the case both are given.

 

rectify

Function which takes a string which may or may not be valid parameter value and returns a valid one. Pass NULL if anything goes (or validation is handled otherwise).

 

default_value

Default value of the parameter.

 

Since: 2.59

gwy_param_def_add_unit ()

void
gwy_param_def_add_unit (GwyParamDef *pardef,
                        gint id,
                        const gchar *name,
                        const gchar *desc,
                        const gchar *default_value);

Defines a new parameter with values that are strings representing units.

Units parameters are not enforced to parse to meaningful units. However, they are conceptually different from arbitrary strings and have several special unit-oriented functions.

Units behave as strings with the GWY_PARAM_STRING_EMPTY_IS_NULL flag.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

default_value

Default value of the parameter. NULL is allowed.

 

Since: 2.59

gwy_param_def_add_resource ()

void
gwy_param_def_add_resource (GwyParamDef *pardef,
                            gint id,
                            const gchar *name,
                            const gchar *desc,
                            GwyInventory *inventory,
                            const gchar *default_value);

Defines a new parameter with values that are string resource names.

Use gwy_params_get_string() to get the string name and gwy_params_get_resource() to get the corresponding resource object.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which will be used for a label in GUI.

 

inventory

Inventory holding the resources to choose from.

 

default_value

Default value of the parameter (resource name).

 

Since: 2.59

gwy_param_def_add_grain_groups ()

void
gwy_param_def_add_grain_groups (GwyParamDef *pardef,
                                gint id,
                                const gchar *name,
                                const gchar *desc,
                                guint default_value);

Defines a new flag parameter with values that are bits corresponding to grain value groups.

Such parameter is usually used to represent the set of expanded grain value groups in a tree view.

See the introduction for name and desc lifetime rules.

Parameters

pardef

A set of parameter definitions.

 

id

Parameter identifier.

 

name

Parameter name for settings. It can be NULL for derived parameters not stored in settings.

 

desc

Parameter description which could be used for a label in GUI, but usually NULL.

 

default_value

Default value of the parameter (bits corresponding to grain value groups).

 

Since: 2.61

Types and Values

enum GwyParamStringFlags

Flags that can be used when defining a string parameter.

Members

GWY_PARAM_STRING_EMPTY_IS_NULL

Fold empty string to NULL.

 

GWY_PARAM_STRING_NULL_IS_EMPTY

Ensure strings are non-empty by replacing NULL with an empty string.

 

GWY_PARAM_STRING_DO_NOT_STRIP

Preserve whitespace at the beginning and end of the string.

 

Since: 2.59

struct GwyParamDef

struct GwyParamDef;

Object representing a set of parameter definitions.

The GwyParamDef struct contains no public fields.

Since: 2.59

struct GwyParamDefClass

struct GwyParamDefClass {
    GObjectClass g_object_class;
};

Class of parameter definition sets.

Since: 2.59

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS