GwyFile: Gwyddion Application Library Reference Manual

## GwyFile GwyFile — Dictionary representing a data file |

## Functions

void | (*GwyFileTransferFunc) ()
GwyFile * | gwy_file_new ()
GwyFile * | gwy_file_new_in_construction ()
GwyFile * | gwy_file_copy ()
gint | gwy_file_add_image ()
gint | gwy_file_add_graph ()
gint | gwy_file_add_spectra ()
gint | gwy_file_add_volume ()
gint | gwy_file_add_xyz ()
gint | gwy_file_add_cmap ()
void | gwy_file_remove ()
guint | gwy_file_get_n_data ()
gint * | gwy_file_get_ids ()
gint * | gwy_file_get_idsv ()
void | gwy_file_sync_items ()
gint | gwy_file_copy_data ()
void | gwy_file_merge ()
void | gwy_file_set_link_quark ()
void | gwy_file_set_link ()
gboolean | gwy_file_value_is_link ()
GObject * | gwy_file_get_data ()
void | gwy_file_set_image ()
void | gwy_file_pass_image ()
GwyField * | gwy_file_get_image ()
void | gwy_file_set_image_mask ()
void | gwy_file_pass_image_mask ()
GwyNield * | gwy_file_get_image_mask ()
void | gwy_file_set_graph ()
void | gwy_file_pass_graph ()
GwyGraphModel * | gwy_file_get_graph ()
void | gwy_file_set_volume ()
void | gwy_file_pass_volume ()
GwyBrick * | gwy_file_get_volume ()
void | gwy_file_set_spectra ()
void | gwy_file_pass_spectra ()
GwySpectra * | gwy_file_get_spectra ()
void | gwy_file_set_xyz ()
void | gwy_file_pass_xyz ()
GwyScatter * | gwy_file_get_xyz ()
void | gwy_file_set_cmap ()
void | gwy_file_pass_cmap ()
GwyLawn * | gwy_file_get_cmap ()
void | gwy_file_set_title ()
void | gwy_file_pass_title ()
gchar * | gwy_file_get_display_title ()
const gchar * | gwy_file_get_title ()
gint * | gwy_file_find_by_title ()
void | gwy_file_set_visible ()
gboolean | gwy_file_get_visible ()
void | gwy_file_pass_meta ()
GwyDict * | gwy_file_get_meta ()
void | gwy_file_set_palette ()
const gchar * | gwy_file_get_palette ()
void | gwy_file_set_color_mapping ()
GwyColorMappingType | gwy_file_get_color_mapping ()
void | gwy_file_set_fixed_range ()
gboolean | gwy_file_get_fixed_range ()
void | gwy_file_remove_selections ()
void | gwy_file_remove_logs ()
const gchar * | gwy_file_get_format_name ()
const gchar * | gwy_file_get_filename_sys ()
gint | gwy_file_get_id ()
GQuark | gwy_file_key_filename ()
GQuark | gwy_file_key_data ()
GQuark | gwy_file_key_image ()
GQuark | gwy_file_key_image_mask ()
GQuark | gwy_file_key_image_picture ()
GQuark | gwy_file_key_graph ()
GQuark | gwy_file_key_spectra ()
GQuark | gwy_file_key_volume ()
GQuark | gwy_file_key_volume_mask ()
GQuark | gwy_file_key_xyz ()
GQuark | gwy_file_key_cmap ()
GQuark | gwy_file_key_image_title ()
GQuark | gwy_file_key_image_color_mapping ()
GQuark | gwy_file_key_image_range_min ()
GQuark | gwy_file_key_image_range_max ()
GQuark | gwy_file_key_image_palette ()
GQuark | gwy_file_key_image_meta ()
GQuark | gwy_file_key_image_real_square ()
GQuark | gwy_file_key_image_selection ()
GQuark | gwy_file_key_image_mask_color ()
GQuark | gwy_file_key_volume_mask_color ()
GQuark | gwy_file_key_volume_title ()
GQuark | gwy_file_key_volume_picture ()
GQuark | gwy_file_key_volume_palette ()
GQuark | gwy_file_key_volume_meta ()
GQuark | gwy_file_key_xyz_title ()
GQuark | gwy_file_key_xyz_palette ()
GQuark | gwy_file_key_xyz_meta ()
GQuark | gwy_file_key_xyz_picture ()
GQuark | gwy_file_key_cmap_title ()
GQuark | gwy_file_key_cmap_palette ()
GQuark | gwy_file_key_cmap_meta ()
GQuark | gwy_file_key_cmap_picture ()
GQuark | gwy_file_key_cmap_real_square ()
gboolean | gwy_parse_file_key ()
GQuark | gwy_form_file_key ()
const gchar * | gwy_form_string_file_key ()
GQuark | gwy_file_error_quark ()

## Types and Values

#define | GWY_FILE_PREFIX_IMAGE
#define | GWY_FILE_PREFIX_GRAPH
#define | GWY_FILE_PREFIX_SPECTRA
#define | GWY_FILE_PREFIX_VOLUME
#define | GWY_FILE_PREFIX_XYZ
#define | GWY_FILE_PREFIX_CMAP
#define | GWY_FILE_ID_NONE
#define | GWY_FILE_ERROR
enum | GwyFileError
enum | GwyDataKind
enum | GwyFilePiece
#define | GWY_FILE_ITEM_PALETTE
#define | GWY_FILE_ITEM_RANGE
#define | GWY_FILE_ITEM_COLOR_MAPPING
#define | GWY_FILE_ITEM_REAL_SQUARE
#define | GWY_FILE_ITEM_MASK
#define | GWY_FILE_ITEM_MASK_COLOR
#define | GWY_FILE_ITEM_SELECTIONS
#define | GWY_FILE_ITEM_META
#define | GWY_FILE_ITEM_PICTURE
#define | GWY_FILE_ITEM_VIEW
#define | GWY_FILE_ITEM_TITLE
| GwyFileKeyParsed
struct | GwyFile
struct | GwyFileClass

## Object Hierarchy

        GObject
        ╰── GwyDict
            ╰── GwyFile

## Implemented Interfaces

GwyFile implements GwySerializable.

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

GwyFile is a subclass of GwyDict, assuming a specific organisation of items inside to represent scanning probe microscopy data, more specifically a Gwyddion GWY file.

The class implements GwySerializable `copy()` and `assign()` methods. A convenience wrapper `gwy_file_copy()` is provided only for the first one. Assigning files by value is less efficient than simply destroying the existing GwyFile and creating a new data file. It also generates lots of signals about changed items. So, generally, do not do it.

## Functions

### GwyFileTransferFunc()

    void
    (*GwyFileTransferFunc) (GwyFile *source,
                            GwyFile *destination,
                            GwyDataKind data_kind,
                            gint source_id,
                            gint destination_id,
                            gpointer user_data);

Type of callback function for file item transfer.

#### Parameters

source | Source file. |
destination | Destination file. |
data_kind | Type of the data object. |
source_id | Numerical id of a data in source file. |
destination_id | Numerical id of a data in destination file. |
user_data | User data passed to the function. | [closure]

### gwy_file_new()

    GwyFile *
    gwy_file_new (void);

Creates a new GwyFile.

[constructor]

#### Returns

A new data file container.

[transfer full]

### gwy_file_new_in_construction()

    GwyFile *
    gwy_file_new_in_construction (void);

Creates a new GwyFile and marks is as being in construction.

This is a convenience function calling `gwy_dict_start_construction()` on the newly created file.

[constructor]

#### Returns

A new data file container.

[transfer full]

### gwy_file_copy()

    GwyFile *
    gwy_file_copy (GwyFile *file);

Create a new data file as a copy of an existing one.

This function is a convenience `gwy_serializable_copy()` wrapper.

#### Parameters

file | A data file to duplicate. |

#### Returns

A copy of the data file.

[transfer full]

### gwy_file_add_image()

    gint
    gwy_file_add_image (GwyFile *file,
                        GwyField *field);

Adds a data field representing an image to a file data container.

The file cannot be in construction (see `gwy_dict_start_construction()`). In particular, this function is not suitable for the import of data from third party file formats, use `gwy_file_pass_image()`.

A new unused id is assigned to the image and returned. Generally, it is the lowest integer larger than any existing image id (however, there are no specific guarantees).

The image is not immediately shown in a new window when the GUI is running. Use `gwy_file_set_visible()` to show it, preferrably after setting or synchronising visualisation settings like the colour mapping.

#### Parameters

file | A data file container to add `field` to. |
field | Data field representing an image to add. |

#### Returns

The id of the newly added image in the file.

### gwy_file_add_graph()

    gint
    gwy_file_add_graph (GwyFile *file,
                        GwyGraphModel *graph);

Adds a graph model representing a graph to a file data container.

The file cannot be in construction (see `gwy_dict_start_construction()`). In particular, this function is not suitable for the import of data from third party file formats, use `gwy_file_pass_graph()`.

A new unused id is assigned to the graph and returned. Generally, it is the lowest integer larger than any existing graph id (however, there are no specific guarantees).

The graph is not immediately shown in a new window when the GUI is running. Use `gwy_file_set_visible()` to show it, preferrably after setting or synchronising other settings.

#### Parameters

file | A data file container to add `graph` to. |
graph | Graph model to add. |

#### Returns

The id of the newly added graph in the file.

### gwy_file_add_spectra()

    gint
    gwy_file_add_spectra (GwyFile *file,
                          GwySpectra *spectra);

Adds a spectra representing a single point spectra to a file data container.

The file cannot be in construction (see `gwy_dict_start_construction()`). In particular, this function is not suitable for the import of data from third party file formats, use `gwy_file_pass_spectra()`.

A new unused id is assigned to the spectra and returned. Generally, it is the lowest integer larger than any existing spectra id (however, there are no specific guarantees).

The spectra are not immediately shown in a new window when the GUI is running. Use `gwy_file_set_visible()` to show it, preferrably after setting or synchronising other settings.

#### Parameters

file | A data file container to add `spectra` to. |
spectra | Single point spectra to add. |

#### Returns

The id of the newly added spectra in the file.

### gwy_file_add_volume()

    gint
    gwy_file_add_volume (GwyFile *file,
                         GwyBrick *brick,
                         GwyField *preview);

Adds a data brick representing an volume data to a file data container.

The file cannot be in construction (see `gwy_dict_start_construction()`). In particular, this function is not suitable for the import of data from third party file formats, use `gwy_file_pass_volume()`.

A new unused id is assigned to the volume data and returned. Generally, it is the lowest integer larger than any existing volume data id (however, there are no specific guarantees).

The volume data is not immediately shown in a new window when the GUI is running. Use `gwy_file_set_visible()` to show it, preferrably after setting or synchronising visualisation settings like the colour mapping.

#### Parameters

file | A data file container to add `brick` to. |
brick | Data brick to add. |
preview | Data field to use as the preview. You can also pass `NULL` to create a preview automatically. | [nullable]

#### Returns

The id of the newly added volume data in the file.

### gwy_file_add_xyz()

    gint
    gwy_file_add_xyz (GwyFile *file,
                      GwyScatter *scatter);

Adds a data scatter representing an XYZ data to a file data container.

The file cannot be in construction (see `gwy_dict_start_construction()`). In particular, this function is not suitable for the import of data from third party file formats, use `gwy_file_pass_xyz()`.

A new unused id is assigned to the XYZ data and returned. Generally, it is the lowest integer larger than any existing XYZ data id (however, there are no specific guarantees).

The XYZ data is not immediately shown in a new window when the GUI is running. Use `gwy_file_set_visible()` to show it, preferrably after setting or synchronising visualisation settings like the colour mapping.

#### Parameters

file | A data file container to add `scatter` to. |
scatter | XYZ data scatter to add. |

#### Returns

The id of the newly added XYZ data in the file.

### gwy_file_add_cmap()

    gint
    gwy_file_add_cmap (GwyFile *file,
                       GwyLawn *lawn,
                       GwyField *preview);

Adds a data lawn representing an curve map data to a file data container.

The file cannot be in construction (see `gwy_dict_start_construction()`). In particular, this function is not suitable for the import of data from third party file formats, use `gwy_file_pass_cmap()`.

A new unused id is assigned to the curve map data and returned. Generally, it is the lowest integer larger than any existing curve map data id (however, there are no specific guarantees).

The curve map data is not immediately shown in a new window when the GUI is running. Use `gwy_file_set_visible()` to show it, preferrably after setting or synchronising visualisation settings like the colour mapping.

#### Parameters

file | A data file container to add `lawn` to. |
lawn | Data lawn to add. |
preview | Data field to use as the preview. You can also pass `NULL` to create a preview automatically. | [nullable]

#### Returns

The id of the newly added curve map data in the file.

### gwy_file_remove()

    void
    gwy_file_remove (GwyFile *file,
                     GwyDataKind data_kind,
                     gint id);

Removes a data object from a file data contained together with all auxiliary information.

The function can be used with files in construction (see `gwy_dict_new_in_construction()`), although usually there is no reason for it.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data in file. |

### gwy_file_get_n_data()

    guint
    gwy_file_get_n_data (GwyFile *file,
                         GwyDataKind data_kind);

Gets the number of data objects of a given kind in a file.

This is the preferred function for checking whether there are any data of given kind at all.

The file must not be in construction.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |

#### Returns

The number of data items.

### gwy_file_get_ids()

    gint *
    gwy_file_get_ids (GwyFile *file,
                      GwyDataKind data_kind);

Gets the list of ids of all objects of given kind in a file.

When there are no data objects of given kind, a non-`NULL` array is still returned. It contains the single value -1.

The file must not be in construction.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |

#### Returns

A newly allocated, −1-terminated list of all the ids.

### gwy_file_get_idsv()

    gint *
    gwy_file_get_idsv (GwyFile *file,
                       GwyDataKind data_kind,
                       guint *n);

Gets the list of ids of all objects of given kind in a file.

The returned pointer remains valid only as long as `file` exists and data objects of kind `data_kind` are not added or removed. The array is not −1-terminated so unless you obtain the number of data objects by other means you need to get `n` .

The file must not be in construction.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
n | Location to store the number of returned ids. | [optional][inout]

#### Returns

A newly allocated list of all the ids with `n` elements.

### gwy_file_sync_items()

    void
    gwy_file_sync_items (GwyFile *source,
                         GwyDataKind src_data_kind,
                         gint from_id,
                         GwyFile *destination,
                         GwyDataKind dest_data_kind,
                         gint to_id,
                         guint64 items,
                         gboolean delete_too);

Synchronizes auxiliary data items between data file containers.

Use a bit mask formed from predefined constants such as `GWY_FILE_ITEM_REAL_SQUARE` or unsigned 1 shifted left by `GWY_FILE_PIECE_REAL_SQUARE` for the flags. Note that the 1 may need to be 64bit if you are doing the shifting yourself.

The most common use is with `dest_data_kind` = `src_data_kind` . Nevertheless, some items make sense for multiple data kinds and can be used with `dest_data_kind` ≠ `src_data_kind` . For example, the false colour gradient can be synchronised between an image and volume data.

#### Parameters

source | Source data file container. |
src_data_kind | Type of source data object. |
from_id | Source numerical id of data object. |
destination | Destination data file container. |
dest_data_kind | Type of destination data object. |
to_id | Destination numerical id of data object. |
items | Flags indicating the items to synchronise. |
delete_too | `TRUE` to delete items in target if source does not contain them, `FALSE` to copy only. |

### gwy_file_copy_data()

    gint
    gwy_file_copy_data (GwyFile *source,
                        GwyDataKind data_kind,
                        gint id,
                        GwyFile *destination);

Completely duplicates data in a data file container including all auxiliary information.

The source and destination files may be the same file. Visibility is not copied; the new data object is created as not visible. The log is not copied either. See also `gwy_data_browser_copy_data()` for somewhat a more high-level function for copying data in managed files.

#### Parameters

source | Source data file container. |
data_kind | Type of data object. |
id | Source numerical id of data object. |
destination | Destination data file container. |

#### Returns

The id of the newly added data in file `destination` .

### gwy_file_merge()

    void
    gwy_file_merge (GwyFile *file,
                    GwyFile *otherfile,
                    GwyFileTransferFunc merged,
                    gpointer user_data,
                    GDestroyNotify destroy);

Merges a data file container into another.

The caller passes its reference on `otherfile` to the function. The function releases the reference when it is finished. The underlying assumption is that `otherfile` is then destroyed. This enables an efficient merge as objects in `otherfile` can simply be added to `file` and expensive copying is avoided. Keeping `otherfile` around after merging is not recommended. Use `gwy_file_copy()` on `otherfile` beforhand if you want to add a copy of all its data to `file` .

This is a low-level function and does not handle logs. The caller can use the `merge` callback to copy logs and add new log entries for the merge operation if appropriate.

If `merged` is given, it is called for each transferred item after the transfer is completely done, but before visibility is set (i.e. before any widgets would be created if `file` is displayed in the GUI). Source file will be `otherfile` and destination file `file` . Since the transfer is already done, `merge` can modify the `file` . However, caution is advised as changes can have cascading effects.

#### Parameters

file | A data file container. |
otherfile | A file to merge into `file` . It must not be `file` itself and must not be managed by the data browser. | [transfer full]
merged | Optional function to call for each copied data item. | [nullable][scope call][closure user_data][destroy destroy]
user_data | Data passed to `merged` . |
destroy | Function to destroy user data when done, possibly `NULL`. |

### gwy_file_set_link_quark()

    void
    gwy_file_set_link_quark (GwyFile *file,
                             GQuark key,
                             GQuark value);

Creates a link in a data file container, specified using quarks.

The link value is always a string. Use this function instead of `gwy_file_set_link()` for convenience when you already have quarks. See its description for remarks.

#### Parameters

file | A data file container. |
key | Link source in `file` , as a quark. |
value | Link target in `file` , as a quark. |

### gwy_file_set_link()

    void
    gwy_file_set_link (GwyFile *file,
                       const gchar *key,
                       const gchar *value);

Creates a link in a data file container, specified using string keys.

Link is a string which holds the key of some other data in the file. Its value can be obtained using `gwy_dict_get_string()` or `gwy_dict_gis_string()`. The difference between links and plain strings is that when data are moved around or merged, they can be automatically updated to point to the new location.

Modifying the value by a GwyDict function, even to another string, makes it a non-link. Therefore, do not do it. There are no file items that can be both links and non-links. One of the two options is always invalid.

#### Parameters

file | A data file container. |
key | Link source in `file` , as a string. |
value | Link target in `file` , as a string. |

### gwy_file_value_is_link()

    gboolean
    gwy_file_value_is_link (GwyFile *file,
                            const gchar *key);

Checks if a value in a data file container is a link.

It is not an error to call this function with keys which do not corresponds to strings at all. It will return `FALSE`.

#### Parameters

file | A data file container. |
key | Key sin `file` , as a string. |

#### Returns

`TRUE` if `key` is a link, `FALSE` if it is not.

### gwy_file_get_data()

    GObject *
    gwy_file_get_data (GwyFile *file,
                       GwyDataKind data_kind,
                       gint id);

Gets the primary data object of specified type and id.

The type of the returned object is whatever is appropriate for given data kind. This function is mainly useful when you need to check generically a data object for some data management purpose. For data processing, usually functions such as `gwy_file_get_image()` or `gwy_file_get_volume()` are preferred as they return a specific type.

It is not an error to ask for an object which does not exist in the file. The function returns `NULL` in such case. However, `data_kind` and `id` must be valid in principle.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of data in file. |

#### Returns

The main data object in the file corresponding to `data_kind` and `id` , or `NULL` if it does not exist.

[transfer none][nullable]

### gwy_file_set_image()

    void
    gwy_file_set_image (GwyFile *file,
                        gint id,
                        GwyField *field);

Sets a data field as the image in a data file container with no ownership transfer.

#### Parameters

file | A data file container. |
id | Numerical id of an image in `file` . |
field | Data field representing an image. | [transfer none]

### gwy_file_pass_image()

    void
    gwy_file_pass_image (GwyFile *file,
                         gint id,
                         GwyField *field);

Sets a data field as the image in a data file container passing the ownership to the file.

#### Parameters

file | A data file container. |
id | Numerical id of an image in `file` . |
field | Data field representing an image. | [transfer full]

### gwy_file_get_image()

    GwyField *
    gwy_file_get_image (GwyFile *file,
                        gint id);

Gets a data field representing an image in a data file container.

It is not an error to ask for an image which does not exist in the file. The function returns `NULL` in such case. However, `id` must be valid (non-negative).

#### Parameters

file | A data file container. |
id | Numerical id of an image in `file` . |

#### Returns

Data field representing an image, or `NULL`.

[transfer none][nullable]

### gwy_file_set_image_mask()

    void
    gwy_file_set_image_mask (GwyFile *file,
                             gint id,
                             GwyNield *mask);

Sets a number field as the image mask in a data file container with no ownership transfer.

If `mask` is passed as `NULL`, any existing mask object is removed.

#### Parameters

file | A data file container. |
id | Numerical id of an image mask in `file` . |
mask | Data field representing a mask. | [transfer none][nullable]

### gwy_file_pass_image_mask()

    void
    gwy_file_pass_image_mask (GwyFile *file,
                              gint id,
                              GwyNield *mask);

Sets a number field as the image mask in a data file container passing the ownership to the file.

#### Parameters

file | A data file container. |
id | Numerical id of an image mask in `file` . |
mask | Data field representing a mask. | [transfer full]

### gwy_file_get_image_mask()

    GwyNield *
    gwy_file_get_image_mask (GwyFile *file,
                             gint id);

Gets a number field representing the image mask in a data file container.

It is not an error to ask for a mask which does not exist in the file. The function returns `NULL` in such case. However, `id` must be valid (non-negative).

#### Parameters

file | A data file container. |
id | Numerical id of an image mask in `file` . |

#### Returns

Data field representing the mask, or `NULL`.

[transfer none][nullable]

### gwy_file_set_graph()

    void
    gwy_file_set_graph (GwyFile *file,
                        gint id,
                        GwyGraphModel *gmodel);

Sets a graph model as the graph in a data file container with no ownership transfer.

#### Parameters

file | A data file container. |
id | Numerical id of a graph in `file` . |
gmodel | Graph model representing a graph. | [transfer none]

### gwy_file_pass_graph()

    void
    gwy_file_pass_graph (GwyFile *file,
                         gint id,
                         GwyGraphModel *gmodel);

Sets a graph model as the graph in a data file container passing the ownership to the file.

#### Parameters

file | A data file container. |
id | Numerical id of a graph in `file` . |
gmodel | Graph model representing a graph. | [transfer full]

### gwy_file_get_graph()

    GwyGraphModel *
    gwy_file_get_graph (GwyFile *file,
                        gint id);

Gets a graph model representing a graph in a data file container.

It is not an error to ask for a graph which does not exist in the file. The function returns `NULL` in such case. However, `id` must be valid (non-negative).

#### Parameters

file | A data file container. |
id | Numerical id of a graph in `file` . |

#### Returns

Graph model representing a graph, or `NULL`.

[transfer none][nullable]

### gwy_file_set_volume()

    void
    gwy_file_set_volume (GwyFile *file,
                         gint id,
                         GwyBrick *brick);

Sets a data brick as the volume data in a data file container with no ownership transfer.

#### Parameters

file | A data file container. |
id | Numerical id of volume data in `file` . |
brick | Data brick representing volume data. | [transfer none]

### gwy_file_pass_volume()

    void
    gwy_file_pass_volume (GwyFile *file,
                          gint id,
                          GwyBrick *brick);

Sets a data brick as the volume data in a data file container passing the ownership to the file.

#### Parameters

file | A data file container. |
id | Numerical id of volume data in `file` . |
brick | Data brick representing volume data. | [transfer full]

### gwy_file_get_volume()

    GwyBrick *
    gwy_file_get_volume (GwyFile *file,
                         gint id);

Gets a data brick representing volume data in a data file container.

It is not an error to ask for volume data which does not exist in the file. The function returns `NULL` in such case. However, `id` must be valid (non-negative).

#### Parameters

file | A data file container. |
id | Numerical id of volume data in `file` . |

#### Returns

Data brick representing volume data, or `NULL`.

[transfer none][nullable]

### gwy_file_set_spectra()

    void
    gwy_file_set_spectra (GwyFile *file,
                          gint id,
                          GwySpectra *spectra);

Sets a spectra object as the single point spectra in a data file container with no ownership transfer.

#### Parameters

file | A data file container. |
id | Numerical id of single point spectra in `file` . |
spectra | Spectra object representing single point spectra. | [transfer none]

### gwy_file_pass_spectra()

    void
    gwy_file_pass_spectra (GwyFile *file,
                           gint id,
                           GwySpectra *spectra);

Sets a spectra object as the single point spectra in a data file container passing the ownership to the file.

#### Parameters

file | A data file container. |
id | Numerical id of single point spectra in `file` . |
spectra | Spectra object representing single point spectra. | [transfer full]

### gwy_file_get_spectra()

    GwySpectra *
    gwy_file_get_spectra (GwyFile *file,
                          gint id);

Gets a spectra object representing single point spectra in a data file container.

It is not an error to ask for single point spectra which does not exist in the file. The function returns `NULL` in such case. However, `id` must be valid (non-negative).

#### Parameters

file | A data file container. |
id | Numerical id of single point spectra in `file` . |

#### Returns

Spectra object representing single point spectra, or `NULL`.

[transfer none][nullable]

### gwy_file_set_xyz()

    void
    gwy_file_set_xyz (GwyFile *file,
                      gint id,
                      GwyScatter *scatter);

Sets a scatter object as the XYZ data in a data file container with no ownership transfer.

#### Parameters

file | A data file container. |
id | Numerical id of XYZ data in `file` . |
scatter | Scatter object representing XYZ data. | [transfer none]

### gwy_file_pass_xyz()

    void
    gwy_file_pass_xyz (GwyFile *file,
                       gint id,
                       GwyScatter *scatter);

Sets a scatter object as the XYZ data in a data file container passing the ownership to the file.

#### Parameters

file | A data file container. |
id | Numerical id of XYZ data in `file` . |
scatter | Scatter object representing XYZ data. | [transfer full]

### gwy_file_get_xyz()

    GwyScatter *
    gwy_file_get_xyz (GwyFile *file,
                      gint id);

Gets a scatter object representing XYZ data in a data file container.

It is not an error to ask for XYZ data which does not exist in the file. The function returns `NULL` in such case. However, `id` must be valid (non-negative).

#### Parameters

file | A data file container. |
id | Numerical id of XYZ data in `file` . |

#### Returns

Scatter object representing XYZ data, or `NULL`.

[transfer none][nullable]

### gwy_file_set_cmap()

    void
    gwy_file_set_cmap (GwyFile *file,
                       gint id,
                       GwyLawn *lawn);

Sets a data lawn as the a curve map in a data file container with no ownership transfer.

#### Parameters

file | A data file container. |
id | Numerical id of a curve map in `file` . |
lawn | Data lawn representing a curve map. | [transfer none]

### gwy_file_pass_cmap()

    void
    gwy_file_pass_cmap (GwyFile *file,
                        gint id,
                        GwyLawn *lawn);

Sets a data lawn as the a curve map in a data file container passing the ownership to the file.

#### Parameters

file | A data file container. |
id | Numerical id of a curve map in `file` . |
lawn | Data lawn representing a curve map. | [transfer full]

### gwy_file_get_cmap()

    GwyLawn *
    gwy_file_get_cmap (GwyFile *file,
                       gint id);

Gets a data lawn representing a curve map in a data file container.

It is not an error to ask for a curve map which does not exist in the file. The function returns `NULL` in such case. However, `id` must be valid (non-negative).

#### Parameters

file | A data file container. |
id | Numerical id of a curve map in `file` . |

#### Returns

Data lawn representing a curve map, or `NULL`.

[transfer none][nullable]

### gwy_file_set_title()

    void
    gwy_file_set_title (GwyFile *file,
                        GwyDataKind data_kind,
                        gint id,
                        const gchar *name,
                        gboolean numbered);

Sets the title of a data object in a file data container.

This is a convenience wrapper, abstracting setting the title for different data types.

Depending on `numbered` , the id is possibly appended to the name. When `name` is `NULL`, id is always appended, regardless of `numbered` .

Passing `numbered` as `TRUE` is generally recommended for derived data computed in modules with generic names such as ‘Drift-corrected’. Without numbering there would be lots of data with the same name, making it difficult to distinguish them.

For channels in imported files, which generally carry file-unique names, it is fine to not append numbers. See also `gwy_file_pass_title()` which may be more useful on file import.

The function can be used with files in construction (see `gwy_dict_new_in_construction()`), provided that the tiltle is set after the primary data object.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of an existing data object in `file` . |
name | New title to set. It can be `NULL` to use something like ‘Untitled’. | [nullable]
numbered | `TRUE` to append the numeric id to the title, `FALSE` to set it as-is. |

### gwy_file_pass_title()

    void
    gwy_file_pass_title (GwyFile *file,
                         GwyDataKind data_kind,
                         gint id,
                         gchar *name);

Sets the title of a data object in a file data container, passing string ownership.

This is a convenience wrapper, abstracting setting the title for different data types.

Unlike in `gwy_file_set_title()`, `name` is always used unmodified and may not be `NULL`. Uts ownership is passed to the file (or other object).

The function can be used with files in construction (see `gwy_dict_new_in_construction()`), provided that the tiltle is set after the primary data object.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of an existing data object in `file` . |
name | Title to set. It may not be `NULL`. | [transfer full]

### gwy_file_get_display_title()

    gchar *
    gwy_file_get_display_title (GwyFile *file,
                                GwyDataKind data_kind,
                                gint id);

Gets a suitable title of a data object in a file data container.

The function returns a non-`NULL` string even if no data title has been set or is empty. It is something like ‘Untitled 123’ in such case. It makes it useful for having at least some identifying label for all data objects, regardless if they have any title set. However, if you really need to know whether a title has been set use `gwy_file_get_title()`.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |

#### Returns

The title as a newly allocated string.

### gwy_file_get_title()

    const gchar *
    gwy_file_get_title (GwyFile *file,
                        GwyDataKind data_kind,
                        gint id);

Gets the title of a data object in a file data container.

If no title is set this function can return `NULL`. Use `gwy_file_get_display_title()` if you want to always get some useful identifying string.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |

#### Returns

The title as a string owned by the corresponding data object.

[nullable]

### gwy_file_find_by_title()

    gint *
    gwy_file_find_by_title (GwyFile *file,
                            GwyDataKind data_kind,
                            const gchar *titleglob);

Gets the list of all data objects in a data file container whose titles match the specified pattern.

If titleglob is `NULL` the function is identical to `gwy_file_get_ids()`.

For data objects with no title the synthetic title produced by `gwy_file_get_display_title()` is used.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
titleglob | Pattern, as used by GPatternSpec, to match the data titles against. | [nullable]

#### Returns

A newly allocated, −1-terminated list of all the ids.

### gwy_file_set_visible()

    void
    gwy_file_set_visible (GwyFile *file,
                          GwyDataKind data_kind,
                          gint id,
                          gboolean visible);

Sets the visibility of a data item in a data file container.

The function can be used to either just mark the visibility status of data objects in files or actually control the visibility in files open in the GUI. Closing the last window displaying any data of a particular file can close the file entirely.

The function can be used with files in construction (see `gwy_dict_new_in_construction()`).

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |
visible | `TRUE` to display the data in a window, `FALSE` to hide it. |

### gwy_file_get_visible()

    gboolean
    gwy_file_get_visible (GwyFile *file,
                          GwyDataKind data_kind,
                          gint id);

Gets the visivility status of a data object in a data file container.

The function returning `TRUE` does not mean the data object is actually displayed in some window. It simply returns the value of the flag and can be used with standalone files with no GUI running.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |

#### Returns

`TRUE` if the object is marked visible, `FALSE` otherwise.

### gwy_file_pass_meta()

    void
    gwy_file_pass_meta (GwyFile *file,
                        GwyDataKind data_kind,
                        gint id,
                        GwyDict *meta);

Sets the metadata for a data object in a data file container.

This is a convenience wrapper for `gwy_dict_pass_object()` with slightly more checking. It can be used with files in construction (see `gwy_dict_new_in_construction()`) and is most useful in file import modules.

If `meta` has still the in-construction flag set, the function calls `gwy_dict_finish_construction()` on it. Preferably set the metadata after `meta` has been filled with values.

Analogous function `gwy_file_set_meta()` is missing intentionally. It creates too big temptation to use the same object as metadata for multiple data, which is an error. Use GwyFile functions to get the key and GwyDict functions to set the object if you really need to keep the metadata around after puttng it to the file. The useful idioms are the following.

With a function which creates metadata:

    1
    gwy_file_pass_meta(file, GWY_FILE_IMAGE, id, create_metadata(...));

With the same metadata for many data items:

    1
    2
    3
    4
    5
    6
    7
    meta = create_metadata(...);
    ...
    gwy_file_pass_meta(file, GWY_FILE_IMAGE, id1, gwy_dict_copy(meta));
    gwy_file_pass_meta(file, GWY_FILE_IMAGE, id2, gwy_dict_copy(meta));
    gwy_file_pass_meta(file, GWY_FILE_IMAGE, id3, gwy_dict_copy(meta));
    ...
    g_object_unref(meta);

With optional metadata:

    1
    2
    3
    4
    5
    6
    meta = gwy_dict_new();
    ...
    if (gwy_dict_get_n_items(meta))
        gwy_file_pass_meta(file, GWY_FILE_IMAGE, id, meta));
    else
        g_object_unref(meta);

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |
meta | A data container holding data object's metadata. The reference is passed to `file` . | [transfer full]

### gwy_file_get_meta()

    GwyDict *
    gwy_file_get_meta (GwyFile *file,
                       GwyDataKind data_kind,
                       gint id);

Gets the metadata for a data object in a data file container.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |

#### Returns

A data container holding data object's metadata.

[transfer none][nullable]

### gwy_file_set_palette()

    void
    gwy_file_set_palette (GwyFile *file,
                          GwyDataKind data_kind,
                          gint id,
                          const gchar *name);

Sets the gradient name for data visualisation in a data file container.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |
name | Gradient name. It can be `NULL` to unset the gradient (causing the current default gradient to be used). | [nullable]

### gwy_file_get_palette()

    const gchar *
    gwy_file_get_palette (GwyFile *file,
                          GwyDataKind data_kind,
                          gint id);

Gets the gradient name for data visualisation in a data file container.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |

#### Returns

The gradient name as a string owned by the file. It can be `NULL` if no gradient is set.

[nullable]

### gwy_file_set_color_mapping()

    void
    gwy_file_set_color_mapping (GwyFile *file,
                                GwyDataKind data_kind,
                                gint id,
                                GwyColorMappingType mapping);

Sets the colour mapping type for data visualisation in a data file container.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |
mapping | Mapping type to set. |

### gwy_file_get_color_mapping()

    GwyColorMappingType
    gwy_file_get_color_mapping (GwyFile *file,
                                GwyDataKind data_kind,
                                gint id);

Gets the colour mapping type for data visualisation in a data file container.

If no mapping is set, the current default mapping type from user settings is returned.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |

#### Returns

The colour mapping type.

### gwy_file_set_fixed_range()

    void
    gwy_file_set_fixed_range (GwyFile *file,
                              GwyDataKind data_kind,
                              gint id,
                              gdouble min,
                              gdouble max);

Sets the fixed colour mapping range for data visualisation in a data file container.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |
min | Fixed range minimum. |
max | Fixed range maximum. |

### gwy_file_get_fixed_range()

    gboolean
    gwy_file_get_fixed_range (GwyFile *file,
                              GwyDataKind data_kind,
                              gint id,
                              gdouble *min,
                              gdouble *max);

Gets the fixed colour mapping range for data visualisation in a data file container.

It is possible (although unusual) to request just one of the values, or even none.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of a data object in `file` . |
min | Location to store fixed range minimum. | [out][nullable]
max | Location to store fixed range maximum. | [out][nullable]

#### Returns

`TRUE` if all requested values were retrieved, `FALSE` otherwise.

### gwy_file_remove_selections()

    void
    gwy_file_remove_selections (GwyFile *file,
                                GwyDataKind data_kind,
                                gint id);

Removes all selections associated with image-like data from a file.

This is the preferred selection handling after in-place changes in data geometry as they have generally unpredictable effects on selections. The currently active tool generally needs a selection and will be forced to re-create it.

The function can be used with files in construction (see `gwy_dict_new_in_construction()`), although usually there is no reason for it.

#### Parameters

file | A data file container. |
data_kind | Type of data object. |
id | Numerical id of image-like data in file. |

### gwy_file_remove_logs()

    void
    gwy_file_remove_logs (GwyFile *file);

Removes all data processing logs from a file.

#### Parameters

file | A data file container. |

### gwy_file_get_format_name()

    const gchar *
    gwy_file_get_format_name (GwyFile *file);

Gets the file format name for a data file container.

The file format name is the name of file import function used to import the data.

#### Parameters

file | A data file container. |

#### Returns

The file format name, possibly `NULL`.

[nullable]

### gwy_file_get_filename_sys()

    const gchar *
    gwy_file_get_filename_sys (GwyFile *file);

Gets the file name corresponding to a data file container.

The file name is set on two ocasions: file load and successful file save. File export does not set it.

#### Parameters

file | A data file |

#### Returns

File name of `data` (in GLib encoding), or `NULL`. The returned string is owned by `file` and is valid only until it is destroyed or saved again.

### gwy_file_get_id()

    gint
    gwy_file_get_id (GwyFile *file);

Gets the numerical identifier of a file.

Only files managed by the data browser have an id. `GWY_FILE_ID_NONE` is returned for free-standing files. You can check whether a file is managed by calling this function and comparing the returned id to `GWY_FILE_ID_NONE`.

The identifier is not reused and does not change during program's lifetime. See also `gwy_data_browser_get_file()`.

For convenience, `NULL` can be also passed. The function then returns a negative value (`GWY_FILE_ID_NONE`).

#### Parameters

file | A data file container. | [nullable][transfer none]

#### Returns

The id (a nonnegative integer), possibly `GWY_FILE_ID_NONE`.

### gwy_file_key_filename()

    GQuark
    gwy_file_key_filename (void);

Returns the file name quark identifier.

#### Returns

The quark key identifying the file name.

### gwy_file_key_data()

    GQuark
    gwy_file_key_data (GwyDataKind data_kind,
                       gint id);

Constructs the quark identifier for a data kind and numerical id.

#### Parameters

data_kind | Type of data item. |
id | Numerical id of a data item in file. |

#### Returns

The quark key identifying the data.

### gwy_file_key_image()

    GQuark
    gwy_file_key_image (gint id);

Constructs image data quark identifier from its id.

#### Parameters

id | Numerical id of an image in file. |

#### Returns

The quark key identifying image data with number `id` .

### gwy_file_key_image_mask()

    GQuark
    gwy_file_key_image_mask (gint id);

Constructs image mask data quark identifier from its id.

#### Parameters

id | Numerical id of an image mask in file. |

#### Returns

The quark key identifying image mask data with number `id` .

### gwy_file_key_image_picture()

    GQuark
    gwy_file_key_image_picture (gint id);

Constructs image presentation data quark identifier from its id.

#### Parameters

id | Numerical id of an image in file. |

#### Returns

The quark key identifying image presentation data with number `id` .

### gwy_file_key_graph()

    GQuark
    gwy_file_key_graph (gint id);

Constructs graph model quark identifier from its id.

#### Parameters

id | Numerical id of a graph in file. |

#### Returns

The quark key identifying graph model with number `id` .

### gwy_file_key_spectra()

    GQuark
    gwy_file_key_spectra (gint id);

Constructs spectra quark identifier from its id.

#### Parameters

id | Numerical id of a spectra set in file. |

#### Returns

The quark key identifying spectra with number `id` .

### gwy_file_key_volume()

    GQuark
    gwy_file_key_volume (gint id);

Constructs data brick quark identifier from its id.

#### Parameters

id | Numerical id of a data brick in file. |

#### Returns

The quark key identifying data brick with number `id` .

### gwy_file_key_volume_mask()

    GQuark
    gwy_file_key_volume_mask (gint id);

Constructs volume mask data quark identifier from its id.

#### Parameters

id | Numerical id of a volume data in file. |

#### Returns

The quark key identifying volume mask data with number `id` .

### gwy_file_key_xyz()

    GQuark
    gwy_file_key_xyz (gint id);

Constructs XYZ scattered data quark identifier from its id.

#### Parameters

id | Numerical id of an XYZ scattered data in file. |

#### Returns

The quark key identifying XYZ scattered data with number `id` .

### gwy_file_key_cmap()

    GQuark
    gwy_file_key_cmap (gint id);

Constructs GwyLawn curve map quark identifier from its id.

#### Parameters

id | Numerical id of a GwyLawn curve map in file. |

#### Returns

The quark key identifying GwyLawn curve map with number `id` .

### gwy_file_key_image_title()

    GQuark
    gwy_file_key_image_title (gint id);

Constructs data field title quark identifier from its id.

#### Parameters

id | Numerical id of a image in file. |

#### Returns

The quark key identifying string title of image with number `id` .

### gwy_file_key_image_color_mapping()

    GQuark
    gwy_file_key_image_color_mapping (gint id);

Constructs data field color mapping quark identifier from its id.

#### Parameters

id | Numerical id of a image in file. |

#### Returns

The quark key identifying GwyColorMappingType false colour mapping type of image with number `id` .

### gwy_file_key_image_range_min()

    GQuark
    gwy_file_key_image_range_min (gint id);

Constructs data field fixed range minimum quark identifier from its id.

#### Parameters

id | Numerical id of a image in file. |

#### Returns

The quark key identifying floating fixed false colour range minimum of image with number `id` .

### gwy_file_key_image_range_max()

    GQuark
    gwy_file_key_image_range_max (gint id);

Constructs data field fixed range maximum quark identifier from its id.

#### Parameters

id | Numerical id of a image in file. |

#### Returns

The quark key identifying floating fixed false colour range maximum of image with number `id` .

### gwy_file_key_image_palette()

    GQuark
    gwy_file_key_image_palette (gint id);

Constructs data field palette quark identifier from its id.

#### Parameters

id | Numerical id of a image in file. |

#### Returns

The quark key identifying string name palette of image with number `id` .

### gwy_file_key_image_meta()

    GQuark
    gwy_file_key_image_meta (gint id);

Constructs data field metadata quark identifier from its id.

#### Parameters

id | Numerical id of a image in file. |

#### Returns

The quark key identifying metadata container of image with number `id` .

### gwy_file_key_image_real_square()

    GQuark
    gwy_file_key_image_real_square (gint id);

Constructs data field real-square quark identifier from its id.

#### Parameters

id | Numerical id of a image in file. |

#### Returns

The quark key identifying boolean controlling real-square setting of image with number `id` .

### gwy_file_key_image_selection()

    GQuark
    gwy_file_key_image_selection (gint id,
                                  const gchar *name);

Constructs data field selection quark identifier from its id and selection name.

If `name` is `NULL` or empty the base selections key is constructed, with no suffix for a specific selection.

#### Parameters

id | Numerical id of a image in file. |
name | Selection name (suffix of the string key). | [nullable]

#### Returns

The quark key identifying a GwySelection for image with number `id` .

### gwy_file_key_image_mask_color()

    GQuark
    gwy_file_key_image_mask_color (gint id);

Constructs image mask color quark identifier from its id.

#### Parameters

id | Numerical id of an image in file. |

#### Returns

The quark key identifying string color of image mask with number `id` .

### gwy_file_key_volume_mask_color()

    GQuark
    gwy_file_key_volume_mask_color (gint id);

Constructs volume mask color quark identifier from its id.

#### Parameters

id | Numerical id of a volume data in file. |

#### Returns

The quark key identifying string color of volume mask with number `id` .

### gwy_file_key_volume_title()

    GQuark
    gwy_file_key_volume_title (gint id);

Constructs data brick title quark identifier from its id.

#### Parameters

id | Numerical id of a data brick in file. |

#### Returns

The quark key identifying string title of data brick with number `id` .

### gwy_file_key_volume_picture()

    GQuark
    gwy_file_key_volume_picture (gint id);

Constructs data brick preview quark identifier from its id.

#### Parameters

id | Numerical id of a data brick in file. |

#### Returns

The quark key identifying preview data field of data brick with number `id` .

### gwy_file_key_volume_palette()

    GQuark
    gwy_file_key_volume_palette (gint id);

Constructs data brick palette quark identifier from its id.

#### Parameters

id | Numerical id of a data brick in file. |

#### Returns

The quark key identifying string name palette of data brick with number `id` .

### gwy_file_key_volume_meta()

    GQuark
    gwy_file_key_volume_meta (gint id);

Constructs data brick title quark identifier from its id.

#### Parameters

id | Numerical id of a data brick in file. |

#### Returns

The quark key identifying metadata container of data brick with number `id` .

### gwy_file_key_xyz_title()

    GQuark
    gwy_file_key_xyz_title (gint id);

Constructs XYZ scattered data title quark identifier from its id.

#### Parameters

id | Numerical id of a XYZ scattered data in file. |

#### Returns

The quark key identifying string title of XYZ scattered data with number `id` .

### gwy_file_key_xyz_palette()

    GQuark
    gwy_file_key_xyz_palette (gint id);

Constructs XYZ scattered data palette quark identifier from its id.

#### Parameters

id | Numerical id of an XYZ scattered data in file. |

#### Returns

The quark key identifying string name palette of XYZ scattered data with number `id` .

### gwy_file_key_xyz_meta()

    GQuark
    gwy_file_key_xyz_meta (gint id);

Constructs XYZ scattered data title quark identifier from its id.

#### Parameters

id | Numerical id of an XYZ scattered data in file. |

#### Returns

The quark key identifying metadata container of XYZ scattered data with number `id` .

### gwy_file_key_xyz_picture()

    GQuark
    gwy_file_key_xyz_picture (gint id);

Constructs XYZ scattered data preview quark identifier from its id.

#### Parameters

id | Numerical id of an XYZ scattered data in file. |

#### Returns

The quark key identifying preview data field of XYZ scattered data with number `id` .

### gwy_file_key_cmap_title()

    GQuark
    gwy_file_key_cmap_title (gint id);

Constructs GwyLawn curve map title quark identifier from its id.

#### Parameters

id | Numerical id of a GwyLawn curve map in file. |

#### Returns

The quark key identifying string title of GwyLawn curve map with number `id` .

### gwy_file_key_cmap_palette()

    GQuark
    gwy_file_key_cmap_palette (gint id);

Constructs GwyLawn curve map palette quark identifier from its id.

#### Parameters

id | Numerical id of a GwyLawn curve map in file. |

#### Returns

The quark key identifying string name palette of GwyLawn curve map with number `id` .

### gwy_file_key_cmap_meta()

    GQuark
    gwy_file_key_cmap_meta (gint id);

Constructs GwyLawn curve map title quark identifier from its id.

#### Parameters

id | Numerical id of a GwyLawn curve map in file. |

#### Returns

The quark key identifying metadata container of GwyLawn curve map with number `id` .

### gwy_file_key_cmap_picture()

    GQuark
    gwy_file_key_cmap_picture (gint id);

Constructs GwyLawn curve map preview quark identifier from its id.

#### Parameters

id | Numerical id of a GwyLawn curve map in file. |

#### Returns

The quark key identifying preview data field of GwyLawn curve map with number `id` .

### gwy_file_key_cmap_real_square()

    GQuark
    gwy_file_key_cmap_real_square (gint id);

Constructs GwyLawn curve map real-square quark identifier from its id.

#### Parameters

id | Numerical id of a GwyLawn curve map in file. |

#### Returns

The quark key identifying boolean controlling real-square setting of GwyLawn curve map with number `id` .

### gwy_parse_file_key()

    gboolean
    gwy_parse_file_key (const gchar *strkey,
                        GwyFileKeyParsed *parsed);

Parses a data file container key.

The parsing usually identifies the data kind, id and the specific setting or property for the data (if applicable). If a specific combination is impossible, for instance mask colour with graphs, the function returns `FALSE` even though the key may seem syntactically valid.

Upon successful parsing all fields are always set (possibly to values meaning ‘none’). There are some special cases. The piece `GWY_FILE_PIECE_FILENAME` is file-global and has neither data kind nor id.

When `parsed.suffix` is not set to `NULL` will generally point inside `strkey` . Since GwyDict keys are backed by GQuark, the corresponding string key is a constant string which always exists. Hence, the pointer will be always valid. However, if you use `gwy_parse_file_key()` with an arbitrary string, be aware that modifying or freeing it invalidates the suffix.

See also `gwy_form_file_key()` for constructing the key back.

#### Parameters

strkey | String data file container key. |
parsed | Location to store the parsed information. The contents of `parsed` is undefined if the function return `FALSE`. | [out]

#### Returns

`TRUE` if the key was sucessfully parsed; `FALSE` if it was not.

### gwy_form_file_key()

    GQuark
    gwy_form_file_key (const GwyFileKeyParsed *parsed);

Constructs a data file quark key from its broken down representation.

Although the function does not accept complete nonsense, it can form keys corresponding to data type and piece combinations which do not actually exists. In other words, if `parsed` was obtained using `gwy_parse_file_key()`, this function can be used to construct the string (quark) key back. However, a key constructed by this function is not guaranteed to be parseable using `gwy_parse_file_key()`.

See `gwy_form_string_file_key()` for a string version.

#### Parameters

parsed | Broken down key in a data file. |

#### Returns

The corresponding key as a quark.

### gwy_form_string_file_key()

    const gchar *
    gwy_form_string_file_key (const GwyFileKeyParsed *parsed);

Constructs a data file string key from its broken down representation.

See `gwy_form_file_key()` for a quark version and remarks.

#### Parameters

parsed | Broken down key in a data file. |

#### Returns

The corresponding key as a static string.

### gwy_file_error_quark()

    GQuark
    gwy_file_error_quark (void);

Gets the error domain for file structure.

See and use `GWY_FILE_ERROR`.

#### Returns

The error domain.

## Types and Values

### GWY_FILE_PREFIX_IMAGE

    #define GWY_FILE_PREFIX_IMAGE   "/image"

Prefix of image string keys in Gwyddion data files.

### GWY_FILE_PREFIX_GRAPH

    #define GWY_FILE_PREFIX_GRAPH   "/graph"

Prefix of graph string keys in Gwyddion data files.

### GWY_FILE_PREFIX_SPECTRA

    #define GWY_FILE_PREFIX_SPECTRA "/sps"

Prefix of single point spectra string keys in Gwyddion data files.

### GWY_FILE_PREFIX_VOLUME

    #define GWY_FILE_PREFIX_VOLUME  "/volume"

Prefix of volume data string keys in Gwyddion data files.

### GWY_FILE_PREFIX_XYZ

    #define GWY_FILE_PREFIX_XYZ     "/xyz"

Prefix of XYZ data string keys in Gwyddion data files.

### GWY_FILE_PREFIX_CMAP

    #define GWY_FILE_PREFIX_CMAP    "/cmap"

Prefix of curve map string keys in Gwyddion data files.

### GWY_FILE_ID_NONE

    #define GWY_FILE_ID_NONE (-1)

Invalid file id value indicating an unmanaged file.

Only files managed by the data browser have an id. A free-standing file object does not have any. Using `gwy_file_get_id()` on such file gives this value. The value can also represent an error.

### GWY_FILE_ERROR

    #define GWY_FILE_ERROR gwy_file_error_quark()

Error domain for file structure.

Errors in this domain will be from the GwyFileError enumeration. See GError for information on error domains.

### enum GwyFileError

Error codes returned by scanning of file structure.

Invalid file structure should not result from normal program operation. Therefore, the way you would get this errors, is the deserialisation of a GwyFile with incorrect/unrecognised structure. They would be include in the error list among (possibly) other deserialisation errors.

Error `GWY_FILE_ERROR_SIZE_MISMATCH` can occur for example when a mask has different pixel dimensions than the corresponding image. A similar error can happen with volume or curve map data previews.

For `GWY_FILE_ERROR_HUGE_ID`, reasonble depends on the amount of data. For a file with 100 images, reasonable ids are larger than for a single-image file. If the ids are several times larger the number of data, you are perfectly fine. If you try to add an image with id `G_MAXINT` just to cause trouble, do not do it then.

#### Members

GWY_FILE_ERROR_KEY | Malformed or unrecognised item key. |
GWY_FILE_ERROR_TYPE | Item has the wrong type for given key. |
GWY_FILE_ERROR_ORPHAN | Secondary item does not correspond to any primary data. |
GWY_FILE_ERROR_SIZE_MISMATCH | Secondary item does not match its primary data. |
GWY_FILE_ERROR_HUGE_ID | Unreasonably large data id. |

### enum GwyDataKind

Basic kind of data which can be found in Gwyddion data files.

#### Members

GWY_FILE_NONE | No data. Often meaning an error, sometimes also special data keys not related to any specific data. |
GWY_FILE_IMAGE | An image, primarily represented as GwyField. |
GWY_FILE_GRAPH | A graph, primarily represented as GwyGraphModel. |
GWY_FILE_SPECTRA | Single point spectra, primarily represented as GwySpectra. |
GWY_FILE_VOLUME | Volume data, primarily represented as GwyBrick. |
GWY_FILE_XYZ | XYZ data, primarily represented as GwyScatter. |
GWY_FILE_CMAP | A curve map, primarily represented as GwyLawn. |

### enum GwyFilePiece

Type of auxiliary data in a Gwyddion data file.

#### Members

GWY_FILE_PIECE_PALETTE | False colour mapping gradient. |
GWY_FILE_PIECE_RANGE | False colour mapping range. |
GWY_FILE_PIECE_COLOR_MAPPING | False colour mapping type. |
GWY_FILE_PIECE_REAL_SQUARE | Pixel/real aspect ratio. |
GWY_FILE_PIECE_MASK | Image mask. |
GWY_FILE_PIECE_MASK_COLOR | Mask colour. |
GWY_FILE_PIECE_SELECTION | Image selections. |
GWY_FILE_PIECE_META | Data item metadata. |
GWY_FILE_PIECE_PICTURE | Object representing the visualisation or preview of the data. |
GWY_FILE_PIECE_VIEW | Window size or scaling. |
GWY_FILE_PIECE_TITLE | Data item title. |
GWY_FILE_PIECE_LOG | Log of operations on the data item. |
GWY_FILE_PIECE_VISIBLE | Data item visibility. |
GWY_FILE_PIECE_FILENAME | Name of the file. |
GWY_FILE_PIECE_REF | References to other data in the file. |
GWY_FILE_PIECE_NONE | It usually indicates the main data object, but it can indicate an invalid data piece. |

### GWY_FILE_ITEM_PALETTE

    #define GWY_FILE_ITEM_PALETTE       (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_PALETTE)

False colour mapping gradient. Predefined item synchonisation flag.

### GWY_FILE_ITEM_RANGE

    #define GWY_FILE_ITEM_RANGE         (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_RANGE)

False colour mapping range. Predefined item synchonisation flag.

### GWY_FILE_ITEM_COLOR_MAPPING

    #define GWY_FILE_ITEM_COLOR_MAPPING (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_COLOR_MAPPING)

False colour mapping type. Predefined item synchonisation flag.

### GWY_FILE_ITEM_REAL_SQUARE

    #define GWY_FILE_ITEM_REAL_SQUARE   (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_REAL_SQUARE)

Pixel/real aspect ratio. Predefined item synchonisation flag.

### GWY_FILE_ITEM_MASK

    #define GWY_FILE_ITEM_MASK          (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_MASK)

Image mask. Predefined item synchonisation flag.

### GWY_FILE_ITEM_MASK_COLOR

    #define GWY_FILE_ITEM_MASK_COLOR    (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_MASK_COLOR)

Mask colour. Predefined item synchonisation flag.

### GWY_FILE_ITEM_SELECTIONS

    #define GWY_FILE_ITEM_SELECTIONS    (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_SELECTION)

Image selections. Predefined item synchonisation flag.

### GWY_FILE_ITEM_META

    #define GWY_FILE_ITEM_META          (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_META)

Data item metadata. Predefined item synchonisation flag.

### GWY_FILE_ITEM_PICTURE

    #define GWY_FILE_ITEM_PICTURE       (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_PICTURE)

Object representing the visualisation or preview of the data. Predefined item synchonisation flag.

### GWY_FILE_ITEM_VIEW

    #define GWY_FILE_ITEM_VIEW          (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_VIEW)

Window size or scaling. Predefined item synchonisation flag.

### GWY_FILE_ITEM_TITLE

    #define GWY_FILE_ITEM_TITLE         (G_GUINT64_CONSTANT(1) << GWY_FILE_PIECE_TITLE)

Data item title. Predefined item synchonisation flag.

### GwyFileKeyParsed

    typedef struct {
        gint id;
        GwyDataKind data_kind;
        GwyFilePiece piece;
        const gchar *suffix;
    } GwyFileKeyParsed;

Broken down representation of a piece of information in a data file container.

#### Members

gint `id`; | Numerical id of a data in file, -1 for no data item. |
GwyDataKind `data_kind`; | Type of the data object, `GWY_FILE_NONE` for no data item. |
GwyFilePiece `piece`; | Particular piece related or belonging to the data, `GWY_FILE_PIECE_NONE` for the main data object. |
const gchar *`suffix`; | Remaning part of the key (pointer to `strkey` ), or `NULL`. |

### struct GwyFile

    struct GwyFile;

The GwyFile struct contains private data only and should be accessed using the functions below.

### struct GwyFileClass

    struct GwyFileClass {
        GwyDictClass parent_class;
    };

## See Also

GwyDict