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

GwyParams (HEAD)

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_assign ()
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_assign ()

void
gwy_params_assign (GwyParams *params,
                   GwyParams *source);

Assigns values to a set of parameter values from another one.

The parameter sets must have compatible definitions. Usually, the GwyParamDef of source is the same as the one of params , a subset, or a superset. In other words, parameters existing only in one objects are ignored. Usually a GwyParamDef superset is created by defining one parameter set, then defining another one exactly the same way and adding a few more parameters.

Parameters are identified by id. Both parameter ids and names must match. However, a NULL name is considered to match any name – if the ids are equal. Of course, parameter types must also match.

Parameters

params	A set of parameter values.
source	A set of parameter values.

Since: 2.62

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.

Use gwy_params_get_string() to get the resource name instead of the object.

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