Gwyddion – Free SPM (AFM, SNOM/NSOM, STM, MFM, …) data analysis software

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 ()
gint gwy_app_add_graph_or_curves ()
void gwy_preview_surface_to_datafield ()
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_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 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_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_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_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_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

© David Nečas and Petr Klapetek

Home Download News Features Screenshots Documentation Communicate Participate Resources Publications Applications Site Map

Valid XHTML 1.0 Valid CSS