![]() |
![]() |
![]() |
Gwyddion Module Library Reference Manual | ![]() |
---|---|---|---|---|
enum GwyFileOperation; GwyFileFuncInfo; gint (*GwyFileDetectFunc) (const gchar *filename, gboolean only_name, const gchar *name); GwyContainer* (*GwyFileLoadFunc) (const gchar *filename, const gchar *name); gboolean (*GwyFileSaveFunc) (GwyContainer *data, const gchar *filename, const gchar *name); gboolean gwy_file_func_register (const gchar *modname, GwyFileFuncInfo *func_info); gint gwy_file_func_run_detect (const gchar *name, const gchar *filename, gboolean only_name); GwyContainer* gwy_file_func_run_load (const gchar *name, const gchar *filename); gboolean gwy_file_func_run_save (const gchar *name, GwyContainer *data, const gchar *filename); GwyFileOperation gwy_file_func_get_operations (const gchar *name); const gchar* gwy_file_func_get_description (const gchar *name); gchar* gwy_file_detect (const gchar *filename, gboolean only_name, GwyFileOperation operations); GwyContainer* gwy_file_load (const gchar *filename); gboolean gwy_file_save (GwyContainer *data, const gchar *filename); GtkObject* gwy_file_func_build_menu (GtkObject *item_factory, const gchar *prefix, GCallback item_callback, GwyFileOperation type);
File modules implement file loading, saving and file type detection functions. Not all fuctions has to be implemented, a file module can be import-only or export-only. If it does not implement file type detection, files of this type can be read/written only on user's explicite request.
For file module writers, the only useful function here is the registration
function gwy_file_func_register()
and the signatures of particular file operations:
GwyFileDetectFunc,
GwyFileLoadFunc, and
GwyFileSaveFunc.
typedef enum { GWY_FILE_NONE = 0, GWY_FILE_LOAD = 1 << 0, GWY_FILE_SAVE = 1 << 1, GWY_FILE_DETECT = 1 << 2, GWY_FILE_MASK = 0x07 } GwyFileOperation;
File type function file operations (capabilities).
typedef struct { const gchar *name; const gchar *file_desc; GwyFileDetectFunc detect; GwyFileLoadFunc load; GwyFileSaveFunc save; } GwyFileFuncInfo;
Information about set of functions for one file type.
const gchar *name ; |
File type function name (used for all detect/save/load functions). |
const gchar *file_desc ; |
Brief file type description. This will appear in the menu so it should not contain slashes, and the preferred form is "Foobar data (.foo)". |
GwyFileDetectFunc detect ; |
The file type detecting function. |
GwyFileLoadFunc load ; |
The file loading function. |
GwyFileSaveFunc save ; |
The file saving function. |
gint (*GwyFileDetectFunc) (const gchar *filename, gboolean only_name, const gchar *name);
The type of file type detection function.
When called with TRUE
only_name
it should not try to access the file.
filename : |
A file name to detect the filetype of. |
only_name : |
Whether the type should be guessed only from file name. |
name : |
Function name from GwyFileFuncInfo (most modules can safely ignore this argument) |
Returns : | An integer likehood score (see gwy_file_func_run_detect() for
description).
|
GwyContainer* (*GwyFileLoadFunc) (const gchar *filename, const gchar *name);
The type of file loading function.
filename : |
A file name to load data from. |
name : |
Function name from GwyFileFuncInfo (most modules can safely ignore this argument) |
Returns : | A newly created data container or NULL .
|
gboolean (*GwyFileSaveFunc) (GwyContainer *data, const gchar *filename, const gchar *name);
The type of file saving function.
data : |
A GwyContainer to save. |
filename : |
A file name to save data as.
|
name : |
Function name from GwyFileFuncInfo (most modules can safely ignore this argument) |
Returns : | TRUE if file save succeeded, FALSE otherwise.
|
gboolean gwy_file_func_register (const gchar *modname, GwyFileFuncInfo *func_info);
Registeres a file type function.
To keep compatibility with old versions func_info
should not be an
automatic variable. However, since 1.6 it keeps a copy of func_info
.
gint gwy_file_func_run_detect (const gchar *name, const gchar *filename, gboolean only_name);
Runs a file type detection function identified by name
.
Value of only_name
should be TRUE
if the file doesn't exist (is to be
written) so its contents can't be used for file type detection.
This is a low-level function, consider using gwy_file_detect()
if you
simply want to detect a file type.
name : |
A file type function name. |
filename : |
A file name to detect. |
only_name : |
Whether to use only file name for a guess, or try to actually access the file. |
Returns : | An integer score expressing the likehood of the file being loadable as this type. A basic scale is 20 for a good extension, 100 for good magic header, more for more thorough tests. |
GwyContainer* gwy_file_func_run_load (const gchar *name, const gchar *filename);
Runs a file load function identified by name
.
This is a low-level function, consider using gwy_file_load()
if you
simply want to load a file.
name : |
A file load function name. |
filename : |
A file name to load data from. |
Returns : | A new GwyContainer with data from filename , or NULL .
|
gboolean gwy_file_func_run_save (const gchar *name, GwyContainer *data, const gchar *filename);
Runs a file save function identified by name
.
It guarantees the container lifetime spans through the actual file saving, so the module function doesn't have to care about it.
This is a low-level function, consider using gwy_file_save()
if you
simply want to save a file.
name : |
A file save function name. |
data : |
A GwyContainer to save. |
filename : |
A file name to save data as.
|
Returns : | TRUE if file save succeeded, FALSE otherwise.
|
GwyFileOperation gwy_file_func_get_operations (const gchar *name);
Returns possible operations for a file type function identified by
name
.
This function is the prefered one for testing whether a file function exists, as function with no operations cannot be registered.
name : |
File type function name. |
Returns : | The file operation bit mask, zero if name does not exist.
|
const gchar* gwy_file_func_get_description (const gchar *name);
Gets file function description.
That is, the file_desc
field of GwyFileFuncInfo.
name : |
File type function name. |
Returns : | File function description, as a string owned by module loader. |
Since 1.9
gchar* gwy_file_detect (const gchar *filename, gboolean only_name, GwyFileOperation operations);
Detects file type of file filename
.
filename : |
A file name to detect type of. |
only_name : |
Whether to use only file name for a guess, or try to actually access the file. |
operations : |
The file operations (all of them) the file type should support. |
Returns : | The type name (i.e., the same name as passed to
e.g. gwy_run_file_load_func() ) of most probable type of filename ,
or NULL if there's no probable one.
|
GwyContainer* gwy_file_load (const gchar *filename);
Loads a data file, autodetecting its type.
filename : |
A file name to load data from. |
Returns : | A new GwyContainer with data from filename , or NULL .
|
gboolean gwy_file_save (GwyContainer *data, const gchar *filename);
Saves a data file, deciding to save as what type from the file name.
data : |
A GwyContainer to save. |
filename : |
A file name to save the data as. |
Returns : | TRUE if file save succeeded, FALSE otherwise.
|
GtkObject* gwy_file_func_build_menu (GtkObject *item_factory, const gchar *prefix, GCallback item_callback, GwyFileOperation type);
Creates GtkItemFactory for a file type menu with all registered file type functions.
item_factory : |
A GtkItemFactory to add items to. |
prefix : |
Where to add the menu items to the factory. |
item_callback : |
A GtkItemFactoryCallback1 called when an item from the menu is selected. |
type : |
Only function providing this file operation are included in the menu. |
Returns : | The menu item factory as a GtkObject. |