## module utils module utils — Module utility functions |

## Functions

gchar * | (*GwySaveAuxiliaryCreate) ()
void | (*GwySaveAuxiliaryDestroy) ()
gboolean | gwy_save_auxiliary_data ()
gboolean | gwy_save_auxiliary_with_callback ()
void | gwy_set_data_preview_size ()
gint | gwy_app_add_graph_or_curves ()
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_spectra ()

## 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 save, `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 save, `FALSE` if it was not saved for any reason (I/O error, cancellation, overwrite cancellation, etc.).

Since: 2.3

### 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_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_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 return `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 return `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 return `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_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