GwyParamDef: Gwyddion Application Library Reference Manual

## 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_enum_subset ()
void | gwy_param_def_add_basic_merge ()
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_scatter_data ()
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_spectra_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_cmap_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 <libgwyapp/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_image_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.

### 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.

### 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_image_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`. |

### 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`).

### 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.

### 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.

### 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. |

### 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. |

### 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. |

### gwy_param_def_add_enum_subset()

    void
    gwy_param_def_add_enum_subset (GwyParamDef *pardef,
                                   gint id,
                                   const gchar *name,
                                   const gchar *desc,
                                   GType enum_gtype,
                                   const gint *values,
                                   guint nvalues,
                                   gint default_value);

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

This function is useful when the function uses a standard enum, but not all values make sense or are supported. The values in `values` must exist in the standard enum and not repeat. See `gwy_param_def_add_enum()` for supported enums.

A typical example is GwyMergeType, where a number of operations exists mainly for completeness and usually it is not useful to offer them to the user. This specific case is so common that a helper `gwy_param_def_add_basic_merge()` exists to avoid repetition.

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`. |
values | Array with enum values to select from the standard enum. |
nvalues | The number of values in `values` . |
default_value | Default value of the parameter. |

### gwy_param_def_add_basic_merge()

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

Defines a new parameter with enumerated values being the basic grain merge types.

This helper defines an enum parameter with contains the three most useful classic operations `GWY_MERGE_UNION`, `GWY_MERGE_INTERSECTION` and possibly `GWY_MERGE_SUBTRACT` from GwyMergeType. The default value must be one of these three.

Note that the user usually considers the existing mask as the first operand and the created mask the second operand; the module code tends to have them logically reversed. For the two symmetrical operations there is no difference. Subtraction may need to be chaned to `GWY_MERGE_REVSUBTRACT` when actually calling `gwy_nield_merge()`.

If you need a different subset of operations, you can use `gwy_param_def_add_enum_subset()` directly to define it. However, the less useful merge types may not have any icon associated.

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. May be `NULL` for the default label. |
only_setwise | `TRUE` to only include operations which makes sense for a set of masks, i.e. commutative and associative. `FALSE` to include subtraction, which only makes sense for an ordered pair of masks. |
default_value | Default value of the parameter. |

### 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. |

### 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. |

### 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. |

### 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.

The parameter can be set with `gwy_params_set_curve()`.

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. |

### gwy_param_def_add_scatter_data()

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

Defines a new parameter with values that are scattered data value indices.

The parameter can be set with `gwy_params_set_curve()` (it is really more like a plane index, not a curve index, but it is still analogous to volume data curves).

Value indices can be any non-negative integers. The upper bound is determined by GwyParamTable once the GUI for choosing a value from specific scattered data is set up. Value -1 is also allowed for empty scattered data with no values.

Value index parameters are stored in settings as value labels, even though they are treated integers otherwise. This helps selecting a value with the same function/interpretation the next time the module is invoked – or the first value 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. |

### 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`. |

### 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. |

### 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. |

### 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. |

### 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. |

### 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. |

### 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. |

### 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. |

### 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. |

### 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. |

### 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. |

### gwy_param_def_add_spectra_id()

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

Defines a new parameter with values that are spectra 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. |

### 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. |

### 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. |

### 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. |

### gwy_param_def_add_cmap_id()

    void
    gwy_param_def_add_cmap_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. |

### 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. |

### 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. |

### 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. |

### 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. |

### 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. |

### 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). |

### 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). |

## 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. |

### struct GwyParamDef

    struct GwyParamDef;

Object representing a set of parameter definitions.

The GwyParamDef struct contains no public fields.

### struct GwyParamDefClass

    struct GwyParamDefClass {
        GObjectClass g_object_class;
    };

Class of parameter definition sets.