## module utils

module utils — Module utility functions

## Synopsis

    #include <app/gwymoduleutils.h>

    gchar*              (*GwySaveAuxiliaryCreate)           (gpointer user_data,
                                                             gssize *data_len);
    void                (*GwySaveAuxiliaryDestroy)          (gchar *data,
                                                             gpointer user_data);
    gboolean            gwy_save_auxiliary_data             (const gchar *title,
                                                             GtkWindow *parent,
                                                             gssize data_len,
                                                             const gchar *data);
    gboolean            gwy_save_auxiliary_with_callback    (const gchar *title,
                                                             GtkWindow *parent,
                                                             GwySaveAuxiliaryCreate create,
                                                             GwySaveAuxiliaryDestroy destroy,
                                                             gpointer user_data);
    void                gwy_set_data_preview_size           (GwyDataView *data_view,
                                                             gint max_size);

## Description

## Details

### GwySaveAuxiliaryCreate ()

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

The type of auxiliary saved data creation function.

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

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

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

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

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

Since 2.7