module utils: Gwyddion Application Library Reference Manual

## module utils module utils — Module utility functions |

## Functions

gchar * | (*GwySaveAuxiliaryCreate) ()
void | (*GwySaveAuxiliaryDestroy) ()
gboolean | gwy_save_auxiliary_data ()
gboolean | gwy_save_auxiliary_with_callback ()
gboolean | gwy_module_data_load ()
gboolean | gwy_module_data_save ()
FILE * | gwy_module_data_fopen ()
void | gwy_set_data_preview_size ()
gboolean | gwy_require_image_same_units ()
gboolean | gwy_require_square_image ()
GtkWidget * | gwy_create_preview ()
GtkWidget * | gwy_create_dialog_preview_hbox ()
GwySelection * | gwy_create_preview_vector_layer ()
void | gwy_param_active_page_link_to_notebook ()
GtkWidget * | gwy_create_expander_with_param ()
void | gwy_create_graph_xrange_with_params ()
GtkTreeModel * | gwy_create_inventory_model_without_default ()
void | gwy_select_in_filtered_inventory_treeeview ()
gint | gwy_app_add_graph_or_curves ()
void | gwy_preview_surface_to_datafield ()
GtkWidget * | gwy_app_wait_preview_data_field ()
void | gwy_set_gradient_for_residuals ()
gint | gwy_run_subdialog ()
gboolean | gwy_app_data_id_verify_channel ()
gboolean | gwy_app_data_id_verify_graph ()
gboolean | gwy_app_data_id_verify_volume ()
gboolean | gwy_app_data_id_verify_xyz ()
gboolean | gwy_app_data_id_verify_curve_map ()
gboolean | gwy_app_data_id_verify_spectra ()

## Types and Values

enum | GwyPreviewSurfaceFlags

## Includes

    #include <app/gwymoduleutils.h>

## Description

## Functions

### GwySaveAuxiliaryCreate ()

    gchar *
    (*GwySaveAuxiliaryCreate) (gpointer user_data,
                               gssize *data_len);

The type of auxiliary saved data creation function.

#### Parameters

user_data | The data passed to `gwy_save_auxiliary_with_callback()` as `user_data` . |
data_len | The length of the returned data in bytes. Leaving it unset has the same effect as setting it to a negative value. See `gwy_save_auxiliary_data()` for details. |

#### Returns

The data to save. It must not return `NULL`.

Since: 2.3

### GwySaveAuxiliaryDestroy ()

    void
    (*GwySaveAuxiliaryDestroy) (gchar *data,
                                gpointer user_data);

The type of auxiliary saved data destruction function.

#### Parameters

data | The data returned by the corresponding GwySaveAuxiliaryCreate function. |
user_data | The data passed to `gwy_save_auxiliary_with_callback()` as `user_data` . |

Since: 2.3

### gwy_save_auxiliary_data ()

    gboolean
    gwy_save_auxiliary_data (const gchar *title,
                             GtkWindow *parent,
                             gssize data_len,
                             const gchar *data);

Saves a report or other auxiliary data to a user specified file.

This is actually a simple `gwy_save_auxiliary_with_callback()` wrapper, see its description for details.

#### Parameters

title | File chooser dialog title. |
parent | Parent window for the file chooser dialog (may be `NULL`). |
data_len | The length of `data` in bytes. Pass -1 if `data` is text, it must be nul-terminated then and it will be saved in text mode (this matters if the operating system distinguishes between text and binary). A non-negative value causes the data to be saved as binary. |
data | The data to save. |

#### Returns

`TRUE` if the data was saved, `FALSE` if it was not saved for any reason.

Since: 2.3

### gwy_save_auxiliary_with_callback ()

    gboolean
    gwy_save_auxiliary_with_callback (const gchar *title,
                                      GtkWindow *parent,
                                      GwySaveAuxiliaryCreate create,
                                      GwySaveAuxiliaryDestroy destroy,
                                      gpointer user_data);

Saves a report or other auxiliary data to a user specified file.

#### Parameters

title | File chooser dialog title. |
parent | Parent window for the file chooser dialog (may be `NULL`). |
create | Function to create the data (it will not be called if the user cancels the saving). |
destroy | Function to destroy the data (if will be called iff `create` will be called), it may be `NULL`. |
user_data | User data passed to `create` and `destroy` . |

#### Returns

`TRUE` if the data was saved, `FALSE` if it was not saved for any reason (I/O error, cancellation, overwrite cancellation, etc.).

Since: 2.3

### gwy_module_data_load ()

    gboolean
    gwy_module_data_load (const gchar *modname,
                          const gchar *filename,
                          gchar **contents,
                          gsize *length,
                          GError **error);

Load module data file from the user directory.

The function wraps `g_file_get_contents()`, forming the full file name automatically.

The error can be from `G_FILE_ERROR` domain. Usually, however, you only need the return value and consider the file simply not existing yet when the function fails.

#### Parameters

modname | Module name (determines the subdirectory). |
filename | Name of the file to load. In GLib encoding, but it really should be just ASCII. |
contents | Location to store the allocated file contents. Use `g_free()` to free it. It is set to `NULL` when the file cannot be loaded. |
length | Location to the length of the contents in bytes, or `NULL`. |
error | Location for error, or `NULL`. |

#### Returns

`TRUE` if the file was loaded.

Since: 2.51

### gwy_module_data_save ()

    gboolean
    gwy_module_data_save (const gchar *modname,
                          const gchar *filename,
                          gchar *contents,
                          gssize length,
                          GError **error);

Saves module data file to the user directory.

The function wraps `g_file_set_contents()`, forming the full file name automatically and handling subdirectory creation.

The error can be from `G_FILE_ERROR` domain.

#### Parameters

modname | Module name (determines the subdirectory). |
filename | Name of the file to save. In GLib encoding, but it really should be just ASCII. |
contents | File contents to write. |
length | Length of `contents` , or -1 if it is a NUL-terminated string. |
error | Location for error, or `NULL`. |

#### Returns

`TRUE` if the file was saved.

Since: 2.51

### gwy_module_data_fopen ()

    FILE *
    gwy_module_data_fopen (const gchar *modname,
                           const gchar *filename,
                           const gchar *mode,
                           GError **error);

Opens a module data file in the user directory.

The function wraps `gwy_fopen()`, forming the full file name automatically and handling subdirectory creation.

The error can be from `G_FILE_ERROR` domain.

#### Parameters

modname | Module name (determines the subdirectory). |
filename | Name of the file to save. In GLib encoding, but it really should be just ASCII. |
mode | File open mode, as in `fopen()`. |
error | Location for error, or `NULL`. |

#### Returns

A file handle if the file was opened as requested, `NULL` on failure.

Since: 2.51

### gwy_set_data_preview_size ()

    void
    gwy_set_data_preview_size (GwyDataView *data_view,
                               gint max_size);

Sets up data view zoom to not exceed specified size.

Before calling this function, data keys have be set, data fields and layers have to be present and physically square mode set in the container. Sizing of both pixel-wise square and physically square displays is performed correctly.

#### Parameters

data_view | A data view used for module preview. |
max_size | Maximum allowed `data_view` size (width and height). |

Since: 2.7

### gwy_require_image_same_units ()

    gboolean
    gwy_require_image_same_units (GwyDataField *field,
                                  GwyContainer *data,
                                  gint id,
                                  const gchar *name);

Checks if data field has equal lateral and value units, possibly showing error message.

If the data field does not have the same lateral and value units a simple error message dialog is shown for `data` and `id` . This is only done if other GUI functions (like progress bars for waiting) are enabled.

#### Parameters

field | The data field to check. |
data | Data container with the data field. |
id | The id of `field` in `data` . |
name | Error message prefix, usually module function name. |

#### Returns

`TRUE` if the units are the same, `FALSE` otherwise.

Since: 2.59

### gwy_require_square_image ()

    gboolean
    gwy_require_square_image (GwyDataField *field,
                              GwyContainer *data,
                              gint id,
                              const gchar *name);

Checks if data field has the same horizontal and vertical pixel dimensions, possibly showing error message.

If the data field is not square a simple error message dialog is shown for `data` and `id` . This is only done if other GUI functions (like progress bars for waiting) are enabled.

#### Parameters

field | The data field to check. |
data | Data container with the data field. |
id | The id of `field` in `data` . |
name | Error message prefix, usually module function name. |

#### Returns

`TRUE` if the data field is square, `FALSE` otherwise.

Since: 2.59

### gwy_create_preview ()

    GtkWidget *
    gwy_create_preview (GwyContainer *data,
                        gint id,
                        gint size,
                        gboolean have_mask);

Creates and sets up a preview widget for use in modules.

#### Parameters

data | Data container with images to preview. |
id | Data id of preview image in `data` . |
size | Preview size. Prefrably one of the standard sizes. |
have_mask | `TRUE` if the preview will have mask and should be set up so. |

#### Returns

A new data view widget with the preview.

Since: 2.59

### gwy_create_dialog_preview_hbox ()

    GtkWidget *
    gwy_create_dialog_preview_hbox (GtkDialog *dialog,
                                    GwyDataView *dataview,
                                    gboolean pack_end);

Creates the typical data processing dialog hbox with a preview.

The box is added to the dialog.

#### Parameters

dialog | A data processing dialog. |
dataview | Preview data view, usually created by `gwy_create_preview()`. |
pack_end | `TRUE` to pack the data view to the end; `FALSE` to pack it to the start. |

#### Returns

A new GtkBox widget.

Since: 2.59

### gwy_create_preview_vector_layer ()

    GwySelection *
    gwy_create_preview_vector_layer (GwyDataView *dataview,
                                     gint id,
                                     const gchar *name,
                                     gint max_objects,
                                     gboolean editable);

Creates and sets up a vector layer for use in module previews.

The selection's key will have the form "/0/select/lcname", where `lcname` is the lowercase version of `name` . You can query the layer using GwyDataView functions.

Parameters `max_objects` and `editable` exist for convenience. The corresponding properties can be modified later.

In typical scenarios this function is also suitable for switching vector layers in the preview. Simply create a different layer and the current one will be discarded – this assumes you do not keep the old layer object around. Selections are kept in `dataview` 's data, so they will be automatically restored when switching back and forth.

#### Parameters

dataview | Preview data view, usually created by `gwy_create_preview()`. |
id | Data id of preview image in `dataview` 's data. |
name | Layer/selection type name, without the GwyLayer/GwySelection prefix. So usually "Point", "Line" or "Rectangle". |
max_objects | Maximum number of objects in the selection. |
editable | `TRUE` for a user-editable selection, `FALSE` to disable editing. |

#### Returns

The layer's selection. No reference is added; use `g_object_ref()` if you want to keep the selection around after the preview is destroyed.

Since: 2.61

### gwy_param_active_page_link_to_notebook ()

    void
    gwy_param_active_page_link_to_notebook
                                   (GwyParams *params,
                                    gint id,
                                    GtkNotebook *notebook);

Connects an active page parameter to a notebook.

This function should be called after the notebook was fully constructed. The active notebook page is set according to the parameter (clamping values that refer to non-existent pages). Future page switches will update the parameter value, allowing to simply save it to settings when the module dialog is finished.

#### Parameters

params | A parameter value set. |
id | Parameter identifier. |
notebook | A notebook widget. |

Since: 2.59

### gwy_create_expander_with_param ()

    GtkWidget *
    gwy_create_expander_with_param (const gchar *label,
                                    GwyParams *params,
                                    gint id);

Creates an expander linked to a boolean parameter.

This is a convenience function for making an expander whose state is remembered in settings. The parameter identified by `id` must be a boolean parameter. The expander initial state will be set from the parameter and, conversely, the parameter will be updated according to the expander state.

#### Parameters

label | Expander label markup. Usually boldface Options. |
params | A parameter value set. |
id | Parameter identifier. |

#### Returns

A newly created GtkExpander widget.

Since: 2.62

### gwy_create_graph_xrange_with_params ()

    void
    gwy_create_graph_xrange_with_params (GwyParamTable *partable,
                                         gint id_from,
                                         gint id_to,
                                         GwyGraph *graph,
                                         GwyGraphModel *gmodel);

Sets up a parameter table range row for horizontal graph selection.

A row with the two parameters is added to the table. The graph is set up for `GWY_GRAPH_STATUS_XSEL`. Synchronisation between the parameters and selection is set up.

The caller still needs to run `gwy_dialog_invalidate()` or use a similar mechanism when the parameter changes. Usually, any change to the selection will result in two updates, one for each parameter.

#### Parameters

partable | Set of parameter value controls. |
id_from | Parameter identifier for the beginning. |
id_to | Parameter identifier for the end. |
graph | Graph widget where the `x` -range will be selected. |
gmodel | Graph model used for determining the `x` range. May be `NULL` to use `graph` 's model, although this is not usually useful. |

Since: 2.63

### gwy_create_inventory_model_without_default ()

    GtkTreeModel *
    gwy_create_inventory_model_without_default
                                   (GwyInventoryStore *store);

Creates a tree model filter around an inventory store which hides the default item.

The model can be used to create resource lists without the default item if it is special and should not be shown to users. Remember you need to translate iters between the models using `gtk_tree_model_filter_convert_child_iter_to_iter()` and `gtk_tree_model_filter_convert_iter_to_child_iter()`.

#### Parameters

store | An inventory store. |

#### Returns

A newly created GtkTreeModelFilter wrapping `store` .

Since: 2.62

### gwy_select_in_filtered_inventory_treeeview ()

    void
    gwy_select_in_filtered_inventory_treeeview
                                   (GtkTreeView *treeview,
                                    const gchar *name);

Selects an item in filtered tree view showing an inventory.

Usually the tree view would show a GtkTreeModelFilter model created by `gwy_create_inventory_model_without_default()`. However, this function works also for other filter models around a GwyInventoryStore.

#### Parameters

treeview | A filtered tree view showing an inventory. |
name | Item name to select. |

Since: 2.62

### gwy_app_add_graph_or_curves ()

    gint
    gwy_app_add_graph_or_curves (GwyGraphModel *gmodel,
                                 GwyContainer *data,
                                 const GwyAppDataId *target_graph,
                                 gint colorstep);

Puts the curves of a graph to another graph if possible, or adds the graph as new.

If the units of `gmodel` are compatible with the units of the graph identified by `target_graph` the curves are copied to the target graph with `gwy_graph_model_append_curves()`.

In all other cases, including when `target_graph` does not refer to any existing graph, the graph model is added to `data` as a new graph.

Either way, the caller usually need to release its own reference afterwards.

This function is useful particularly in modules that create graphs and can be run non-interactively.

#### Parameters

gmodel | A graph model with curves to add. |
data | Data container where the graph would be added. |
target_graph | Graph where curves would be added. |
colorstep | Curve block size as in `gwy_graph_model_append_curves()`. |

#### Returns

The numerical identifier of the newly-created graph of one was created. Value -1 is returned if curves were added to `target_graph` .

Since: 2.41

### gwy_preview_surface_to_datafield ()

    void
    gwy_preview_surface_to_datafield (GwySurface *surface,
                                      GwyDataField *dfield,
                                      gint max_xres,
                                      gint max_yres,
                                      GwyPreviewSurfaceFlags flags);

Renders a preview of a XYZ data surface to a data field.

#### Parameters

surface | A surface representing a XYZ data. |
dfield | A data field to fill with `surface` preview. |
max_xres | Maximum width of the preview, it must be at least 2. |
max_yres | Maximum height of the preview, it must be at least 2. |
flags | Flags modifying the behaviour. |

Since: 2.46

### gwy_app_wait_preview_data_field ()

    GtkWidget *
    gwy_app_wait_preview_data_field (GwyDataField *dfield,
                                     GwyContainer *data,
                                     gint id);

Helper function for progressive animated preview.

This is a wrapper for `gwy_app_wait_set_preview_widget()` which creates a simple image preview displaying `dfield` . Call `gwy_data_field_data_changed()` on it to redraw the preview.

No preview is created if progress bars are disabled, see `gwy_app_wait_set_enabled()`.

#### Parameters

dfield | A data field used for preview. |
data | Data container with source image (or `NULL`). |
id | Source image id (or -1). |

#### Returns

The created GwyDataView with the preview (possibly `NULL` if not preview was actually created). Usually you can ignore it.

Since: 2.59

### gwy_set_gradient_for_residuals ()

    void
    gwy_set_gradient_for_residuals (GwyGradient *gradient,
                                    gdouble fullmin,
                                    gdouble fullmax,
                                    gdouble *dispmin,
                                    gdouble *dispmax);

Sets a false colour gradient suitably for fit residuals.

If the provided `dispmin` and `dispmax` are set to the mapping minimum and maximum, the resulting gradient will have neutral light colour for zero, a red gradient for postive values and a blue gradient for negative values. An effort is made to do something reasonable even when all values are positive or negative.

Usually `fullmin` and `fullmax` are simply the minimun and maximum, whereas `dispmin` and `dispmax` come from a function like `gwy_data_field_get_autorange()`. Altough the full range might also be used.

#### Parameters

gradient | A false colour gradient to modify. |
fullmin | Minimum residual value (presumably negative). |
fullmax | Maximum residual value (presumably positive). |
dispmin | Natural mapping minimum. It will be set to the fixed mapping minimum to actually use. |
dispmax | Natural mapping maximum. It will be set to the fixed mapping maximum to actually use. |

Since: 2.64

### gwy_run_subdialog ()

    gint
    gwy_run_subdialog (GtkDialog *dialog);

Runs a modal dialog transient for another another dialog, trying to work around bugs.

If both dialogs are modal, bad things can happen in some graphical environments, such as the second being hidden under the first one and inaccessible. This function attempts to work around this by temporarily setting the parent dialog (the one `dialog` is transient for) non-modal.

If the dialog is not transient for anything or its parent is not modal it is just run normally.

The function returns only after the dialog has been destroyed. Do not destroy it yourself.

#### Parameters

dialog | A data dialog to be run as modal. |

#### Returns

The response of `dialog` .

Since: 2.62

### gwy_app_data_id_verify_channel ()

    gboolean
    gwy_app_data_id_verify_channel (GwyAppDataId *id);

Checks if numerical channel identifiers correspond to an existing channel.

If either the data contained referenced in `id` or the channel does not exist the structure is cleared to `GWY_APP_DATA_ID_NONE` and the function returns `FALSE`. If it represents an existing channel it is kept intact and the function returns `TRUE`.

#### Parameters

id | Numerical identifiers of a channel in data managed by the data browser. |

#### Returns

Whether `id` refers to an existing channel now.

Since: 2.41

### gwy_app_data_id_verify_graph ()

    gboolean
    gwy_app_data_id_verify_graph (GwyAppDataId *id);

Checks if numerical graph identifiers correspond to an existing graph.

If either the data contained referenced in `id` or the graph model does not exist the structure is cleared to `GWY_APP_DATA_ID_NONE` and the function returns `FALSE`. If it represents an existing graph it is kept intact and the function returns `TRUE`.

#### Parameters

id | Numerical identifiers of a graph in data managed by the data browser. |

#### Returns

Whether `id` refers to an existing graph now.

Since: 2.41

### gwy_app_data_id_verify_volume ()

    gboolean
    gwy_app_data_id_verify_volume (GwyAppDataId *id);

Checks if numerical volume data identifiers correspond to existing volume data.

If either the data contained referenced in `id` or the volume data does not exist the structure is cleared to `GWY_APP_DATA_ID_NONE` and the function returns `FALSE`. If it represents existing volume data it is kept intact and the function returns `TRUE`.

#### Parameters

id | Numerical identifiers of volume data in data managed by the data browser. |

#### Returns

Whether `id` refers to existing volume data now.

Since: 2.41

### gwy_app_data_id_verify_xyz ()

    gboolean
    gwy_app_data_id_verify_xyz (GwyAppDataId *id);

Checks if numerical XYZ data identifiers correspond to existing XYZ data.

If either the data contained referenced in `id` or the XYZ data does not exist the structure is cleared to `GWY_APP_DATA_ID_NONE` and the function returns `FALSE`. If it represents existing XYZ data it is kept intact and the function returns `TRUE`.

#### Parameters

id | Numerical identifiers of XYZ data in data managed by the data browser. |

#### Returns

Whether `id` refers to existing XYZ data now.

Since: 2.46

### gwy_app_data_id_verify_curve_map ()

    gboolean
    gwy_app_data_id_verify_curve_map (GwyAppDataId *id);

Checks if numerical curve map data identifiers correspond to existing curve map data.

If either the data contained referenced in `id` or the curve map data does not exist the structure is cleared to `GWY_APP_DATA_ID_NONE` and the function returns `FALSE`. If it represents existing curve map data it is kept intact and the function returns `TRUE`.

#### Parameters

id | Numerical identifiers of curve map data in data managed by the data browser. |

#### Returns

Whether `id` refers to existing curve map data now.

Since: 2.46

### gwy_app_data_id_verify_spectra ()

    gboolean
    gwy_app_data_id_verify_spectra (GwyAppDataId *id);

Checks if numerical spectra identifiers correspond to existing spectra.

If either the data contained referenced in `id` or the spectra does not exist the structure is cleared to `GWY_APP_DATA_ID_NONE` and the function returns `FALSE`. If it represents existing spectra it is kept intact and the function return `TRUE`.

#### Parameters

id | Numerical identifiers of spectra in data managed by the data browser. |

#### Returns

Whether `id` refers to existing spectra now.

Since: 2.41

## Types and Values

### enum GwyPreviewSurfaceFlags

Type of behaviour modifying flags that can be passed to `gwy_preview_surface_to_datafield()`.

#### Members

GWY_PREVIEW_SURFACE_DENSITY | Render a point density map instead of the data. |
GWY_PREVIEW_SURFACE_FILL | Make the data field as large as the specified resolutions at least in one dimension (it can be prevented in the other by different aspect ratio). |

Since: 2.46