Top | ![]() |
![]() |
![]() |
![]() |
#define | GWY_FILE_PREFIX_IMAGE |
#define | GWY_FILE_PREFIX_MASK |
#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 |
enum | GwyFileItem |
enum | GwyDataKind |
enum | GwyFilePiece |
GwyFileKeyParsed | |
struct | GwyFile |
struct | GwyFileClass |
GwyFile is a subclass of GwyContainer, assuming a specific organisation of items inside to represent scanning probe microscopy data, more specifically a Gwyddion GWY file.
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_container_start_construction()
on the newly created file.
[constructor]
gint gwy_file_add_image (GwyFile *file
,GwyDataField *field
);
Adds a data field representing an image to a file data container.
The file cannot be in construction (see gwy_container_start_construction()
).
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.
gint gwy_file_add_mask (GwyFile *file
,GwyDataField *mask
);
Adds a data field representing a mask to a file data container.
The file cannot be in construction (see gwy_container_start_construction()
).
A new unused id is assigned to the mask and returned. Generally, it is the lowest integer larger than any existing mask id (however, there are no specific guarantees).
The mask 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.
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_container_start_construction()
).
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.
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_container_start_construction()
).
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.
gint gwy_file_add_volume (GwyFile *file
,GwyBrick *brick
,GwyDataField *preview
);
Adds a data brick representing an volume data to a file data container.
The file cannot be in construction (see gwy_container_start_construction()
).
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.
gint gwy_file_add_xyz (GwyFile *file
,GwySurface *surface
);
Adds a data surface representing an XYZ data to a file data container.
The file cannot be in construction (see gwy_container_start_construction()
).
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.
gint gwy_file_add_cmap (GwyFile *file
,GwyLawn *lawn
,GwyDataField *preview
);
Adds a data lawn representing an curve map data to a file data container.
The file cannot be in construction (see gwy_container_start_construction()
).
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.
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.
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
.
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.
void gwy_file_sync_items (GwyFile *source
,GwyDataKind data_kind
,gint from_id
,GwyFile *dest
,gint to_id
,gboolean delete_too
,...
);
void gwy_file_sync_itemsv (GwyFile *source
,GwyDataKind data_kind
,gint from_id
,GwyFile *dest
,gint to_id
,gboolean delete_too
,const GwyFileItem *items
,guint nitems
);
gint gwy_file_copy (GwyFile *source
,GwyDataKind data_kind
,gint id
,GwyFile *dest
);
void gwy_file_set_visible (GwyFile *file
,GwyDataKind data_kind
,gboolean visible
);
GQuark
gwy_file_key_image (gint id
);
Constructs image data quark identifier from its id.
GQuark
gwy_file_key_mask (gint id
);
Constructs mask data quark identifier from its id.
GQuark
gwy_file_key_show (gint id
);
Constructs presentation data quark identifier from its id.
GQuark
gwy_file_key_graph (gint id
);
Constructs graph model quark identifier from its id.
GQuark
gwy_file_key_spectra (gint id
);
Constructs spectra quark identifier from its id.
GQuark
gwy_file_key_volume (gint id
);
Constructs data brick quark identifier from its id.
GQuark
gwy_file_key_xyz (gint id
);
Constructs XYZ surface quark identifier from its id.
GQuark
gwy_file_key_cmap (gint id
);
Constructs GwyLawn curve map quark identifier from its id.
GQuark
gwy_file_key_image_title (gint id
);
Constructs data field title quark identifier from its id.
GQuark
gwy_file_key_image_base (gint id
);
Constructs data field base visualisation quark identifier from its id.
This is the common prefix for range and palette key. It is not useful alone because it is only prefix.
GQuark
gwy_file_key_image_range_type (gint id
);
Constructs data field range type quark identifier from its id.
The quark key identifying GwyLayerBasicRangeType false colour mapping type of image with number id
.
GQuark
gwy_file_key_image_range_min (gint id
);
Constructs data field fixed range minimum quark identifier from its id.
GQuark
gwy_file_key_image_range_max (gint id
);
Constructs data field fixed range maximum quark identifier from its id.
GQuark
gwy_file_key_image_palette (gint id
);
Constructs data field palette quark identifier from its id.
GQuark
gwy_file_key_image_meta (gint id
);
Constructs data field metadata quark identifier from its id.
GQuark
gwy_file_key_image_real_square (gint id
);
Constructs data field real-square quark identifier from its id.
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.
GQuark
gwy_file_key_mask_title (gint id
);
Constructs data field title quark identifier from its id.
GQuark
gwy_file_key_volume_title (gint id
);
Constructs data brick title quark identifier from its id.
GQuark
gwy_file_key_volume_preview (gint id
);
Constructs data brick preview quark identifier from its id.
GQuark
gwy_file_key_volume_palette (gint id
);
Constructs data brick palette quark identifier from its id.
GQuark
gwy_file_key_volume_meta (gint id
);
Constructs data brick title quark identifier from its id.
GQuark
gwy_file_key_xyz_title (gint id
);
Constructs data surface title quark identifier from its id.
GQuark
gwy_file_key_xyz_palette (gint id
);
Constructs XYZ surface palette quark identifier from its id.
GQuark
gwy_file_key_xyz_meta (gint id
);
Constructs XYZ surface title quark identifier from its id.
GQuark
gwy_file_key_xyz_preview (gint id
);
Constructs XYZ surface preview quark identifier from its id.
GQuark
gwy_file_key_cmap_title (gint id
);
Constructs GwyLawn curve map title quark identifier from its id.
GQuark
gwy_file_key_cmap_palette (gint id
);
Constructs GwyLawn curve map palette quark identifier from its id.
GQuark
gwy_file_key_cmap_meta (gint id
);
Constructs GwyLawn curve map title quark identifier from its id.
GQuark
gwy_file_key_cmap_preview (gint id
);
Constructs GwyLawn curve map preview quark identifier from its id.
GQuark
gwy_file_key_cmap_real_square (gint id
);
Constructs GwyLawn curve map real-square quark identifier from its id.
The quark key identifying boolean controlling real-square setting of GwyLawn curve map with number id
.
gboolean gwy_file_parse_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 GwyContainer 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_file_parse_key()
with an arbitrary string, be aware that modifying or freeing it
invalidates the suffix.
See also gwy_file_form_key()
for constructing the key back.
GQuark
gwy_file_form_key (const GwyFileKeyParsed *parsed
);
Constructs a data file 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_file_parse_key()
, this
function can be used to construct the key back. However, a key constructed by this function may not be parseable
using gwy_file_parse_key()
.
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.
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()
.
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.
Basic kind of data which can be found in Gwyddion data files.
No data. Often meaning an error, sometimes also special data keys not related to any specific data. |
||
An image, primarily represented as GwyDataField. |
||
A mask, primarily represented as GwyDataField. |
||
A mask, primarily represented as GwyGraphModel. |
||
Single point spectra, primarily represented as GwySpectra. |
||
Volume data, primarily represented as GwyBrick. |
||
XYZ data, primarily represented as GwySurface. |
||
A curve map, primarily represented as GwyLawn. |
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.
Numerical id of a data in file, -1 for no data item. |
||
GwyDataKind |
Type of the data object, |
|
GwyFilePiece |
Particular piece related or belonging to the data, |
|
Remaning part of the key (pointer to |
struct GwyFile;
The GwyFile struct contains private data only and should be accessed using the functions below.