GwyParamTable (HEAD)

GwyParamTable — User interface for parameter sets

Functions

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GwyParamTable

Includes

#include <app/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
13

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);
gwy_dialog_add_param_table(dialog, table);

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.

Finally, GwyDialog should be notified that a new table was added using gwy_dialog_add_param_table(). It is possible to add tables GwyDialog does not know about, although this is seldom useful.

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.

Functions

GwyCreateWidgetFunc ()

GtkWidget *
(*GwyCreateWidgetFunc) (gpointer user_data);

Type of function constructing a widget.

Parameters

Returns

A new widget.

Since: 2.59

GwyCreateTextFunc ()

gchar *
(*GwyCreateTextFunc) (gpointer user_data);

Type of function constructing a string.

Parameters

Returns

A new string.

Since: 2.59

GwyEnumFilterFunc ()

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

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

Returns

A newly created set of parameter value controls.

Since: 2.59

gwy_param_table_params ()

GwyParams *
gwy_param_table_params (GwyParamTable *partable);

Gets the parameter value set for a parameter table.

Parameters

Returns

The parameter value set.

Since: 2.59

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

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).

Since: 2.59

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

Since: 2.59

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

Since: 2.62

gwy_param_table_exists ()

gboolean
gwy_param_table_exists (GwyParamTable *partable,
                        gint id);

Tests if a parameter table has controls for a parameter.

Parameters

Returns

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.62

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.60

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

gwy_param_table_append_radio_buttons ()

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

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. Stock image identifiers stock_ids 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

Since: 2.59

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. Use gwy_param_table_set_sensitive() to set the sensitivity of an enitre group of radio buttons.

Parameters

Since: 2.59

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 enum defined by gwy_param_def_add_gwyenum() or gwy_param_def_add_enum().

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.

Parameters

Since: 2.59

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. Use gwy_param_table_set_sensitive() to set the sensitivity of an enitre group of checkboxes.

Parameters

Since: 2.59

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

Since: 2.60

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

gwy_param_table_append_curve_map_id ()

void
gwy_param_table_append_curve_map_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_curve_map_id() or possibly a predefined parameter of this type.

Parameters

Since: 2.60

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

Since: 2.59

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

Since: 2.60

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

Since: 2.60

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

Since: 2.60

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

Since: 2.60

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.62

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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 GwyDataField alternative values for pixels.

Parameters

Since: 2.59

gwy_param_table_alt_set_field_pixel_x ()

void
gwy_param_table_alt_set_field_pixel_x (GwyParamTable *partable,
                                       gint id,
                                       GwyDataField *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_data_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

Since: 2.59

gwy_param_table_alt_set_field_pixel_y ()

void
gwy_param_table_alt_set_field_pixel_y (GwyParamTable *partable,
                                       gint id,
                                       GwyDataField *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_data_field_get_dy().

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

Parameters

Since: 2.59

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

Since: 2.62

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

Since: 2.62

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

Since: 2.62

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

Since: 2.62

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

Since: 2.62

gwy_param_table_alt_set_field_frac_z ()

void
gwy_param_table_alt_set_field_frac_z (GwyParamTable *partable,
                                      gint id,
                                      GwyDataField *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_data_field_get_min_max().

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

Parameters

Since: 2.59

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 GwySIValueFormat, then q_to_gui and off_to_gui need to be divided by magnitude .

Parameters

Since: 2.59

gwy_param_table_alt_set_calibration ()

void
gwy_param_table_alt_set_calibration (GwyParamTable *partable,
                                     gint id,
                                     GwyDataLine *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

Since: 2.62

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

Since: 2.60

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

Since: 2.60

gwy_param_table_entry_set_value_format ()

void
gwy_param_table_entry_set_value_format
                               (GwyParamTable *partable,
                                gint id,
                                GwySIValueFormat *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

Since: 2.60

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

Since: 2.62

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 ranges numerically. For image ranges separate 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

Since: 2.63

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

Since: 2.59

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_mask_color() for mask colours.

Parameters

Since: 2.64

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

Since: 2.64

gwy_param_table_append_mask_color ()

void
gwy_param_table_append_mask_color (GwyParamTable *partable,
                                   gint id,
                                   GwyContainer *preview_data,
                                   gint preview_i,
                                   GwyContainer *data,
                                   gint i);

Adds a preview mask colour button to a parameter table.

The mask colour will use the standard prefix "/0/mask" where 0 is replaced by preview_i . So it should be also used when setting up the mask layer.

It is possible to have multiple masks and colours in the preview data. However, you need to consider that the colour managed by this colour button will be given by preview_i .

Usually the mask colour should be initialised from the file using gwy_app_sync_data_items(). 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.

The parameter identified by id must be a colour parameter defined by gwy_param_def_add_mask_color().

Parameters

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.63

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

Since: 2.59

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

Since: 2.59

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

Since: 2.59

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

Since: 2.62

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

Since: 2.59

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

Since: 2.59

Types and Values

struct GwyParamTable

struct GwyParamTable;

Object managing user interface controls for parameters.

The GwyParamTable struct contains no public fields.

Since: 2.59

struct GwyParamTableClass

struct GwyParamTableClass {
    GInitiallyUnownedClass parent;
};

Class of user interface parameter controls manager.

Since: 2.59

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

Flags: Run First