Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map
GwyParams — Module parameter value sets
| struct | GwyParams |
| struct | GwyParamsClass |
GObject ╰── GwyParams
#include <app/gwyapp.h>
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.
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().
A new empty parameter value set.
Since: 2.59
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.
params |
A parameter value set. |
|
pardef |
Set of parameter definitions. |
Since: 2.59
GwyParamDef *
gwy_params_get_def (GwyParams *params);
Gets the definitions object for a parameter set.
params |
A parameter value set. |
The set of parameter definitions.
Since: 2.59
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.
pardef |
Set of parameter definitions. |
A new parameter value set.
Since: 2.59
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().
params |
A set of parameter values. |
Since: 2.59
GwyParams *
gwy_params_duplicate (GwyParams *params);
Creates a duplicate of a set of parameter values.
params |
A set of parameter values. |
A new empty parameter value set.
Since: 2.59
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.
params |
A set of parameter values. |
|
source |
A set of parameter values. |
Since: 2.62
void
gwy_params_save_to_settings (GwyParams *params);
Saves a parameter value set to settings.
The associated definitions must have function name set.
params |
A parameter value set. |
Since: 2.59
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.
params |
A parameter value set. |
|
prefix |
The prefix (leading path component) limiting parameters to reset. Pass empty string or |
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The boolean parameter value.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The enum parameter value.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
|
mask |
Pointer to mask data field to update (can also be |
The masking enum parameter value.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The fags parameter value.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
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 if parameter value has changed.
Since: 2.59
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().
params |
A parameter value set. |
|
id |
Parameter identifier. |
The report type parameter value.
Since: 2.59
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().
params |
A parameter value set. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The integer parameter value.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The floating point parameter value.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
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
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
power10 |
Location where to store the power of 10 (or |
An SI unit, owned by params
. It must not be modified nor freed.
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
The resource object corresponding to the parameter value. A default value is returned if the resource does not exist.
Since: 2.61
GwyRGBA gwy_params_get_color (GwyParams *params,gint id);
Gets the value of a colour parameter.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
The colour parameter value.
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The data identifier parameter value.
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
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
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The image data field, or NULL if the parameter is none (or the image no longer exists).
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The mask data field, or NULL if the parameter is none (or the image no longer exists).
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The graph model of the graph, or NULL if the parameter is none (or the graph no longer exists).
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The volume data brick, or NULL if the parameter is none (or the volume data no longer exist).
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The xyz data surface, or NULL if the parameter is none (or the xyz data no longer exist).
Since: 2.59
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.
params |
A parameter value set. |
|
id |
Parameter identifier. |
The curve map data lawn, or NULL if the parameter is none (or the curve map data no longer exist).
Since: 2.60
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.59
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set. |
TRUE if parameter value has changed.
Since: 2.60
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
|
value |
Value to set (a non-negative integer or -1). |
TRUE if parameter value has changed.
Since: 2.60
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.
params |
A set of parameter values. |
|
id |
Parameter identifier. |
The new random seed value (for convenience).
Since: 2.59
struct GwyParams;
Object representing a set of parameter values.
The GwyParams struct contains no public fields.
Since: 2.59
struct GwyParamsClass {
GObjectClass parent;
};
Class of parameter value sets.
Since: 2.59