gwymodule-file

gwymodule-file — File loading and saving modules

Synopsis




enum        GwyFileOperation;
struct      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);
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);

Description

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.

Details

enum GwyFileOperation

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

GWY_FILE_NONE None.
GWY_FILE_LOAD Posibility to load files of this type.
GWY_FILE_SAVE Posibility to save files of this type.
GWY_FILE_DETECT Posibility to detect files are of this file type,
GWY_FILE_MASK The mask for all the flags.

struct GwyFileFuncInfo

struct GwyFileFuncInfo {

    const gchar *name;
    const gchar *file_desc;
    GwyFileDetectFunc detect;
    GwyFileLoadFunc load;
    GwyFileSaveFunc save;
};

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.

GwyFileDetectFunc ()

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

GwyFileLoadFunc ()

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.

GwyFileSaveFunc ()

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.

gwy_file_func_register ()

gboolean    gwy_file_func_register          (const gchar *modname,
                                             GwyFileFuncInfo *func_info);

Registeres a data processing function.

The passed func_info must not be an automatic variable.

modname : Module identifier (name).
func_info : File type function info.
Returns : TRUE on success, FALSE on failure.

gwy_file_func_run_detect ()

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.

gwy_file_func_run_load ()

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.

gwy_file_func_run_save ()

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.

gwy_file_func_get_operations ()

GwyFileOperation gwy_file_func_get_operations
                                            (const gchar *name);

Returns possible operations for a file type function identified by name.

name : File type function name.
Returns : The file operation bit mask.

gwy_file_detect ()

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.

gwy_file_load ()

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.

gwy_file_save ()

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.

gwy_file_func_build_menu ()

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.