GwyParamDef (HEAD)

GwyParamDef — Module parameter definitions

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── GwyParamDef

Includes

#include <app/gwyapp.h>

Description

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

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

1
2
3
4
5

enum {
    PARAM_DEGREE,
    PARAM_MASKING,
    PARAM_UPDATE,
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

static GwyParamDef*
define_module_params()
{
    static GwyParamDef *paramdef = NULL;

    if (paramdef)
        return paramdef;

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

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

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

Functions

GwyRectifyStringFunc ()

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

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

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

Parameters

Returns

Newly allocated string, presumably corrected.

Since: 2.59

gwy_param_def_new ()

GwyParamDef *
gwy_param_def_new (void);

Creates a new empty set of parameter definitions.

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

Returns

A newly create paramete definition set.

Since: 2.59

gwy_param_def_set_function_name ()

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

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

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

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

Parameters

Since: 2.59

gwy_param_def_get_function_name ()

const gchar *
gwy_param_def_get_function_name (GwyParamDef *pardef);

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

Parameters

Returns

The functions name (possibly NULL).

Since: 2.59

gwy_param_def_get_param_name ()

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

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

See gwy_param_def_get_param_label() for parameter labels.

Parameters

Returns

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

Since: 2.62

gwy_param_def_get_param_label ()

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

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

See gwy_param_def_get_param_name() for parameter names (keys).

Parameters

Returns

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

Since: 2.62

gwy_param_def_add_gwyenum ()

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

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

See the introduction for name and desc lifetime rules.

See gwy_param_def_add_enum() for predefined enums.

Parameters

Since: 2.59

gwy_param_def_add_gwyflags ()

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_enum ()

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

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

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

See the introduction for name and desc lifetime rules.

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

Parameters

Since: 2.59

gwy_param_def_add_int ()

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

Defines a new parameter with integer values.

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_graph_curve ()

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

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.60

gwy_param_def_add_lawn_curve ()

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

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.60

gwy_param_def_add_lawn_segment ()

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

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.60

gwy_param_def_add_active_page ()

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_boolean ()

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

Defines a new parameter with boolean values.

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_instant_updates ()

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

Defines a new boolean parameter representing the instant updates option.

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_randomize ()

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

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

See gwy_param_def_add_seed() for random seed parameters.

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_double ()

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

Defines a new parameter with floating point values.

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_angle ()

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

Defines a new parameter with floating point values representing angles.

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_percentage ()

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

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_mask_color ()

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

Defines a new mask colour parameter.

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

See gwy_param_def_add_color() for a generic colour parameter.

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_color ()

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

Defines a new colour parameter.

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.64

gwy_param_def_add_target_graph ()

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

Defines a new parameter with values that are graph ids.

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

See the introduction for name and desc lifetime rules.

See gwy_param_def_add_target_graph() for a generic graph parameter.

Parameters

Since: 2.59

gwy_param_def_add_graph_id ()

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

Defines a new parameter with values that are graph ids.

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

See the introduction for name and desc lifetime rules.

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

Parameters

Since: 2.60

gwy_param_def_add_image_id ()

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

Defines a new parameter with values that are image ids.

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_volume_id ()

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_xyz_id ()

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_curve_map_id ()

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.60

gwy_param_def_add_report_type ()

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

Defines a new parameter with values that are report types.

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_hold_selection ()

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

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

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

Parameters

Since: 2.63

gwy_param_def_add_seed ()

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

Defines a new parameter with values that are random seeds.

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_string ()

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

Defines a new parameter with values that are strings.

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_unit ()

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

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

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

Units behave as strings with the GWY_PARAM_STRING_EMPTY_IS_NULL flag.

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_resource ()

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.59

gwy_param_def_add_grain_groups ()

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

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

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

See the introduction for name and desc lifetime rules.

Parameters

Since: 2.61

Types and Values

enum GwyParamStringFlags

Flags that can be used when defining a string parameter.

Members

Since: 2.59

struct GwyParamDef

struct GwyParamDef;

Object representing a set of parameter definitions.

The GwyParamDef struct contains no public fields.

Since: 2.59

struct GwyParamDefClass

struct GwyParamDefClass {
    GObjectClass g_object_class;
};

Class of parameter definition sets.

Since: 2.59