## GwyParams GwyParams — Module parameter value sets |

## Functions

GwyParams * | gwy_params_new ()
void | gwy_params_set_def ()
GwyParamDef * | gwy_params_get_def ()
GwyParams * | gwy_params_new_from_settings ()
void | gwy_params_load_from_settings ()
GwyParams * | gwy_params_duplicate ()
void | gwy_params_save_to_settings ()
void | gwy_params_reset_all ()
gboolean | gwy_params_reset ()
gboolean | gwy_params_get_boolean ()
gboolean | gwy_params_set_boolean ()
gint | gwy_params_get_enum ()
GwyMaskingType | gwy_params_get_masking ()
gboolean | gwy_params_set_enum ()
guint | gwy_params_get_flags ()
gboolean | gwy_params_set_flags ()
gboolean | gwy_params_set_flag ()
GwyResultsReportType | gwy_params_get_report_type ()
gboolean | gwy_params_set_report_type ()
gint | gwy_params_get_int ()
gboolean | gwy_params_set_int ()
gdouble | gwy_params_get_double ()
gboolean | gwy_params_set_double ()
const gchar * | gwy_params_get_string ()
gboolean | gwy_params_set_string ()
gboolean | gwy_params_set_unit ()
GwySIUnit * | gwy_params_get_unit ()
gboolean | gwy_params_set_resource ()
GwyResource * | gwy_params_get_resource ()
GwyRGBA | gwy_params_get_color ()
gboolean | gwy_params_set_color ()
GwyAppDataId | gwy_params_get_data_id ()
gboolean | gwy_params_data_id_is_none ()
GwyDataField * | gwy_params_get_image ()
GwyDataField * | gwy_params_get_mask ()
GwyGraphModel * | gwy_params_get_graph ()
GwyBrick * | gwy_params_get_volume ()
GwySurface * | gwy_params_get_xyz ()
GwyLawn * | gwy_params_get_curve_map ()
gboolean | gwy_params_set_image_id ()
gboolean | gwy_params_set_graph_id ()
gboolean | gwy_params_set_volume_id ()
gboolean | gwy_params_set_xyz_id ()
gboolean | gwy_params_set_curve_map_id ()
gboolean | gwy_params_set_curve ()
gint | gwy_params_randomize_seed ()

## Types and Values

struct | GwyParams
struct | GwyParamsClass

## Object Hierarchy

        GObject
        ╰── GwyParams

## Includes

    #include <app/gwyapp.h>

## Description

GwyParams represents a set of module parameter values. Usually it is created by loading the values from settings using `gwy_params_new_from_settings()`. It can also be created as empty – it is necessary to tie it to a definition set using `gwy_params_set_def()` then. In any case, the tie to the definitions is permanent. If you need parameter value set for different definitions create a new object.

GwyParams is a “dumb” object, replacing a plain C struct holding the parameter values. Beside making sure parameter values stay in defined ranges, it does not do much. In particular it does not emit any singals.

Each parameter type has its own getters and setters, such as `gwy_params_get_boolean()` and `gwy_params_set_boolean()`. For a few parameter types there may also be dedicated helper functions such as `gwy_params_get_masking()` which encapsulate common logic when dealing with these parameter.

The setters and reset functions should be seldom needed. When running module GUI, parameter values should be set by GwyParamTable functions to ensure the updates cascade as expected. GwyParamTable also has a reset function. Setters do not cause any GUI response and, hence, has no place in most modules as they would lead to an inconsistent state. Sometimes, however, setting parameter values directly can be useful in non-GUI paths which perform extra validation or ensure complex invariants.

## Functions

### gwy_params_new ()

    GwyParams *
    gwy_params_new (void);

Creates a new empty parameter value set.

The created object is empty (and useless) until parameter definitions are set with `gwy_params_set_def()`. However, in modules the parameters are normally instantiated using `gwy_params_new_from_settings()`.

#### Returns

A new empty parameter value set.

Since: 2.59

### gwy_params_set_def ()

    void
    gwy_params_set_def (GwyParams *params,
                        GwyParamDef *pardef);

Sets the definitions of parameters a GwyParams should use.

Once set, the definitions are fixed. One GwyParams object cannot be used with multiple definitions.

#### Parameters

params | A parameter value set. |
pardef | Set of parameter definitions. |

Since: 2.59

### gwy_params_get_def ()

    GwyParamDef *
    gwy_params_get_def (GwyParams *params);

Gets the definitions object for a parameter set.

#### Parameters

params | A parameter value set. |

#### Returns

The set of parameter definitions.

Since: 2.59

### gwy_params_new_from_settings ()

    GwyParams *
    gwy_params_new_from_settings (GwyParamDef *pardef);

Creates a new parameter value set with given definition and loads values from settings.

The definitions `pardef` must have function name set.

#### Parameters

pardef | Set of parameter definitions. |

#### Returns

A new parameter value set.

Since: 2.59

### gwy_params_load_from_settings ()

    void
    gwy_params_load_from_settings (GwyParams *params);

Loads a parameter value set from settings.

The corresponding definitions must have function name set. It is usually more convenient to create and load the parameters at the same time using `gwy_params_new_from_settings()`.

#### Parameters

params | A set of parameter values. |

Since: 2.59

### gwy_params_duplicate ()

    GwyParams *
    gwy_params_duplicate (GwyParams *params);

Creates a duplicate of a set of parameter values.

#### Parameters

params | A set of parameter values. |

#### Returns

A new empty parameter value set.

Since: 2.59

### gwy_params_save_to_settings ()

    void
    gwy_params_save_to_settings (GwyParams *params);

Saves a parameter value set to settings.

The associated definitions must have function name set.

#### Parameters

params | A parameter value set. |

Since: 2.59

### gwy_params_reset_all ()

    void
    gwy_params_reset_all (GwyParams *params,
                          const gchar *prefix);

Resets all parameters in a parameter value set to default values.

This function is seldom needed. See the introduction for discussion.

#### Parameters

params | A parameter value set. |
prefix | The prefix (leading path component) limiting parameters to reset. Pass empty string or `NULL` to reset all parameters. |

Since: 2.59

### gwy_params_reset ()

    gboolean
    gwy_params_reset (GwyParams *params,
                      gint id);

Resets a single parameter in a parameter value set to the default value.

This function is seldom needed. See the introduction for discussion.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_boolean ()

    gboolean
    gwy_params_get_boolean (GwyParams *params,
                            gint id);

Gets the value of a boolean parameter.

This function can be used with any boolean-valued parameter, even if it is more complex/specific than a plain boolean.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The boolean parameter value.

Since: 2.59

### gwy_params_set_boolean ()

    gboolean
    gwy_params_set_boolean (GwyParams *params,
                            gint id,
                            gboolean value);

Sets the value of a plain boolean parameter.

This function is seldom needed. See the introduction for discussion.

This function can only be used with plain boolean parameters defined by `gwy_param_def_add_boolean()`. More complex/specific parameters need to be set using dedicated setters.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_enum ()

    gint
    gwy_params_get_enum (GwyParams *params,
                         gint id);

Gets the value of a enum parameter.

This function can be used with any enum-valued parameter, even if it is more complex/specific than a plain enum.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The enum parameter value.

Since: 2.59

### gwy_params_get_masking ()

    GwyMaskingType
    gwy_params_get_masking (GwyParams *params,
                            gint id,
                            GwyDataField **mask);

Gets the value of a masking type enum parameter, consistently with a mask field.

If `mask` is `NULL` the returned value is simply the parameter value.

If `mask` is a pointer then `mask` and the return value can be modified. The function will set `mask` to `NULL` if masking is `GWY_MASK_IGNORE`. Conversely, it will return `GWY_MASK_IGNORE` if `mask` is a pointer to `NULL` data field. In short, if a `mask` argument is passed a non-ignore masking mode is guaranteed to coincide with non-`NULL` mask.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
mask | Pointer to mask data field to update (can also be `NULL`). |

#### Returns

The masking enum parameter value.

Since: 2.59

### gwy_params_set_enum ()

    gboolean
    gwy_params_set_enum (GwyParams *params,
                         gint id,
                         gint value);

Sets the value of a generic enum parameter.

This function is seldom needed. See the introduction for discussion.

This function can only be used with plain enum parameters defined by `gwy_param_def_add_gwyenum()` or `gwy_param_def_add_enum()`. More complex/specific parameters need to be set using dedicated setters.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_flags ()

    guint
    gwy_params_get_flags (GwyParams *params,
                          gint id);

Gets the value of a flags parameter.

This function can be used with any flags-valued parameter, even if it is more complex/specific than a plain flag set.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The fags parameter value.

Since: 2.59

### gwy_params_set_flags ()

    gboolean
    gwy_params_set_flags (GwyParams *params,
                          gint id,
                          guint value);

Sets the value of a generic flags parameter.

This function is seldom needed. See the introduction for discussion.

This function can only be used with plain flags parameters defined by `gwy_param_def_add_gwyflags()`. More complex/specific parameters need to be set using dedicated setters.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_set_flag ()

    gboolean
    gwy_params_set_flag (GwyParams *params,
                         gint id,
                         guint flag,
                         gboolean value);

Modifies the value of a generic flags parameter.

This function is seldom needed. See the introduction for discussion.

This function can only be used with plain flags parameters defined by `gwy_param_def_add_gwyflags()`. More complex/specific parameters need to be set using dedicated setters.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
flag | The flag bit to set or unset (it can be actually a flag combination). |
value | `TRUE` to set the flag, `FALSE` to unset the flag. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_report_type ()

    GwyResultsReportType
    gwy_params_get_report_type (GwyParams *params,
                                gint id);

Gets the value of a report type parameter.

This function can only be used with a parameter defined by `gwy_param_def_add_report_type()`.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The report type parameter value.

Since: 2.59

### gwy_params_set_report_type ()

    gboolean
    gwy_params_set_report_type (GwyParams *params,
                                gint id,
                                GwyResultsReportType value);

Sets the value of a report type parameter.

This function is seldom needed. See the introduction for discussion.

This function can only be used with parameters defined by `gwy_param_def_add_report_type()`.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_int ()

    gint
    gwy_params_get_int (GwyParams *params,
                        gint id);

Gets the value of a plain integer parameter.

This function can be used with any integer-valued parameter, even if it is more complex/specific than a plain integer.

It can also be used to get a random seed parameter value. The seed value does not change between calls unless `gwy_params_randomize_seed()` has been called.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The integer parameter value.

Since: 2.59

### gwy_params_set_int ()

    gboolean
    gwy_params_set_int (GwyParams *params,
                        gint id,
                        gint value);

Sets the value of a integer parameter.

This function is seldom needed. See the introduction for discussion.

This function can only be used with plain integer parameters defined by `gwy_param_def_add_int()` and random seeds created with `gwy_param_def_add_seed()`. More complex/specific parameters need to be set using dedicated setters.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_double ()

    gdouble
    gwy_params_get_double (GwyParams *params,
                           gint id);

Gets the value of a floating point parameter.

This function can be used with any double-valued parameter, even if it is more complex/specific than a plain double.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The floating point parameter value.

Since: 2.59

### gwy_params_set_double ()

    gboolean
    gwy_params_set_double (GwyParams *params,
                           gint id,
                           gdouble value);

Sets the value of a plain floating point parameter.

This function is seldom needed. See the introduction for discussion.

This function can only be used with plain floating point parameters defined by `gwy_param_def_add_double()` and simple transformed parameters such as `gwy_param_def_add_angle()` or `gwy_param_def_add_percentage()`. More complex/specific parameters need to be set using dedicated setters.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_string ()

    const gchar *
    gwy_params_get_string (GwyParams *params,
                           gint id);

Gets the value of a string parameter.

This function can be used with any string-valued parameter (for instance units and resource names), even if it is more complex/specific than a plain string.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The string parameter value. It is owned by `params` and it is only guaranteed to be valid until the parameter change (or the object is destroyed).

Since: 2.59

### gwy_params_set_string ()

    gboolean
    gwy_params_set_string (GwyParams *params,
                           gint id,
                           const gchar *value);

Sets the value of a string parameter.

This function is seldom needed. See the introduction for discussion.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_set_unit ()

    gboolean
    gwy_params_set_unit (GwyParams *params,
                         gint id,
                         const gchar *value);

Sets the value of a unit parameter.

This function is seldom needed. See the introduction for discussion.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_unit ()

    GwySIUnit *
    gwy_params_get_unit (GwyParams *params,
                         gint id,
                         gint *power10);

Gets an SI unit object for a unit parameter.

Use `gwy_params_get_string()` if you simply want the unit string.

The returned object is not guaranteed to be updated automatically when the parameter changes. It must not be assumed it will persist past the destruction of `params` . Briefly, do not keep it around.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
power10 | Location where to store the power of 10 (or `NULL`). |

#### Returns

An SI unit, owned by `params` . It must not be modified nor freed.

Since: 2.59

### gwy_params_set_resource ()

    gboolean
    gwy_params_set_resource (GwyParams *params,
                             gint id,
                             const gchar *value);

Sets the value of a resource name parameter.

This function is seldom needed. See the introduction for discussion.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_resource ()

    GwyResource *
    gwy_params_get_resource (GwyParams *params,
                             gint id);

Gets the resource object of a resource name parameter.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |

#### Returns

The resource object corresponding to the parameter value. A default value is returned if the resource does not exist.

Since: 2.61

### gwy_params_get_color ()

    GwyRGBA
    gwy_params_get_color (GwyParams *params,
                          gint id);

Gets the value of a colour parameter.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |

#### Returns

The colour parameter value.

Since: 2.59

### gwy_params_set_color ()

    gboolean
    gwy_params_set_color (GwyParams *params,
                          gint id,
                          GwyRGBA value);

Sets the value of a colour parameter.

This function is seldom needed. See the introduction for discussion.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_get_data_id ()

    GwyAppDataId
    gwy_params_get_data_id (GwyParams *params,
                            gint id);

Gets the value of a data identifier parameter.

This function can be used with any specific identifier-valued parameter, even though they have dedicated creators and setters.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The data identifier parameter value.

Since: 2.59

### gwy_params_data_id_is_none ()

    gboolean
    gwy_params_data_id_is_none (GwyParams *params,
                                gint id);

Checks if data identifier parameter is set to no-data.

This convenience function can be used with any specific identifier-valued parameter.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

`TRUE` if the data identifier parameter is no-data and `gwy_params_get_data_id()` would return `GWY_APP_DATA_ID_NONE`; `FALSE` otherwise if some real data object is selected.

Since: 2.59

### gwy_params_get_image ()

    GwyDataField *
    gwy_params_get_image (GwyParams *params,
                          gint id);

Gets the data field object for an image identifier parameter.

This is a more convenient alternative to `gwy_params_get_data_id()` since it fetches and checks the object.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The image data field, or `NULL` if the parameter is none (or the image no longer exists).

Since: 2.59

### gwy_params_get_mask ()

    GwyDataField *
    gwy_params_get_mask (GwyParams *params,
                         gint id);

Gets the data field object for an mask identifier parameter.

This is a more convenient alternative to `gwy_params_get_data_id()` since it fetches and checks the object.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The mask data field, or `NULL` if the parameter is none (or the image no longer exists).

Since: 2.59

### gwy_params_get_graph ()

    GwyGraphModel *
    gwy_params_get_graph (GwyParams *params,
                          gint id);

Gets the graph model object for a graph identifier parameter.

This is a more convenient alternative to `gwy_params_get_data_id()` since it fetches and checks the object.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The graph model of the graph, or `NULL` if the parameter is none (or the graph no longer exists).

Since: 2.59

### gwy_params_get_volume ()

    GwyBrick *
    gwy_params_get_volume (GwyParams *params,
                           gint id);

Gets the brick object for a volume data identifier parameter.

This is a more convenient alternative to `gwy_params_get_data_id()` since it fetches and checks the object.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The volume data brick, or `NULL` if the parameter is none (or the volume data no longer exist).

Since: 2.59

### gwy_params_get_xyz ()

    GwySurface *
    gwy_params_get_xyz (GwyParams *params,
                        gint id);

Gets the surface object for a xyz data identifier parameter.

This is a more convenient alternative to `gwy_params_get_data_id()` since it fetches and checks the object.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The xyz data surface, or `NULL` if the parameter is none (or the xyz data no longer exist).

Since: 2.59

### gwy_params_get_curve_map ()

    GwyLawn *
    gwy_params_get_curve_map (GwyParams *params,
                              gint id);

Gets the lawn object for a curve map data identifier parameter.

This is a more convenient alternative to `gwy_params_get_data_id()` since it fetches and checks the object.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |

#### Returns

The curve map data lawn, or `NULL` if the parameter is none (or the curve map data no longer exist).

Since: 2.60

### gwy_params_set_image_id ()

    gboolean
    gwy_params_set_image_id (GwyParams *params,
                             gint id,
                             GwyAppDataId value);

Sets the value of an image identifier parameter.

This function is seldom needed. See the introduction for discussion.

If `value` is not `GWY_APP_DATA_ID_NONE` then the image identified by `value` must currently exist.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_set_graph_id ()

    gboolean
    gwy_params_set_graph_id (GwyParams *params,
                             gint id,
                             GwyAppDataId value);

Sets the value of a graph identifier parameter.

This function is seldom needed. See the introduction for discussion.

If `value` is not `GWY_APP_DATA_ID_NONE` then the graph identified by `value` must currently exist.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_set_volume_id ()

    gboolean
    gwy_params_set_volume_id (GwyParams *params,
                              gint id,
                              GwyAppDataId value);

Sets the value of a volume data identifier parameter.

If `value` is not `GWY_APP_DATA_ID_NONE` then the volume data identified by `value` must currently exist.

This function is seldom needed. See the introduction for discussion.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

Since: 2.59

### gwy_params_set_xyz_id ()

    gboolean
    gwy_params_set_xyz_id (GwyParams *params,
                           gint id,
                           GwyAppDataId value);

Sets the value of an xyz data identifier parameter.

This function is seldom needed. See the introduction for discussion.

If `value` is not `GWY_APP_DATA_ID_NONE` then the XYZ data identified by `value` must currently exist.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.59

### gwy_params_set_curve_map_id ()

    gboolean
    gwy_params_set_curve_map_id (GwyParams *params,
                                 gint id,
                                 GwyAppDataId value);

Sets the value of a curve map data identifier parameter.

This function is seldom needed. See the introduction for discussion.

If `value` is not `GWY_APP_DATA_ID_NONE` then the curve map data identified by `value` must currently exist.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set. |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.60

### gwy_params_set_curve ()

    gboolean
    gwy_params_set_curve (GwyParams *params,
                          gint id,
                          gint value);

Sets the value of a graph or lawn curve number parameter.

This function is seldom needed. See the introduction for discussion.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |
value | Value to set (a non-negative integer or -1). |

#### Returns

`TRUE` if parameter value has changed.

Since: 2.60

### gwy_params_randomize_seed ()

    gint
    gwy_params_randomize_seed (GwyParams *params,
                               gint id);

Randomizes the value of a random seed parameter.

You can use `gwy_params_get_int()` any number of times afterwards and obtain the same value.

This function is seldom needed. See the introduction for discussion. In the usual setup the seed is randomised when loaded from settings if the controlling randomization boolean is `TRUE`. Furthermore, GwyParamTable knows to randomize the seed when the randomization button is pressed.

#### Parameters

params | A set of parameter values. |
id | Parameter identifier. |

#### Returns

The new random seed value (for convenience).

Since: 2.59

## Types and Values

### struct GwyParams

    struct GwyParams;

Object representing a set of parameter values.

The GwyParams struct contains no public fields.

Since: 2.59

### struct GwyParamsClass

    struct GwyParamsClass {
        GObjectClass parent;
    };

Class of parameter value sets.

Since: 2.59