GwyFitTable: Gwyddion Widgets Library Reference Manual

## GwyFitTable GwyFitTable — Table of fit results |

## Functions

GtkWidget * | gwy_fit_table_new ()
void | gwy_fit_table_set_has_checkboxes ()
gboolean | gwy_fit_table_get_has_checkboxes ()
void | gwy_fit_table_set_values_editable ()
gboolean | gwy_fit_table_get_values_editable ()
void | gwy_fit_table_resize ()
void | gwy_fit_table_set_header ()
void | gwy_fit_table_set_name ()
void | gwy_fit_table_set_tooltip ()
void | gwy_fit_table_set_unit ()
void | gwy_fit_table_set_flags ()
void | gwy_fit_table_set_value ()
void | gwy_fit_table_set_error ()
gboolean | gwy_fit_table_error_is_set ()
void | gwy_fit_table_clear_error ()
void | gwy_fit_table_clear_errors ()
void | gwy_fit_table_clear_value ()
void | gwy_fit_table_clear_values ()
gboolean | gwy_fit_table_value_is_set ()
void | gwy_fit_table_revert_values ()
void | gwy_fit_table_set_checked ()
gdouble | gwy_fit_table_get_value ()
gdouble | gwy_fit_table_get_error ()
gboolean | gwy_fit_table_get_checked ()
void | gwy_fit_table_set_sensitive ()
void | gwy_fit_table_reset_sensitivity ()
gint | gwy_fit_table_gather ()

## Signals

void | activated | Run First
void | changed | Run First
void | toggled | Run First

## Types and Values

struct | GwyFitTable
struct | GwyFitTableClass

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkGrid
                        ╰── GwyFitTable

## Implemented Interfaces

GwyFitTable implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Includes

    #include <libgwyui/gwyui.h>

## Description

GwyFitTable can be used either for passive display of least-squares fitting results or for user-settable parameter values. If parameters should be edtiable, use `gwy_fit_table_set_values_editable()` and often also `gwy_fit_table_set_has_checkboxes()` to add checkboxes controlling fixed/free parameters. The widget does not assign any meaning to the checkboxes.

A fit table keeps track of all parameter values, errors and checkbox states. It can even revert parameters to the last values set programatically, i.e. revert user changes (for example since the last fit). Therefore, it can be used as the primary store if you do not wish to keep a copy of everything.

## Functions

### gwy_fit_table_new()

    GtkWidget *
    gwy_fit_table_new (void);

Creates a new table of fit results.

#### Returns

New fit results table widget.

### gwy_fit_table_set_has_checkboxes()

    void
    gwy_fit_table_set_has_checkboxes (GwyFitTable *table,
                                      gboolean setting);

Sets whether rows in a table of fit results have checkboxes.

#### Parameters

table | A table of fit results. |
setting | `TRUE` if each row should have a checkbox; `FALSE` if it should not. |

### gwy_fit_table_get_has_checkboxes()

    gboolean
    gwy_fit_table_get_has_checkboxes (GwyFitTable *table);

Reports whether rows in a table of fit results have checkboxes.

#### Parameters

table | A table of fit results. |

#### Returns

`TRUE` if each row has a checkbox; `FALSE` if it does not.

### gwy_fit_table_set_values_editable()

    void
    gwy_fit_table_set_values_editable (GwyFitTable *table,
                                       gboolean setting);

Sets whether the values in a table of fit results are editable.

#### Parameters

table | A table of fit results. |
setting | `TRUE` if values should editable entries; `FALSE` if they are only displayed. |

### gwy_fit_table_get_values_editable()

    gboolean
    gwy_fit_table_get_values_editable (GwyFitTable *table);

Reports whether the values in a table of fit results are editable.

#### Parameters

table | A table of fit results. |

#### Returns

`TRUE` if values are editable entries; `FALSE` if they are only displayed.

### gwy_fit_table_resize()

    void
    gwy_fit_table_resize (GwyFitTable *table,
                          guint n);

Resizes a table of fit results.

If the table shrinks then no further setup is necessary, in principle. If it expands, you should usually set row labels, and possibly values and errors (which are created unset). Note that row sensitivity is not reset (you can use `gwy_fit_table_reset_sensitivity()`). Typically, this function is used when the fit model changes, so all rows are set up afterwards.

#### Parameters

table | A table of fit results. |
n | New number of parameters. |

### gwy_fit_table_set_header()

    void
    gwy_fit_table_set_header (GwyFitTable *table,
                              const gchar *markup,
                              guint col,
                              guint width);

Sets a header label in a table of fit results.

An existing header starting at the same column is replaced. If you try to create overlapping headers the behaviour is undefined.

#### Parameters

table | A table of fit results. |
markup | Header label as valid Pango markup. |
col | The first column of the header label. |
width | The column span of the header label. |

### gwy_fit_table_set_name()

    void
    gwy_fit_table_set_name (GwyFitTable *table,
                            guint i,
                            const gchar *markup);

Sets the name of a parameter in a table of fit results.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |
markup | Parameter name as valid Pango markup. |

### gwy_fit_table_set_tooltip()

    void
    gwy_fit_table_set_tooltip (GwyFitTable *table,
                               guint i,
                               const gchar *markup);

Sets the tooltip of a parameter in a table of fit results.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |
markup | Parameter tooltip as valid Pango markup. |

### gwy_fit_table_set_unit()

    void
    gwy_fit_table_set_unit (GwyFitTable *table,
                            guint i,
                            GwyUnit *unit);

Sets the unit of a parameter in a table of fit results.

Setting the unit generally causes reformatting of the value and error (in addition to the unit labels).

#### Parameters

table | A table of fit results. |
i | Row index in the table. |
unit | New parameter unit. It is passed by value. The object is not kept. |

### gwy_fit_table_set_flags()

    void
    gwy_fit_table_set_flags (GwyFitTable *table,
                             guint i,
                             GwyNLFitParamFlags flags);

Sets the flags for a parameter in a table of fit results.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |
flags | Parameter flags. |

### gwy_fit_table_set_value()

    void
    gwy_fit_table_set_value (GwyFitTable *table,
                             guint i,
                             gdouble value);

Sets the value of a parameter in a table of fit results.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |
value | The value of `i` -th parameter. |

### gwy_fit_table_set_error()

    void
    gwy_fit_table_set_error (GwyFitTable *table,
                             guint i,
                             gdouble error);

Sets the error of a parameter in a table of fit results.

Use `gwy_fit_table_clear_error()` to unset the error.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |
error | The value of `i` -th parameter. |

### gwy_fit_table_error_is_set()

    gboolean
    gwy_fit_table_error_is_set (GwyFitTable *table,
                                guint i);

Reports whether an error in a table of fit results is set or cleared.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |

#### Returns

`TRUE` if the error is set (and displayed), `FALSE` when it is cleared (and hidden).

### gwy_fit_table_clear_error()

    void
    gwy_fit_table_clear_error (GwyFitTable *table,
                               guint i);

Clears the error of a parameter in a table of fit results.

Claring the error means no error is displayed, for instance to indicate the parameter has not yet been fitted. Use `gwy_fit_table_set_error()` to display an error.

Use `gwy_fit_table_clear_errors()` to clear all errors.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |

### gwy_fit_table_clear_errors()

    void
    gwy_fit_table_clear_errors (GwyFitTable *table);

Clears the errors of all parameter in a table of fit results.

See `gwy_fit_table_clear_error()` for clearing invididual errors and discussion.

#### Parameters

table | A table of fit results. |

### gwy_fit_table_clear_value()

    void
    gwy_fit_table_clear_value (GwyFitTable *table,
                               guint i);

Clears the value of a parameter in a table of fit results.

Claring the value means no value is displayed, for instance to indicate the parameter has not yet been initialised in any manner. The stored value remains unchanged. Use `gwy_fit_table_set_value()` to display a value.

Only passively displayed values, i.e. those not set editable using `gwy_fit_table_set_values_editable()`, can be cleared.

Use `gwy_fit_table_clear_values()` to clear all values.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |

### gwy_fit_table_clear_values()

    void
    gwy_fit_table_clear_values (GwyFitTable *table);

Clears the values of all parameters in a table of fit results.

See `gwy_fit_table_clear_value()` for clearing invididual values and discussion.

#### Parameters

table | A table of fit results. |

### gwy_fit_table_value_is_set()

    gboolean
    gwy_fit_table_value_is_set (GwyFitTable *table,
                                guint i);

Reports whether an value in a table of fit results is set or cleared.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |

#### Returns

`TRUE` if the value is set (and displayed), `FALSE` when it is cleared (and hidden).

### gwy_fit_table_revert_values()

    void
    gwy_fit_table_revert_values (GwyFitTable *table);

Reverts the values of all parameter in a table of fit results.

The values are set to the last programmatic update (done using `gwy_fit_table_set_value()`), discarding all user modifications.

#### Parameters

table | A table of fit results. |

### gwy_fit_table_set_checked()

    void
    gwy_fit_table_set_checked (GwyFitTable *table,
                               guint i,
                               gboolean checked);

Sets the whether the checkox of a parameter in a table of fit results is checked.

The state is remebmered even when no checkboxes are actually shown.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |
checked | `TRUE` to check the checkbox; `FALSE` to uncheck it. |

### gwy_fit_table_get_value()

    gdouble
    gwy_fit_table_get_value (GwyFitTable *table,
                             guint i);

Gets the value of a parameter in a table of fit results.

The value is only updated when the value entry is activated or loses focus (and on programmatic updates).

See also `gwy_fit_table_gather()` for getting information about all parameters at once.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |

#### Returns

The parsed parameter value.

### gwy_fit_table_get_error()

    gdouble
    gwy_fit_table_get_error (GwyFitTable *table,
                             guint i);

Gets the error of a parameter in a table of fit results.

The error is always whatever was set using the last `gwy_fit_table_set_error()` for the paramters. Clearing an error does not change the value. This functions exists in case you do not want to keep around an array of errors yourself.

See also `gwy_fit_table_gather()` for getting information about all parameters at once.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |

#### Returns

The parameter error.

### gwy_fit_table_get_checked()

    gboolean
    gwy_fit_table_get_checked (GwyFitTable *table,
                               guint i);

Gets the whether the checkbox of parameter in a table of fit results is checked.

The checked state is remembered even when checkboxes are hidden.

See also `gwy_fit_table_gather()` for getting information about all parameters at once.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |

#### Returns

`TRUE` if the checkbox is checked.

### gwy_fit_table_set_sensitive()

    void
    gwy_fit_table_set_sensitive (GwyFitTable *table,
                                 guint i,
                                 gboolean setting);

Sets the sensitivity of a row in a table of fit results.

This function should be rarely needed and probably only makes sense when the parameters are editable.

#### Parameters

table | A table of fit results. |
i | Row index in the table. |
setting | `TRUE` to make the row sensitive, `FALSE` to make it insensitive. |

### gwy_fit_table_reset_sensitivity()

    void
    gwy_fit_table_reset_sensitivity (GwyFitTable *table);

Resets the sensitivity of all rows in a table of fit results.

All rows are made sensitive, as is the default. This function should be rarely needed and probably only makes sense when the parameters are editable.

#### Parameters

table | A table of fit results. |

### gwy_fit_table_gather()

    gint
    gwy_fit_table_gather (GwyFitTable *table,
                          gdouble *values,
                          gdouble *errors,
                          gboolean *checked);

Gathers information about all parameters in a table of fit results.

All arguments `value` , `errors` and `checked` may be `NULL`. Use `gwy_fit_table_get_value()`, `gwy_fit_table_get_error()` and `gwy_fit_table_get_checked()` to obtain individual information.

#### Parameters

table | A table of fit results. |
values | Array to fill with parameter values, or `NULL`. |
errors | Array to fill with parameter errors, or `NULL`. |
checked | Array to fill with whether parameters are checked, or `NULL`. |

#### Returns

How many parameters are checked. If you want to know the number of unchecked paramers you need to subtract the return value from the table size.

## Types and Values

### struct GwyFitTable

    struct GwyFitTable;

### struct GwyFitTableClass

    struct GwyFitTableClass {
        GtkGridClass parent_class;

        void (*changed)(gint i);
        void (*activated)(gint i);
        void (*toggled)(gint i);
    };

## Signal Details

### The `“activated”` signal

    void
    user_function (GwyFitTable *gwyfittable,
                   int          arg1,
                   gpointer     user_data)

The ::activated signal is emitted whenever a value entry is activated (after parsing the value). It can only be emitted when values are edtiable.

#### Parameters

gwyfittable | The GwyFitTable which received the signal. |
arg1 | Index of the activated row. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“changed”` signal

    void
    user_function (GwyFitTable *gwyfittable,
                   int          arg1,
                   gpointer     user_data)

The ::changed signal is emitted whenever the user edits a value entry (not necessarily to a valid number). It can only be emitted when values are edtiable and is not generally emitted on programmatic updates.

#### Parameters

gwyfittable | The GwyFitTable which received the signal. |
arg1 | Index of the changed row. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“toggled”` signal

    void
    user_function (GwyFitTable *gwyfittable,
                   int          arg1,
                   gpointer     user_data)

The ::toggled signal is emitted whenever the row checkox is toggled. It can only be emitted when rows have checkboxes and is not generally emitted on programmatic changes.

#### Parameters

gwyfittable | The GwyFitTable which received the signal. |
arg1 | Index of the toggled row. |
user_data | user data set when the signal handler was connected. |

Flags: Run First