GwyParamTable: Gwyddion Application Library Reference Manual

## GwyParamTable GwyParamTable — User interface for parameter sets |

## Functions

GtkWidget * | (*GwyCreateWidgetFunc) ()
gchar * | (*GwyCreateTextFunc) ()
gboolean | (*GwyEnumFilterFunc) ()
GwyParamTable * | gwy_param_table_new ()
GwyParams * | gwy_param_table_params ()
GtkWidget * | gwy_param_table_widget ()
void | gwy_param_table_reset ()
void | gwy_param_table_set_from_params ()
gboolean | gwy_param_table_exists ()
void | gwy_param_table_param_changed ()
void | gwy_param_table_set_no_reset ()
void | gwy_param_table_set_no_resetv ()
void | gwy_param_table_set_sensitive ()
void | gwy_param_table_set_label ()
void | gwy_param_table_set_boolean ()
void | gwy_param_table_set_int ()
void | gwy_param_table_set_double ()
void | gwy_param_table_set_enum ()
void | gwy_param_table_set_flags ()
void | gwy_param_table_set_string ()
void | gwy_param_table_set_data_id ()
void | gwy_param_table_set_curve ()
void | gwy_param_table_append_header ()
void | gwy_param_table_append_separator ()
void | gwy_param_table_set_unitstr ()
void | gwy_param_table_append_checkbox ()
void | gwy_param_table_add_enabler ()
void | gwy_param_table_append_combo ()
void | gwy_param_table_combo_set_filter ()
void | gwy_param_table_combo_refilter ()
void | gwy_param_table_append_radio ()
void | gwy_param_table_append_radio_header ()
void | gwy_param_table_append_radio_item ()
void | gwy_param_table_append_radio_row ()
void | gwy_param_table_append_radio_buttons ()
void | gwy_param_table_radio_set_sensitive ()
void | gwy_param_table_append_checkboxes ()
void | gwy_param_table_checkboxes_set_sensitive ()
void | gwy_param_table_append_checkbox_row ()
void | gwy_param_table_append_graph_id ()
void | gwy_param_table_append_spectra_id ()
void | gwy_param_table_append_image_id ()
void | gwy_param_table_append_volume_id ()
void | gwy_param_table_append_xyz_id ()
void | gwy_param_table_append_cmap_id ()
void | gwy_param_table_append_target_graph ()
void | gwy_param_table_append_graph_curve ()
void | gwy_param_table_graph_curve_set_model ()
void | gwy_param_table_graph_curve_refresh ()
void | gwy_param_table_append_lawn_curve ()
void | gwy_param_table_lawn_curve_set_model ()
void | gwy_param_table_lawn_curve_refresh ()
void | gwy_param_table_append_lawn_segment ()
void | gwy_param_table_append_scatter_data ()
void | gwy_param_table_scatter_data_set_model ()
void | gwy_param_table_scatter_data_refresh ()
void | gwy_param_table_data_id_set_filter ()
void | gwy_param_table_data_id_refilter ()
void | gwy_param_table_append_slider ()
void | gwy_param_table_slider_set_mapping ()
void | gwy_param_table_slider_set_steps ()
void | gwy_param_table_slider_set_digits ()
void | gwy_param_table_slider_set_snapping ()
void | gwy_param_table_slider_restrict_range ()
void | gwy_param_table_slider_set_transform ()
void | gwy_param_table_slider_set_factor ()
void | gwy_param_table_slider_add_alt ()
void | gwy_param_table_alt_set_field_pixel_x ()
void | gwy_param_table_alt_set_field_pixel_y ()
void | gwy_param_table_alt_set_brick_pixel_x ()
void | gwy_param_table_alt_set_brick_pixel_y ()
void | gwy_param_table_alt_set_brick_pixel_z ()
void | gwy_param_table_alt_set_lawn_pixel_x ()
void | gwy_param_table_alt_set_lawn_pixel_y ()
void | gwy_param_table_alt_set_field_frac_z ()
void | gwy_param_table_alt_set_linear ()
void | gwy_param_table_alt_set_calibration ()
void | gwy_param_table_append_entry ()
void | gwy_param_table_entry_set_width ()
void | gwy_param_table_entry_set_value_format ()
void | gwy_param_table_entry_set_instant_changes ()
void | gwy_param_table_append_range ()
void | gwy_param_table_append_unit_chooser ()
void | gwy_param_table_append_color ()
void | gwy_param_table_color_add_preset ()
void | gwy_param_table_append_image_mask_color ()
void | gwy_param_table_append_button ()
void | gwy_param_table_button_set_icon ()
void | gwy_param_table_append_info ()
void | gwy_param_table_append_results ()
void | gwy_param_table_append_resultsv ()
void | gwy_param_table_results_fill ()
void | gwy_param_table_results_clear ()
void | gwy_param_table_append_report ()
void | gwy_param_table_report_set_results ()
void | gwy_param_table_report_set_formatter ()
void | gwy_param_table_append_hold_selection ()
void | gwy_param_table_append_seed ()
void | gwy_param_table_append_message ()
void | gwy_param_table_info_set_valuestr ()
void | gwy_param_table_info_set_add_punctuation ()
void | gwy_param_table_message_set_type ()
void | gwy_param_table_append_foreign ()

## Signals

void | param-changed | Run First

## Types and Values

struct | GwyParamTable
struct | GwyParamTableClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GwyParamTable

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

GwyParamTable manages the user interface for module parameters. It is not a GtkWidget itself, but it can create widgets. Most of what is needed for the parameter controls is already contained in GwyParamDef. Therefore, the corresponding user interface can be as simple as:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    GwyParamTable *table = gwy_param_table_new(params);

    gwy_param_table_append_header(table, -1, _("Detection"));
    gwy_param_table_append_combo(table, PARAM_METHOD);
    gwy_param_table_append_slider(table, PARAM_DEGREE);
    gwy_param_table_append_checkbox(table, PARAM_ADAPTIVE);

    gwy_param_table_append_header(table, -1, _("Output"));
    gwy_param_table_append_checkbox(table, PARAM_EXTRACT_BACKGROUND);
    gwy_param_table_append_checkbox(table, PARAM_CREATE_MASK);

    gwy_dialog_add_content(dialog, gwy_param_table_widget(table), FALSE, FALSE, 0);

After creating the table, you append the various elements in the order in which they should appear in the user interface. Function `gwy_param_table_widget()` then creates the widget for the entire parameter table, which can be packed to the dialog. Note that the created widget type is unspecified. It may be GtkTable, GtkGrid or something else.

GwyParamTable updates parameter values in GwyParams when the user changes something. Therefore, when there is no preview and no relations between parameters to manage, no further setup is necessary. If you need to respond to parameter changes, connect to the “param-changed” signal.

If you change parameters in response to the user changing other parameters, always use the GwyParamTable functions such as `gwy_param_table_set_boolean()` or `gwy_param_table_set_enum()`. This ensures the controls are updated accordingly. Functions such as `gwy_params_set_boolean()` or `gwy_params_set_enum()` would only change the value but not the user interface.

When you add GwyParamTable's widget to a GwyDialog, it consumes the table's floating reference with `g_object_ref_sink()`, provided it has any. Usually, this is convenient because you only do this once and it causes the table to be destroyed when the dialog is destroyed. If you want to keep the table around and/or create its widget multiple times, consume the floating reference yourself with `g_object_ref_sink()` and release your reference when you are completely done with the table.

## Functions

### GwyCreateWidgetFunc()

    GtkWidget *
    (*GwyCreateWidgetFunc) (gpointer user_data);

Type of function constructing a widget.

#### Parameters

user_data | The data passed when the function was set up. | [closure]

#### Returns

A new widget.

### GwyCreateTextFunc()

    gchar *
    (*GwyCreateTextFunc) (gpointer user_data);

Type of function constructing a string.

#### Parameters

user_data | The data passed when the function was set up. | [closure]

#### Returns

A new string.

### GwyEnumFilterFunc()

    gboolean
    (*GwyEnumFilterFunc) (const GwyEnum *enumval,
                          gpointer user_data);

Type of enum filtering function.

#### Parameters

enumval | Pointer to an enumerated value, represented as GwyEnum. |
user_data | The data passed to the driver function. | [closure]

#### Returns

`TRUE` to include this value; `FALSE` to exclude it.

### gwy_param_table_new()

    GwyParamTable *
    gwy_param_table_new (GwyParams *params);

Creates a new table of parameter value controls.

The parameter table manages a set of widgets but it is not a widget. Obtain the widget using `gwy_param_table_widget()`.

The created object is initially unowned. Usually you use `gwy_dialog_add_param_table()` and then GwyDialog will assume ownership. However, if you use GwyParamTable standalone you should take ownership yourself with `g_object_ref_sink()` and then release it with `g_object_unref()` when done.

#### Parameters

params | A parameter value set. |

#### Returns

A newly created set of parameter value controls.

### gwy_param_table_params()

    GwyParams *
    gwy_param_table_params (GwyParamTable *partable);

Gets the parameter value set for a parameter table.

#### Parameters

partable | A parameter table. |

#### Returns

The parameter value set.

### gwy_param_table_widget()

    GtkWidget *
    gwy_param_table_widget (GwyParamTable *partable);

Gets and possibly constructs the parameter controls.

If the widget already exists this function returns the existing widget. Otherwise the widget is created.

The returned widget is a table-like widget with implementation-defined type and structure. It can be added as a child to other widgets, show, hidden, made insensitive or destroyed. However, its individual pieces must not be manipulated outside the GwyParamTable functions.

It is more efficient to get the widget after the controls for all parameters were added with functions like `gwy_param_table_append_checkbox()` and `gwy_param_table_append_combo()`. It is also safer with respect to inadvertent parameter modifications as widgets are created after the setup is done. The opposite order is possible but may not work as expected in complex cases.

#### Parameters

partable | A parameter table. |

#### Returns

Widget with all the parameter controls. The widget is owned by `partable` and you do not receive a new reference (not even a floating one).

### gwy_param_table_reset()

    void
    gwy_param_table_reset (GwyParamTable *partable);

Resets all parameters in a parameter table to defaults.

Foreign controls are not reset; this has to be done extra. Controls with the no-reset flag set with `gwy_param_table_set_no_reset()` are not reset either.

The parameters are reset in the order they were added to the table. In a GwyDialog with multiple tables they are reset in the order they were added to the dialog. In complex tables when valid values of one parameter depend on the value of another this may not be sufficient for a well-defined reset. See the introductory section of GwyDialog for discussion.

The entire update will emit at most one signal (with id equal to -1).

#### Parameters

partable | A parameter table. |

### gwy_param_table_set_from_params()

    void
    gwy_param_table_set_from_params (GwyParamTable *partable,
                                     GwyParams *params);

Set all parameters in a parameter table to values from a parameter set.

The parameter value set must be compatible with the table's one, including ids, names and types. It can be a subset.

Unlike `gwy_param_table_reset()`, this function sets also parameters with the no-reset flag. In the typical case, they would not be included in `params` anyway. If they are, update them to the current values beforehand.

The parameters are set in the order they were added to the table. In the case of complex inter-parameter dependencies some parameter may have to be set manually beforehand for the entire process to work as intended.

The entire update will emit at most one signal (with id equal to -1).

#### Parameters

partable | A parameter table. |
params | A parameter value set. |

### gwy_param_table_exists()

    gboolean
    gwy_param_table_exists (GwyParamTable *partable,
                            gint id);

Tests if a parameter table has controls for a parameter.

#### Parameters

partable | A parameter table. |
id | Parameter identifier. |

#### Returns

`TRUE` if the table has controls for parameter `id` , `FALSE` if it does not.

### gwy_param_table_param_changed()

    void
    gwy_param_table_param_changed (GwyParamTable *partable,
                                   gint id);

Emits the param-changed signal for a parameter table.

This function is rarely needed because the parameter table emits this signal itself. It can be occassionally useful for parameters which are not managed by `partable` and it cannot tell that they have changed. If you want to integrate them, i.e. treat more or less as if they were managed by `partable` , you should probably use this function when they change.

Signal recursion is prevented. If this function is called from within a “param-changed” handler it just immediately returns. Similarly, if the signal is really emitted and other parameters change as the result, their changes no longer cause any recursive “param-changed”.

The value of `id` may correspond to a parameter GwyParamTable has no knowledge of. So it is in effect an arbitrary integer.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_set_no_reset()

    void
    gwy_param_table_set_no_reset (GwyParamTable *partable,
                                  gint id,
                                  gboolean setting);

Sets the no-reset flag for a parameter in a parameter table.

No-reset parameters are untouched by `gwy_param_table_reset()`. Hence they are not reset by the GwyDialog reset response handler either. This can be useful for parameters that do not have static default values and need special treatment during the reset.

Some parameters are no-reset by default: for instance data ids or mask colour.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
setting | `TRUE` to set the no-reset flag, `FALSE` to unset it. |

### gwy_param_table_set_no_resetv()

    void
    gwy_param_table_set_no_resetv (GwyParamTable *partable,
                                   const gint *ids,
                                   gint n,
                                   gboolean setting);

Sets the no-reset flag for multiple parameters in a parameter table.

See `gwy_param_table_set_no_reset()` for description.

#### Parameters

partable | Set of parameter value controls. |
ids | Array of parameter identifiers. |
n | Number of items in `ids` . |
setting | `TRUE` to set the no-reset flag, `FALSE` to unset it. |

### gwy_param_table_set_sensitive()

    void
    gwy_param_table_set_sensitive (GwyParamTable *partable,
                                   gint id,
                                   gboolean sensitive);

Sets the sensitivity of a single control in a parameter table.

If the parameter identified by `id` corresponds to multiple widgets all are set sensitive or insensitive as requested. In most cases this is the right function to enable and disable parameters. However, some may have to be managed in more detail.

For radio buttons this function enables/disables the entire button group, including any header label. Use `gwy_param_table_radio_set_sensitive()` to set sensitivity of individual radio buttons.

#### Parameters

partable | A parameter table. |
id | Parameter identifier. |
sensitive | `TRUE` to make the control sensitive, `FALSE` to make it insensitive. |

### gwy_param_table_set_label()

    void
    gwy_param_table_set_label (GwyParamTable *partable,
                               gint id,
                               const gchar *text);

Sets the label text of a control in a parameter table.

Usually label texts are taken from parameter definitions. This function modifies them dynamically. It can also be used to set the text of messages created by `gwy_param_table_append_message()`. Only controls which naturally have labels can have the label set. Some do not, for instance separators, results or foreign widgets.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
text | New label text (may be `NULL` for the default text). |

### gwy_param_table_set_boolean()

    void
    gwy_param_table_set_boolean (GwyParamTable *partable,
                                 gint id,
                                 gboolean value);

Sets the value of a boolean parameter in a parameter table.

The parameter identified by `id` must be a boolean defined by `gwy_param_def_add_boolean()` or a predefined boolean.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | The new value. |

### gwy_param_table_set_int()

    void
    gwy_param_table_set_int (GwyParamTable *partable,
                             gint id,
                             gint value);

Sets the value of an integer parameter in a parameter table.

The parameter identified by `id` must be an integer parameter defined by `gwy_param_def_add_int()` or a predefined integer parameter.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | The new value. |

### gwy_param_table_set_double()

    void
    gwy_param_table_set_double (GwyParamTable *partable,
                                gint id,
                                gdouble value);

Sets the value of a double parameter in a parameter table.

The parameter identified by `id` must be an floating point parameter defined by `gwy_param_def_add_double()` or a predefined floating point parameter.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | The new value. |

### gwy_param_table_set_enum()

    void
    gwy_param_table_set_enum (GwyParamTable *partable,
                              gint id,
                              gint value);

Sets the value of an enum parameter in a parameter table.

The parameter identified by `id` must be a custom enum defined by `gwy_param_def_add_gwyenum()` or predefined enum set up by `gwy_param_def_add_enum()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | The new value. |

### gwy_param_table_set_flags()

    void
    gwy_param_table_set_flags (GwyParamTable *partable,
                               gint id,
                               guint value);

Sets the value of an flags parameter in a parameter table.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | The new value. |

### gwy_param_table_set_string()

    void
    gwy_param_table_set_string (GwyParamTable *partable,
                                gint id,
                                const gchar *value);

Sets the value of a string parameter.

The function can be used with string entries, unit choosers and resource combos.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | The new value. |

### gwy_param_table_set_data_id()

    void
    gwy_param_table_set_data_id (GwyParamTable *partable,
                                 gint id,
                                 GwyAppDataId value);

Sets the value of a data identifier parameter in a parameter table.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | The new value. |

### gwy_param_table_set_curve()

    void
    gwy_param_table_set_curve (GwyParamTable *partable,
                               gint id,
                               gint value);

Sets the value of a curve number parameter in a parameter table.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | The new value. |

### gwy_param_table_append_header()

    void
    gwy_param_table_append_header (GwyParamTable *partable,
                                   gint id,
                                   const gchar *label);

Adds a control group header to a parameter table.

Headers can be used to visually separate parameters into groups. They are typeset to stand out and have extra space before them.

If `id` is supplied it must be unique, different from all parameter identifiers. This is best achieved by taking them all from the same enum. It is only useful for changing the header text or sensitivity later.

#### Parameters

partable | A parameter table. |
id | Parameter identifier, but usually -1. |
label | Header text. It should be in Header Capitalisation Style. |

### gwy_param_table_append_separator()

    void
    gwy_param_table_append_separator (GwyParamTable *partable);

Adds a separator to a parameter table.

Separator adds some extra space between parameters and can be used for visual grouping. Control group headers added by `gwy_param_table_append_header()` have extra space before them added automatically.

#### Parameters

partable | A parameter table. |

### gwy_param_table_set_unitstr()

    void
    gwy_param_table_set_unitstr (GwyParamTable *partable,
                                 gint id,
                                 const gchar *unitstr);

Sets a fixed units label for a control in a parameter table.

Unit labels are added to the right of the main parameter control. Usually they are used for sliders, although they can be set for most parameter controls except separators, enablers and vertical radio button lists.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier of the control (not a new identifier). |
unitstr | Units for the control (with Pango markup). |

### gwy_param_table_append_checkbox()

    void
    gwy_param_table_append_checkbox (GwyParamTable *partable,
                                     gint id);

Adds a checkbox to a parameter table.

The parameter identified by `id` must be a boolean defined by `gwy_param_def_add_boolean()` or a predefined boolean.

The parameter must have a description which will be used as the label.

See also `gwy_param_table_add_enabler()` for a checkbox integrated into another control and `gwy_param_table_append_checkboxes()` for a set of flags presented as checkboxes.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_add_enabler()

    void
    gwy_param_table_add_enabler (GwyParamTable *partable,
                                 gint id,
                                 gint other_id);

Adds checkbox which enables and disables other parameter in a parameter table.

The parameter identified by `id` must be a boolean defined by `gwy_param_def_add_boolean()` or a predefined boolean.

The parameter identified by `other_id` must be added as combo box, data chooser, slider or radio button row (text or image buttons). The check box will then be integrated in the control of that parameter. If you have a generic enable/disable parameter with its own standalone checkbox use `gwy_param_table_append_checkbox()` instead (and set widget sensitivity using `gwy_param_table_set_sensitive()` in the “param-changed” signal handler).

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
other_id | Identifier of parameter to enable/distable. |

### gwy_param_table_append_combo()

    void
    gwy_param_table_append_combo (GwyParamTable *partable,
                                  gint id);

Adds a combo box to a parameter table.

The parameter identified by `id` must be either an enum or a resource. Custom enums are defined by `gwy_param_def_add_gwyenum()`; predefined enum are set up by `gwy_param_def_add_enum()`. Resource names are defined by `gwy_param_def_add_resource()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_combo_set_filter()

    void
    gwy_param_table_combo_set_filter (GwyParamTable *partable,
                                      gint id,
                                      GwyEnumFilterFunc filter,
                                      gpointer user_data,
                                      GDestroyNotify destroy);

The parameter identified by `id` must be a resource defined by a function such as `gwy_param_def_add_resource()`.

Setting the filter to a different one automatically refilters the data chooser.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
filter | The filter function. | [scope notified][closure user_data][destroy destroy]
user_data | The data passed to `filter` . |
destroy | Destroy notifier of `user_data` or `NULL`. |

### gwy_param_table_combo_refilter()

    void
    gwy_param_table_combo_refilter (GwyParamTable *partable,
                                    gint id);

Requests refiltering of choices in a resource combo in a parameter table.

The parameter identified by `id` must be a resource defined `gwy_param_def_add_resource()`.

It is possible to call this function when the table widget does not exist yet.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_radio()

    void
    gwy_param_table_append_radio (GwyParamTable *partable,
                                  gint id);

Adds a set of radio buttons to a parameter table as a vertical list.

The parameter identified by `id` must be a custom enum defined by `gwy_param_def_add_gwyenum()` or predefined enum set up by `gwy_param_def_add_enum()`.

If the parameter has a description it will be used as the radio button list header. Otherwise the buttons will be free-standing.

Use `gwy_param_table_append_radio_header()` and `gwy_param_table_append_radio_item()` if you need to construct the list piecewise, for instance interspersing the radio buttons with other controls. Use `gwy_param_table_append_radio_row()` for a compact one-row list and `gwy_param_table_append_radio_buttons()` for a one-row list of image buttons.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_radio_header()

    void
    gwy_param_table_append_radio_header (GwyParamTable *partable,
                                         gint id);

Adds a list header for radio buttons to a parameter table.

The parameter identified by `id` must be a custom enum defined by `gwy_param_def_add_gwyenum()` or predefined enum set up by `gwy_param_def_add_enum()`.

The parameter must have a description which will be used as the radio button list header.

Use `gwy_param_table_append_radio_item()` to add individual radio buttons. Use `gwy_param_table_append_radio()` instead to add an entire set of radio buttons at once.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_radio_item()

    void
    gwy_param_table_append_radio_item (GwyParamTable *partable,
                                       gint id,
                                       gint value);

Adds a single radio button to a parameter table.

The parameter identified by `id` must be a custom enum defined by `gwy_param_def_add_gwyenum()` or predefined enum set up by `gwy_param_def_add_enum()`. The value must belong to the enum.

Use `gwy_param_table_append_radio_header()` to add the header for a radio button list. Use `gwy_param_table_append_radio()` instead to add an entire set of radio buttons at once.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value | Enumerated value for a particular radio button. |

### gwy_param_table_append_radio_row()

    void
    gwy_param_table_append_radio_row (GwyParamTable *partable,
                                      gint id);

Adds a set of radio buttons to a parameter table as a compact horizontal list.

The parameter identified by `id` must be a custom enum defined by `gwy_param_def_add_gwyenum()` or predefined enum set up by `gwy_param_def_add_enum()`.

This function is only suitable for a small set of choices, each with a rather short label. Use `gwy_param_table_append_radio()` for a vertical list and `gwy_param_table_append_radio_buttons()` for a one-row list of image buttons.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_radio_buttons()

    void
    gwy_param_table_append_radio_buttons (GwyParamTable *partable,
                                          gint id,
                                          const GwyEnum *icon_names);

Adds a set of radio buttons to a parameter table as a row of image buttons.

The parameter identified by `id` must be a custom enum defined by `gwy_param_def_add_gwyenum()` or predefined enum set up by `gwy_param_def_add_enum()`.

Button order is determined by parameter definition. Icon names `icon_names` do not influence it and can be given in any order.

The enum names from parameter definition will be used for button tooltips. Use `gwy_param_table_append_radio()` for a vertical list and `gwy_param_table_append_radio_row()` for a compact one-row list with text labels.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
icon_names | Symbolic icon names corresponding to the enum values. It may be `NULL` for standard enums for which icons are predefined. |

### gwy_param_table_radio_set_sensitive()

    void
    gwy_param_table_radio_set_sensitive (GwyParamTable *partable,
                                         gint id,
                                         gint value,
                                         gboolean sensitive);

Sets the sensitivity of a single radio button in a parameter table.

This function sets the sensitivity of a radio button corresponding to a specific value. It works with any kind of radio button group controls. Use `gwy_param_table_set_sensitive()` to set the sensitivity of an enitre group of radio buttons.

#### Parameters

partable | A parameter table. |
id | Parameter identifier. |
value | Enumerated value for a particular radio button. |
sensitive | `TRUE` to make the control sensitive, `FALSE` to make it insensitive. |

### gwy_param_table_append_checkboxes()

    void
    gwy_param_table_append_checkboxes (GwyParamTable *partable,
                                       gint id);

Adds a set of checkboxes to a parameter table as a vertical list.

The parameter identified by `id` must be a generic flag set defined by `gwy_param_def_add_gwyflags()`.

If the parameter has a description it will be used as the checkbox list header. Otherwise the checkboxes will be free-standing.

Use `gwy_param_table_append_checkbox()` for individual boolean variables and `gwy_param_table_append_checkbox_row()` for checkboxes in a single row.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_checkboxes_set_sensitive()

    void
    gwy_param_table_checkboxes_set_sensitive
                                   (GwyParamTable *partable,
                                    gint id,
                                    guint flags,
                                    gboolean sensitive);

Sets the sensitivity of a subgroup of flag checkboxes in a parameter table.

This function sets the sensitivity of a checkboxes corresponding to specific values. It works with any kind of checkbox group controls. Use `gwy_param_table_set_sensitive()` to set the sensitivity of an enitre group of checkboxes.

#### Parameters

partable | A parameter table. |
id | Parameter identifier. |
flags | Flag values for a particular radio button. It can have multiple bits set – all corresponding checkboxes are made sensitive/insensitive accordingly. |
sensitive | `TRUE` to make the control sensitive, `FALSE` to make it insensitive. |

### gwy_param_table_append_checkbox_row()

    void
    gwy_param_table_append_checkbox_row (GwyParamTable *partable,
                                         gint id);

Adds a set of checkboxes to a parameter table as a compact horizontal list.

The parameter identified by `id` must be a generic flag set defined by `gwy_param_def_add_gwyflags()`.

This function is only suitable for a small set of choices, each with a rather short label. Use `gwy_param_table_append_checkboxes()` for a vertical checkbox group.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_graph_id()

    void
    gwy_param_table_append_graph_id (GwyParamTable *partable,
                                     gint id);

Adds an graph data chooser to a parameter table.

The parameter identified by `id` must be an graph id defined by `gwy_param_def_add_graph_id()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_spectra_id()

    void
    gwy_param_table_append_spectra_id (GwyParamTable *partable,
                                       gint id);

Adds an spectra data chooser to a parameter table.

The parameter identified by `id` must be a spectra data id defined by `gwy_param_def_add_spectra_id()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_image_id()

    void
    gwy_param_table_append_image_id (GwyParamTable *partable,
                                     gint id);

Adds an image data chooser to a parameter table.

The parameter identified by `id` must be an image id defined by `gwy_param_def_add_image_id()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_volume_id()

    void
    gwy_param_table_append_volume_id (GwyParamTable *partable,
                                      gint id);

Adds an volume data chooser to a parameter table.

The parameter identified by `id` must be a volume data id defined by `gwy_param_def_add_volume_id()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_xyz_id()

    void
    gwy_param_table_append_xyz_id (GwyParamTable *partable,
                                   gint id);

Adds an XYZ data chooser to a parameter table.

The parameter identified by `id` must be an XYZ data id defined by `gwy_param_def_add_xyz_id()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_cmap_id()

    void
    gwy_param_table_append_cmap_id (GwyParamTable *partable,
                                    gint id);

Adds a curve map data chooser to a parameter table.

The parameter identified by `id` must be a curve map id defined by `gwy_param_def_add_cmap_id()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_target_graph()

    void
    gwy_param_table_append_target_graph (GwyParamTable *partable,
                                         gint id,
                                         GwyGraphModel *gmodel);

Adds a target graph chooser to a parameter table.

The parameter identified by `id` must be a graph id defined by `gwy_param_def_add_target_graph()`.

If `gmodel` is not `NULL` it will be used for filtering. Only graphs with units matching `gmodel` will be allowed in the chooser. Filtering is only done upon construction and when explicitly requested using `gwy_param_table_data_id_refilter()`. Therefore, `gmodel` can be changed piecewise without invoking reflitering in the intermediate states.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
gmodel | Graph model to use as template for filtering (or `NULL`). |

### gwy_param_table_append_graph_curve()

    void
    gwy_param_table_append_graph_curve (GwyParamTable *partable,
                                        gint id,
                                        GwyGraphModel *gmodel);

Adds a curve data chooser for a graph model to a parameter table.

The parameter identified by `id` must be an curve number defined by `gwy_param_def_add_graph_curve()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
gmodel | Graph model to choose the curve from. |

### gwy_param_table_graph_curve_set_model()

    void
    gwy_param_table_graph_curve_set_model (GwyParamTable *partable,
                                           gint id,
                                           GwyGraphModel *gmodel);

Changes the graph model for a curve data chooser.

The chooser must be created by `gwy_param_table_append_graph_curve()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
gmodel | Graph model to choose the curve from. |

### gwy_param_table_graph_curve_refresh()

    void
    gwy_param_table_graph_curve_refresh (GwyParamTable *partable,
                                         gint id,
                                         gboolean preserve_index);

Refreshes a curve data chooser after graph model changes.

The chooser must be created by `gwy_param_table_append_graph_curve()`. When `preserve_index` is `FALSE`, the update tries to preserve the selected curve by finding one with the same name. When it is `TRUE`, it tries to keep the curve index in the graph model, which is useful for renaming.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
preserve_index | `TRUE` to keep a curve with the same index selected (when possible). |

### gwy_param_table_append_lawn_curve()

    void
    gwy_param_table_append_lawn_curve (GwyParamTable *partable,
                                       gint id,
                                       GwyLawn *lawn);

Adds a curve data chooser for a lawn to a parameter table.

The parameter identified by `id` must be an curve number defined by `gwy_param_def_add_lawn_curve()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
lawn | Lawn curve map object to choose the curve from. |

### gwy_param_table_lawn_curve_set_model()

    void
    gwy_param_table_lawn_curve_set_model (GwyParamTable *partable,
                                          gint id,
                                          GwyLawn *lawn);

Changes the lawn curve object for a curve data chooser.

The chooser must be created by `gwy_param_table_append_lawn_curve()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
lawn | Lawn curve map object to choose the curve from. |

### gwy_param_table_lawn_curve_refresh()

    void
    gwy_param_table_lawn_curve_refresh (GwyParamTable *partable,
                                        gint id,
                                        gboolean preserve_index);

Refreshes a curve data chooser after lawn curve map changes.

The chooser must be created by `gwy_param_table_append_lawn_curve()`. When `preserve_index` is `FALSE`, the update tries to preserve the selected curve by finding one with the same name. When it is `TRUE`, it tries to keep the curve index in the curve map, which is useful for renaming.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
preserve_index | `TRUE` to keep a curve with the same index selected (when possible). |

### gwy_param_table_append_lawn_segment()

    void
    gwy_param_table_append_lawn_segment (GwyParamTable *partable,
                                         gint id,
                                         GwyLawn *lawn);

Adds a segment data chooser for a lawn to a parameter table.

The parameter identified by `id` must be an segment number defined by `gwy_param_def_add_lawn_segment()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
lawn | Lawn curve map object to choose the segment from. |

### gwy_param_table_append_scatter_data()

    void
    gwy_param_table_append_scatter_data (GwyParamTable *partable,
                                         gint id,
                                         GwyScatter *scatter);

Adds a value chooser for a scattered data to a parameter table.

The parameter identified by `id` must be a value number defined by `gwy_param_def_add_scatter_data()` or possibly a predefined parameter of this type.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
scatter | Scattered data object to choose the value from. |

### gwy_param_table_scatter_data_set_model()

    void
    gwy_param_table_scatter_data_set_model
                                   (GwyParamTable *partable,
                                    gint id,
                                    GwyScatter *scatter);

Changes the scattered data object for a value chooser.

The chooser must be created by `gwy_param_table_append_scatter_data()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
scatter | Scattered data object to choose the curve from. |

### gwy_param_table_scatter_data_refresh()

    void
    gwy_param_table_scatter_data_refresh (GwyParamTable *partable,
                                          gint id,
                                          gboolean preserve_index);

Refreshes a value chooser after scattered data changes.

The chooser must be created by `gwy_param_table_append_scatter_data()`. When `preserve_index` is `FALSE`, the update tries to preserve the selected value by finding one with the same name. When it is `TRUE`, it tries to keep the value index in the scattered data, which is useful for renaming.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
preserve_index | `TRUE` to keep a value with the same index selected (when possible). |

### gwy_param_table_data_id_set_filter()

    void
    gwy_param_table_data_id_set_filter (GwyParamTable *partable,
                                        gint id,
                                        GwyDataChooserFilterFunc filter,
                                        gpointer user_data,
                                        GDestroyNotify destroy);

The parameter identified by `id` must be a data id defined by a function such as `gwy_param_def_add_image_id()` or a predefined parameter of this type, for instance defined by `gwy_param_def_add_target_graph()`.

The arguments have the same meaning as in `gwy_data_chooser_set_filter()`. Setting the filter to a different one automatically refilters the data chooser.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
filter | The filter function. | [scope notified][closure user_data][destroy destroy]
user_data | The data passed to `filter` . |
destroy | Destroy notifier of `user_data` or `NULL`. |

### gwy_param_table_data_id_refilter()

    void
    gwy_param_table_data_id_refilter (GwyParamTable *partable,
                                      gint id);

Requests refiltering of choices in a data chooser in a parameter table.

The parameter identified by `id` must be a data id defined by a function such as `gwy_param_def_add_image_id()` or a predefined parameter of this type, for instance defined by `gwy_param_def_add_target_graph()`.

It is possible to call this function when the table widget does not exist yet.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_slider()

    void
    gwy_param_table_append_slider (GwyParamTable *partable,
                                   gint id);

Adds a numerical slider to a parameter table.

The parameter identified by `id` must be an integer or floating point numerical parameter defined by `gwy_param_def_add_int()`, `gwy_param_def_add_double()` or a predefined parameter of one of these types.

The parameter must have a description which will be used as the label.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_slider_set_mapping()

    void
    gwy_param_table_slider_set_mapping (GwyParamTable *partable,
                                        gint id,
                                        GwyScaleMappingType mapping);

Sets the mapping type for a slider in a parameter table.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
mapping | Mapping type to use. |

### gwy_param_table_slider_set_steps()

    void
    gwy_param_table_slider_set_steps (GwyParamTable *partable,
                                      gint id,
                                      gdouble step,
                                      gdouble page);

Sets the step and page step for a slider in a parameter table.

The parameter table sets automatically reasonable steps according to the parameter type and range. This function allows overriding them when more detailed control is needed.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
step | The step (in true parameter values), as in GtkAdjustment. |
page | The page step (in true parameter values), as in GtkAdjustment. |

### gwy_param_table_slider_set_digits()

    void
    gwy_param_table_slider_set_digits (GwyParamTable *partable,
                                       gint id,
                                       gint digits);

Sets the numnber of decimal place for a slider in a parameter table.

The parameter table sets automatically a reasonable number decimal places according to the parameter type, range and steps. This function allows overriding it when more detailed control is needed.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
digits | The number of decimal places of the numerical value. |

### gwy_param_table_slider_set_snapping()

    void
    gwy_param_table_slider_set_snapping (GwyParamTable *partable,
                                         gint id,
                                         gboolean setting);

Sets the snapping option of a slider in a parameter table.

This function is rarely needed. By default, snapping is enabled for integer sliders as they can only represent the discrete integers, whereas floating point sliders are free. In some cases you may want to override it. Note that once you set the snapping option explicitly, you are responsible for it. There is no way to tell the slider to revert to its default behaviour.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
setting | `TRUE` to enable snapping; `FALSE` to disable it. |

### gwy_param_table_slider_restrict_range()

    void
    gwy_param_table_slider_restrict_range (GwyParamTable *partable,
                                           gint id,
                                           gdouble minimum,
                                           gdouble maximum);

Sets the parameter range a slider in a parameter table to a subset of the full range.

This function allows restricting the slider range to a smaller range than the one set in the GwyParamDef. The range can never be extended (it can be set to be less restricted than previously of course).

If there is a transformation between true and displayed values of parameters (for instance for angles) the minimum and maximum refer to the true values.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
minimum | Minimum allowed value (inclusive), in true parameter values. |
maximum | Minimum allowed value (inclusive), in true parameter values. |

### gwy_param_table_slider_set_transform()

    void
    gwy_param_table_slider_set_transform (GwyParamTable *partable,
                                          gint id,
                                          GwyRealFunc value_to_gui,
                                          GwyRealFunc gui_to_value,
                                          gpointer user_data,
                                          GDestroyNotify destroy);

Sets the transformation function for a slider in a parameter table.

The functions have to be monotonically increasing in the allowed parameter range.

Note that GtkSpinButton behaves reasonably for human-sized values. Neither the true nor the transformed value can be too many orders of magnitude far from unity. For values of physical quantities it is necessary to keep the base power of 10 separately. See also `gwy_param_table_slider_add_alt()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
value_to_gui | Function transforming true values to displayed values. | [scope notified][closure user_data][destroy destroy]
gui_to_value | Function transforming displayed values to true values. | [scope notified][closure user_data][destroy destroy]
user_data | Data passed to `value_to_gui` and `gui_to_value` . |
destroy | Destroy notifier of `user_data` or `NULL`. |

### gwy_param_table_slider_set_factor()

    void
    gwy_param_table_slider_set_factor (GwyParamTable *partable,
                                       gint id,
                                       gdouble q_value_to_gui);

Sets a constant factor transformation for a slider in a parameter table.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
q_value_to_gui | Conversion factor for transforming true values to displayed values. |

### gwy_param_table_slider_add_alt()

    void
    gwy_param_table_slider_add_alt (GwyParamTable *partable,
                                    gint id);

Sets up an alternative value for a slider in a parameter table.

The parameter identified by `id` must correspond to a slider already added by `gwy_param_table_append_slider()`. This functions sets up the alternate representation. It is initally just an identity though. You need to use a function specify a useful alternative representation afterwards, for instance using `gwy_param_table_alt_set_field_pixel_x()` which uses real dimensions in a GwyField alternative values for pixels.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_alt_set_field_pixel_x()

    void
    gwy_param_table_alt_set_field_pixel_x (GwyParamTable *partable,
                                           gint id,
                                           GwyField *field);

Defines a parameter table alternative value for a pixel slider using to physical sizes in a data field.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. Unit value of the true parameter value will correspond to horizontal pixel size, as returned by `gwy_field_get_dx()`.

The data field `field` is only used by this function to set up the transformation. It can be destroyed afterwards if no longer needed by the caller. No reference is taken and later changes to its data or properties do not have any effect on the alternative values. Use `gwy_param_table_alt_set_field_pixel_x()` again if you need to adjust the transformation for a modified (or different) data field.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
field | Data field defining the alternative value transformation. |

### gwy_param_table_alt_set_field_pixel_y()

    void
    gwy_param_table_alt_set_field_pixel_y (GwyParamTable *partable,
                                           gint id,
                                           GwyField *field);

Defines a parameter table alternative value for a pixel slider using to physical sizes in a data field.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. Unit value of the true parameter value will correspond to vertical pixel size, as returned by `gwy_field_get_dy()`.

See `gwy_param_table_alt_set_field_pixel_x()` for a discussion how `field` is used.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
field | Data field defining the alternative value transformation. |

### gwy_param_table_alt_set_brick_pixel_x()

    void
    gwy_param_table_alt_set_brick_pixel_x (GwyParamTable *partable,
                                           gint id,
                                           GwyBrick *brick);

Defines a parameter table alternative value for a pixel slider using to physical sizes in a data brick.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. Unit value of the true parameter value will correspond to horizontal pixel size in the XY plane, as returned by `gwy_brick_get_dx()`.

See `gwy_param_table_alt_set_field_pixel_x()` for a discussion how `brick` is used.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
brick | Data brick definiting the alternative value transformation. |

### gwy_param_table_alt_set_brick_pixel_y()

    void
    gwy_param_table_alt_set_brick_pixel_y (GwyParamTable *partable,
                                           gint id,
                                           GwyBrick *brick);

Defines a parameter table alternative value for a pixel slider using to physical sizes in a data brick.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. Unit value of the true parameter value will correspond to vertical pixel size in the XY plane, as returned by `gwy_brick_get_dy()`.

See `gwy_param_table_alt_set_field_pixel_x()` for a discussion how `brick` is used.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
brick | Data brick definiting the alternative value transformation. |

### gwy_param_table_alt_set_brick_pixel_z()

    void
    gwy_param_table_alt_set_brick_pixel_z (GwyParamTable *partable,
                                           gint id,
                                           GwyBrick *brick);

Defines a parameter table alternative value for a pixel slider using to physical sizes in a data brick.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. Unit value of the true parameter value will correspond to depth-wise pixel size (more precisely, voxel size), as returned by `gwy_brick_get_dz()`.

See `gwy_param_table_alt_set_field_pixel_x()` for a discussion how `brick` is used.

See `gwy_param_table_alt_set_calibration()` which can be used with bricks which have Z-calibration.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
brick | Data brick definiting the alternative value transformation. |

### gwy_param_table_alt_set_lawn_pixel_x()

    void
    gwy_param_table_alt_set_lawn_pixel_x (GwyParamTable *partable,
                                          gint id,
                                          GwyLawn *lawn);

Defines a parameter table alternative value for a pixel slider using to physical sizes in a data lawn.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. Unit value of the true parameter value will correspond to horizontal pixel size, as returned by `gwy_lawn_get_dx()`.

See `gwy_param_table_alt_set_field_pixel_x()` for a discussion how `lawn` is used.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
lawn | Data lawn definiting the alternative value transformation. |

### gwy_param_table_alt_set_lawn_pixel_y()

    void
    gwy_param_table_alt_set_lawn_pixel_y (GwyParamTable *partable,
                                          gint id,
                                          GwyLawn *lawn);

Defines a parameter table alternative value for a pixel slider using to physical sizes in a data lawn.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. Unit value of the true parameter value will correspond to vertical pixel size, as returned by `gwy_lawn_get_dy()`.

See `gwy_param_table_alt_set_field_pixel_x()` for a discussion how `lawn` is used.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
lawn | Data lawn definiting the alternative value transformation. |

### gwy_param_table_alt_set_field_frac_z()

    void
    gwy_param_table_alt_set_field_frac_z (GwyParamTable *partable,
                                          gint id,
                                          GwyField *field);

Defines a parameter table alternative value for a fraction slider using to physical values in a data field.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. The range [0,1] of true parameter values will correspond to the range of values in the data field, as returned by `gwy_field_min_max()`.

See `gwy_param_table_alt_set_field_pixel_x()` for a discussion how `field` is used.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
field | Data field defining the alternative value transformation. |

### gwy_param_table_alt_set_linear()

    void
    gwy_param_table_alt_set_linear (GwyParamTable *partable,
                                    gint id,
                                    gdouble q_to_gui,
                                    gdouble off_to_gui,
                                    const gchar *unitstr);

Defines a parameter table alternative value for a fraction slider using a linear function.

This function enables setting up a general linear transformation for the alternative value. The usual cases are more conveniently handled by functions like `gwy_param_table_alt_set_field_pixel_x()` or `gwy_param_table_alt_set_field_frac_z()`.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. The displayed value is calculated from true parameter as `q_to_gui` *`value` + `off_to_gui` .

The factor and offset include any power-of-10 factors corresponding to the units `unitstr` . If `unitstr` comes from a GwyValueFormat, then `q_to_gui` and `off_to_gui` need to be divided by `magnitude` .

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
q_to_gui | Conversion factor for transforming true values to displayed values. |
off_to_gui | Offset for transforming true values to displayed values. |
unitstr | Units for the alternative value (with Pango markup). |

### gwy_param_table_alt_set_calibration()

    void
    gwy_param_table_alt_set_calibration (GwyParamTable *partable,
                                         gint id,
                                         GwyLine *calibration);

Defines a parameter table alternative value for a fraction slider using to a table given by a data line.

The slider needs to have an alternative value set up using `gwy_param_table_slider_add_alt()`. The range [0,`res` -1] of true parameter values will correspond to the values in `calibration` , in order. It has to contain a monotonically increasing sequence of values.

Modification of `calibration` during the existence of `partable` is not supported. The data line has to be static.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
calibration | Data line defining the calibration. It will be referenced by the parameter table. |

### gwy_param_table_append_entry()

    void
    gwy_param_table_append_entry (GwyParamTable *partable,
                                  gint id);

Adds an entry to a parameter table.

The parameter identified by `id` must be a string, integer or double. Other types may be supported in future.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_entry_set_width()

    void
    gwy_param_table_entry_set_width (GwyParamTable *partable,
                                     gint id,
                                     gint width_chars);

Sets the width of an entry in a parameter table.

For numeric formats the automatic width should be sufficient.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
width_chars | Entry width in characters. |

### gwy_param_table_entry_set_value_format()

    void
    gwy_param_table_entry_set_value_format
                                   (GwyParamTable *partable,
                                    gint id,
                                    GwyValueFormat *vf);

Sets the parsing and formatting for a numeric entry to a given value format.

The parameter must be a double defined by `gwy_param_def_add_double()` or a predefined parameter of one of these types.

Setting the value format also sets the unit label accordingly. If you want a different unit label you can override it by using `gwy_param_table_set_unitstr()` after this function.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
vf | Value format to use. The parameter table makes its own copy of the format. |

### gwy_param_table_entry_set_instant_changes()

    void
    gwy_param_table_entry_set_instant_changes
                                   (GwyParamTable *partable,
                                    gint id,
                                    gboolean setting);

Enables or disables instant change signals of a parameter table entriy.

With instant changes any edit causes a change of the parameter and emission of GwyParamTable::param-changed. By default, both only occur only when the entry loses focus or upon entry activation (pressing Enter).

Instant changes are not suitable for parameters with rectifiers because it can lead to the user and rectification function fighting over the entry content.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
setting | `TRUE` to enable instant changes; `FALSE` to disable them. |

### gwy_param_table_append_range()

    void
    gwy_param_table_append_range (GwyParamTable *partable,
                                  gint id_from,
                                  gint id_to);

Adds a pair of numerical entries representing a range to a parameter table.

This is mostly useful for entering graph or value ranges numerically. For image coordinate ranges separate origin and size controls are preferred as they allow pixel plus alternative real values.

The two parameters identified by `id_from` and `id_to` must be doubles and distinct. Parameter `id_from` is considered primary and should be used for referring to the control as a whole (for instance to make it insensitive), even though for convenience both are passed directly to this function.

Use `gwy_param_table_entry_set_value_format()` to set the value format.

#### Parameters

partable | Set of parameter value controls. |
id_from | Parameter identifier for the beginning. |
id_to | Parameter identifier for the end. |

### gwy_param_table_append_unit_chooser()

    void
    gwy_param_table_append_unit_chooser (GwyParamTable *partable,
                                         gint id);

Adds a unit chooser to a parameter table.

The parameter identified by `id` must be a unit parameter defined by `gwy_param_def_add_unit()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_color()

    void
    gwy_param_table_append_color (GwyParamTable *partable,
                                  gint id);

Adds a generic colour button to a parameter table.

The parameter identified by `id` must be a colour parameter defined by `gwy_param_def_add_color()`. See `gwy_param_table_append_image_mask_color()` for a convenient function mask colours.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_color_add_preset()

    void
    gwy_param_table_color_add_preset (GwyParamTable *partable,
                                      gint id,
                                      GwyRGBA rgba,
                                      const gchar *name);

Adds a preset colour to a generic colour button in a parameter table.

Although `name` may be `NULL`, unlabelled presets look too similar to the colour button. So it is recommended to label the colours.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
rgba | The predefined colour. |
name | Label to display alongside, possibly `NULL`. |

### gwy_param_table_append_image_mask_color()

    void
    gwy_param_table_append_image_mask_color
                                   (GwyParamTable *partable,
                                    gint id,
                                    GwyDataView *dataview,
                                    GwyFile *file,
                                    gint i);

Adds a preview mask colour button to a parameter table.

Usually the mask colour should be initialised from the file using `gwy_setup_data_view()`. When the dialog is finished it the mask colour should be set on the output again using `gwy_app_sync_data_items()`. If `data` and `i` are supplied then this is done automatically, which is suitable for typical mask-creating modules.

If `dataview` is passed, its mask colour will be kept updated with the parameter's colour. If `data` and `id` are not give but `dataviw` is, it is used to initialise the colour.

The parameter identified by `id` must be a colour parameter defined by `gwy_param_def_add_mask_color()`. By default, mask colour are not reset (see `gwy_param_table_set_no_reset()`) because the colour is normally external to the module's own settings.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
dataview | Data view whose mask colour should be kept updated to this colour (or `NULL`). | [transfer none][nullable]
file | File data container with the mask (or `NULL`). | [transfer none][nullable]
i | Id of the data field in `data` (or -1). |

### gwy_param_table_append_button()

    void
    gwy_param_table_append_button (GwyParamTable *partable,
                                   gint id,
                                   gint sibling_id,
                                   gint response,
                                   const gchar *text);

Adds a button to a parameter table.

Action buttons occasionally appear inside parameter tables when they do not represent a global action but act on a specific control. For instance they can be used to run an automatic estimation of one specific parameter.

Each button must have its own unique `id` , different from all parameter identifiers. This is best achieved by taking them all from the same enum. However, pressing the button does not change any parameter. It emits GtkDialog::response signal on the parent dialog, with response id given by `response` . Connect to this signal to actually perform the action.

A row with multiple buttons can be created by passing -1 as `sibling_id` for the first button and then ids of some of the previous buttons for the other buttons.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
sibling_id | Identifier of another button in the same row, or -1 for a new button row. |
response | Dialog response to emit. |
text | Text on the button. |

### gwy_param_table_button_set_icon()

    void
    gwy_param_table_button_set_icon (GwyParamTable *partable,
                                     gint id,
                                     const gchar *icon_name);

Sets an icon for a button in a parameter table.

#### Parameters

partable | Set of parameter value controls. |
id | Button identifier. |
icon_name | Icon name, or `NULL`. |

### gwy_param_table_append_info()

    void
    gwy_param_table_append_info (GwyParamTable *partable,
                                 gint id,
                                 const gchar *label);

Add a structured informational value label to a parameter table.

Informational values not modifiable by the users often appear in parameter tables. Each must have its own unique `id` , different from all parameter identifiers, if you need to refer to it later. This is best achieved by taking them all from the same enum. For static texts you can also pass -1 as `id` ; you will not be able to refer to them later.

Use `gwy_param_table_info_set_valuestr()` to set the value part of the information; use `gwy_param_table_set_unitstr()` to set the unit part.

This function is suitable for one-off labels. For larger sets of values consider using GwyResults and `gwy_param_table_append_results()`. See also `gwy_param_table_append_message()` for unstructured texts.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
label | Information label text. |

### gwy_param_table_append_results()

    void
    gwy_param_table_append_results (GwyParamTable *partable,
                                    gint id,
                                    GwyResults *results,
                                    const gchar *result_id,
                                    ...);

Adds a set of reported scalar variables to a parameter table.

Results are not actual user modifiable settings. Yet they often appear in parameter tables. This function integrates them to the parameter table. It appends a single contiguous block of results. Use it multiple times, perhaps interspersed with `gwy_param_table_append_header()`, to create multiple blocks for the same `results` object.

Multiple result blocks can share one `id` . Functions such as `gwy_param_table_results_fill()` and `gwy_param_table_results_clear()` then act on all blocks with given id.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
results | A set of reported scalar values. |
result_id | String identifier of the first result in `result` to add. |
... | `NULL`-terminated list of more result identifiers. |

### gwy_param_table_append_resultsv()

    void
    gwy_param_table_append_resultsv (GwyParamTable *partable,
                                     gint id,
                                     GwyResults *results,
                                     const gchar **result_ids,
                                     gint nids);

Adds a set of reported scalar variables to a parameter table.

See `gwy_param_table_append_results()` for details.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
results | A set of reported scalar values. |
result_ids | Array of string result identifiers in `results` . |
nids | Number of items in `result_ids` . You can pass -1 if the array is `NULL`-terminated. |

### gwy_param_table_results_fill()

    void
    gwy_param_table_results_fill (GwyParamTable *partable,
                                  gint id);

Fills displayed values in a set of reported scalar variables in a parameter table.

The identifier `id` must correspond to a results block added by `gwy_param_table_append_results()` or a similar function.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_results_clear()

    void
    gwy_param_table_results_clear (GwyParamTable *partable,
                                   gint id);

Clears all displayed values in a set of reported scalar variables in a parameter table.

The identifier `id` must correspond to a results block added by `gwy_param_table_append_results()` or a similar function.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_report()

    void
    gwy_param_table_append_report (GwyParamTable *partable,
                                   gint id);

Adds controls for report formatting to a parameter table.

The parameter identified by `id` must be a report type defined by `gwy_param_def_add_report_type()`.

You also need to provide means of report creation by `gwy_param_table_report_set_results()` or `gwy_param_table_report_set_formatter()`. Otherwise the controls allow changing the format type parameter, but the action buttons cannot do anything.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_report_set_results()

    void
    gwy_param_table_report_set_results (GwyParamTable *partable,
                                        gint id,
                                        GwyResults *results);

Sets up report export controls in a parameter table to format GwyResults.

The results would be typically added to the table just above using `gwy_param_table_append_results()`. However, you can use aribtrary GwyResults object.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
results | A set of reported scalar values. |

### gwy_param_table_report_set_formatter()

    void
    gwy_param_table_report_set_formatter (GwyParamTable *partable,
                                          gint id,
                                          GwyCreateTextFunc format_report,
                                          gpointer user_data,
                                          GDestroyNotify destroy);

Sets up report export controls in a parameter table to use a custom function to format the report.

When using a custom formatting function, the report would typically be added just above as a GtkTreeView or a similar data display widget.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
format_report | Function which will format the report for Copy and Save actions. | [scope notified][closure user_data][destroy destroy]
user_data | Data passed to `format_report` . |
destroy | Destroy notifier of `user_data` or `NULL`. |

### gwy_param_table_append_hold_selection()

    void
    gwy_param_table_append_hold_selection (GwyParamTable *partable,
                                           gint id);

Adds a selection holding parameter to a parameter table.

The parameter identified by `id` must be a selection holding flags parameter defined by `gwy_param_def_add_hold_selection()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_seed()

    void
    gwy_param_table_append_seed (GwyParamTable *partable,
                                 gint id);

Adds a random seed parameter to a parameter table.

The parameter identified by `id` must be a random seed parameter defined by `gwy_param_def_add_seed()`.

Usually there is an associated boolean parameter controlling randomization which should be added just below using `gwy_param_table_append_checkbox()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |

### gwy_param_table_append_message()

    void
    gwy_param_table_append_message (GwyParamTable *partable,
                                    gint id,
                                    const gchar *text);

Adds a simple message to a parameter table.

Messages are not actual user modifiable settings. Yet they often appear in parameter tables. Each message must have its own unique `id` , different from all parameter identifiers, if you need to refer to it later. This is best achieved by taking them all from the same enum. For static texts you can also pass -1 as `id` ; you will not be able to refer to them later.

Use `gwy_param_table_set_label()` to change the text later. Use `gwy_param_table_message_set_type()` to set the message type.

This function is intended for unstructured and potentially long, even multiline texts. They can take the full width but cannot have unit text. Use `gwy_param_table_append_info()` instead for information labels with the common label-value-unit structure.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier (possibly -1). |
text | Message text (may be `NULL` for initially empty message). |

### gwy_param_table_info_set_valuestr()

    void
    gwy_param_table_info_set_valuestr (GwyParamTable *partable,
                                       gint id,
                                       const gchar *text);

Sets the value text of a informational value label in a parameter table.

The value text is right-aligned and placed to the right part of the row. This can be used to create simple structured label-value-units messages.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier of the informational value label (not a new identifier). |
text | Value text (may be `NULL` for empty value). |

### gwy_param_table_info_set_add_punctuation()

    void
    gwy_param_table_info_set_add_punctuation
                                   (GwyParamTable *partable,
                                    gint id,
                                    gboolean setting);

Sets whether standard punctuation is added to an informational value label in a parameter table.

The default behaviour is to add the same punctuation as to parameter labels. Use this function to disable it.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier of the informational value label (not a new identifier). |
setting | `TRUE` to add punctuation (usually a colon), `FALSE` to keep the label intact. |

### gwy_param_table_message_set_type()

    void
    gwy_param_table_message_set_type (GwyParamTable *partable,
                                      gint id,
                                      GtkMessageType type);

Sets the type of a message in a parameter table.

This function modifies the visual style of the text according to the given type, the default `GTK_MESSAGE_INFO` corresponding to a neutral presentation. Not all types are equally meaningful in a parameter table. Do not use `GTK_MESSAGE_QUESTION` and `GTK_MESSAGE_OTHER`.

If the message has a value text set by `gwy_param_table_message_set_value_text()` both are styled the same.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier of the message. |
type | Message type. |

### gwy_param_table_append_foreign()

    void
    gwy_param_table_append_foreign (GwyParamTable *partable,
                                    gint id,
                                    GwyCreateWidgetFunc create_widget,
                                    gpointer user_data,
                                    GDestroyNotify destroy);

Adds a widget that is not supported natively to a parameter table.

This function takes a function instead of the widget itself. If the table widget is destroyed and recreated then `create_widget` can be called multiple times. Typically, however, it will just be called once. The destroy notifier will only be called when `partable` itself is destroyed.

The created widget must not be indepdendently destroyed while the table widget exists. If the widget is a container, like GtkBox, it will give you considerable freedom to change its contents later.

The identifier `id` may be passed as -1 if you are not interested in referring to the widget using GwyParamTable functions. A real identifier enables some rudimentary functionality such as `gwy_param_table_exists()` and `gwy_param_table_set_sensitive()`.

#### Parameters

partable | Set of parameter value controls. |
id | Parameter identifier. |
create_widget | Function to create the widget. | [scope notified][closure user_data][destroy destroy]
user_data | The data passed to `create_widget` . |
destroy | Destroy notifier of `user_data` or `NULL`. |

## Types and Values

### struct GwyParamTable

    struct GwyParamTable;

Object managing user interface controls for parameters.

The GwyParamTable struct contains no public fields.

### struct GwyParamTableClass

    struct GwyParamTableClass {
        GInitiallyUnownedClass parent;
    };

Class of user interface parameter controls manager.

## Signal Details

### The `“param-changed”` signal

    void
    user_function (GwyParamTable *gwyparamtable,
                   int            arg1,
                   gpointer       user_data)

The ::param-changed signal is emitted when a parameter changes.

The signal is not emitted recursively. In other words, if a signal handler modifies other parameters in response to a parameter change, it is expected to complete all the dependent udpdates.

#### Parameters

gwyparamtable | The GwyParamTable which received the signal. |
arg1 | Identifier of the changed parameter. |
user_data | user data set when the signal handler was connected. |

Flags: Run First