## toolFileFormat

toolFileFormat — Describes file format objects (name patterns, description, properties...).

## Synopsis

    #define             VISU_FILEFORMAT_ERROR
    GQuark              fileFormatGet_quark                 ();
    enum                FileFormatErrorFlag;
    enum                FileFormatPropertyTypeId;
    struct              FileFormatProperty_struct;
    typedef             FileFormatProperty;
    typedef             FileFormat;
    FileFormat*         fileFormatNew                       (gchar *descr,
                                                             gchar **patterns);
    void                fileFormatFree                      (FileFormat *format);
    gchar*              fileFormatGet_label                 (FileFormat *format);
    gboolean            fileFormatUse_match                 (FileFormat *format,
                                                             gchar *filename);
    FileFormatPropertyTypeId fileFormatGet_propertyType     (FileFormatProperty *property);
    gboolean            fileFormatGet_propertyBoolean       (FileFormatProperty *property);
    gchar*              fileFormatGet_propertyName          (FileFormatProperty *property);
    gboolean            fileFormatSet_propertyBoolean       (FileFormatProperty *property,
                                                             gboolean value);
    GList*              fileFormatGet_propertiesList        (FileFormat *format);
    gchar*              fileFormatGet_propertyLabelUTF8     (FileFormatProperty *property);
    int                 fileFormatGet_propertyInteger       (FileFormatProperty *property);
    gboolean            fileFormatSet_propertyInteger       (FileFormatProperty *property,
                                                             int value);
    void                fileFormatAdd_propertyBoolean       (FileFormat *format,
                                                             const gchar *name,
                                                             const gchar *labelUTF8,
                                                             gboolean value);
    void                fileFormatAdd_propertyInteger       (FileFormat *format,
                                                             const gchar *name,
                                                             const gchar *labelUTF8,
                                                             int value);

## Description

When dealing with files, it is convenient to class then by formats, one format for JPEG files, one other for postscript... Such file formats are characterized by their description, explaining what they are, one or more name pattern (e.g. "*.jpg") and some properties (e.g. compression level for JPEG file).

This module describes objects that can store all these informations and deals with them. To create a new file format, use `fileFormatNew()`. A FileFormat object can be used in a GtkFileChooser object, using a GtkFileFilter. `fileFormatGet_label()` will return directly the label to give to the GtkFileFilter and the name patterns can be passed to it also.

A file format property can be an integer, a boolean or a string. For instance, use `fileFormatAdd_propertyBoolean()` to add a boolean property to a given FileFormat object. Then the stored value can be changed using `fileFormatSet_propertyBoolean()` and retrieve with `fileFormatGet_propertyBoolean()`.

## Details

### VISU_FILEFORMAT_ERROR

    #define VISU_FILEFORMAT_ERROR fileFormatGet_quark()

### fileFormatGet_quark ()

    GQuark              fileFormatGet_quark                 ();

### enum FileFormatErrorFlag

    typedef enum
      {
        FILEFORMAT_ERROR_METHOD,   /* Error from the rendering method. */
        FILEFORMAT_ERROR_FILE,     /* Error when opening. */
        FILEFORMAT_ERROR_FORMAT,   /* Wrongness in format. */
        FILEFORMAT_ERROR_UNKNOWN_FORMAT
      } FileFormatErrorFlag;

These are flags used when reading a file with a loading method associated to a file format.

`FILEFORMAT_ERROR_METHOD` | Error from the loading method.
`FILEFORMAT_ERROR_FILE` | Error when opening.
`FILEFORMAT_ERROR_FORMAT` | Wrongness in format.
`FILEFORMAT_ERROR_UNKNOWN_FORMAT` | the file is not recognised.

### enum FileFormatPropertyTypeId

    typedef enum
      {
        fileFormat_type_integer,
        fileFormat_type_boolean,
        fileFormat_type_string,
        fileFormat_nb_type
      } FileFormatPropertyTypeId;

Type for stored properties.

`fileFormat_type_integer` | the property is an integer value ;
`fileFormat_type_boolean` | the property is a boolean value ;
`fileFormat_type_string` | the property is a string ;
`fileFormat_nb_type` | give the number of supported property types.

### struct FileFormatProperty_struct

    struct FileFormatProperty_struct;

Opaque structure to store some FileFormat properties.

### FileFormatProperty

    typedef struct FileFormatProperty_struct FileFormatProperty;

Short definition for a FileFormatProperty_struct object.

### FileFormat

    typedef struct FileFormat_struct FileFormat;

A short name to identify FileFormat_struct structures.

### fileFormatNew ()

    FileFormat*         fileFormatNew                       (gchar *descr,
                                                             gchar **patterns);

Allocate a new FileFormat. The `patterns` argument is copied in the FileFormat object and can be freed safely after the call to this method.

`descr` : | a short string to label a new file format.
`patterns` : | a set of patterns to identify files of this format.
Returns : | a newly allocated FileFormat, or NULL if something goes wrong.

### fileFormatFree ()

    void                fileFormatFree                      (FileFormat *format);

Free all the memory used by `format`. If `format` is NULL, the method writes a warning on the eror output.

`format` : | a FileFormat to free.

### fileFormatGet_label ()

    gchar*              fileFormatGet_label                 (FileFormat *format);

This method gives a label describing the file format.

`format` : | a FileFormat.
Returns : | a string made by the description and all the paterns of the given format, given in parentethis. This string should not be freed.

### fileFormatUse_match ()

    gboolean            fileFormatUse_match                 (FileFormat *format,
                                                             gchar *filename);

This method try to match the given string to one of the patterns of the FileFormat `format`.

`format` : | a FileFormat ;
`filename` : | a string to match.
Returns : | TRUE if the given string matchs the file format.

### fileFormatGet_propertyType ()

    FileFormatPropertyTypeId fileFormatGet_propertyType     (FileFormatProperty *property);

Use this method to get the type of the given property.

`property` : | a pointer to the property to get the type from.
Returns : | an integer (see FileFormatPropertyTypeId).

### fileFormatGet_propertyBoolean ()

    gboolean            fileFormatGet_propertyBoolean       (FileFormatProperty *property);

Use this method to retrieve a value of a previously created property (use `fileFormatAdd_propertyBoolean()` to create one).

`property` : | a pointer to the property to get the value from.
Returns : | the value or FALSE if something goes wrong.

### fileFormatGet_propertyName ()

    gchar*              fileFormatGet_propertyName          (FileFormatProperty *property);

Use this method to get the string used when saving for the given property.

`property` : | a pointer to the property to get the name from.
Returns : | a string. This string is read-only.

### fileFormatSet_propertyBoolean ()

    gboolean            fileFormatSet_propertyBoolean       (FileFormatProperty *property,
                                                             gboolean value);

Use this method to modify a value of a previously created property (use `fileFormatAdd_propertyBoolean()` to create one).

`property` : | a pointer to the property to set the value to ;
`value` : | the value to be stored.
Returns : | TRUE if value is changed.

### fileFormatGet_propertiesList ()

    GList*              fileFormatGet_propertiesList        (FileFormat *format);

Use this method to get a list of stored properties for the given FileFormat. The GList is composed of FileFormatProperty objects.

`format` : | a FileFormat.
Returns : | a GList* that is read-only.

### fileFormatGet_propertyLabelUTF8 ()

    gchar*              fileFormatGet_propertyLabelUTF8     (FileFormatProperty *property);

Use this method to get a printable label for the given property.

`property` : | a pointer to the property to get the name from.
Returns : | a string in UTF8. This string is read-only.

### fileFormatGet_propertyInteger ()

    int                 fileFormatGet_propertyInteger       (FileFormatProperty *property);

Use this method to retrieve a value of a previously created property (use `fileFormatAdd_propertyInteger()` to create one).

`property` : | a pointer to the property to get the value from.
Returns : | the value or -1 if something goes wrong.

### fileFormatSet_propertyInteger ()

    gboolean            fileFormatSet_propertyInteger       (FileFormatProperty *property,
                                                             int value);

Use this method to modify a value of a previously created property (use `fileFormatAdd_propertyInteger()` to create one).

`property` : | a pointer to the property to set the value to ;
`value` : | the value to be stored.
Returns : | TRUE if value is changed.

### fileFormatAdd_propertyBoolean ()

    void                fileFormatAdd_propertyBoolean       (FileFormat *format,
                                                             const gchar *name,
                                                             const gchar *labelUTF8,
                                                             gboolean value);

Use this method to create a boolean property associated to the given FileFormat. This method is used only to create the property (and initialize it), use `fileFormatSet_propertyBoolean()` to change its value and `fileFormatGet_propertyBoolean()` to retrieve it. No checks are done if such a property already exists.

`format` : | a FileFormat ;
`name` : | a null terminated string ;
`labelUTF8` : | a null terminated string ;
`value` : | the value to be stored.

### fileFormatAdd_propertyInteger ()

    void                fileFormatAdd_propertyInteger       (FileFormat *format,
                                                             const gchar *name,
                                                             const gchar *labelUTF8,
                                                             int value);

Use this method to create an integer property associated to the given FileFormat. This method is used only to create the property (and initialize it), use `fileFormatSet_propertyInteger()` to change its value and `fileFormatGet_propertyInteger()` to retrieve it. No checks are done If such a property already exists.

`format` : | a FileFormat ;
`name` : | a null terminated string ;
`labelUTF8` : | a null terminated string ;
`value` : | the value to be stored.