## toolFileFormat

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

## Synopsis

    enum        FileFormatErrorFlag;
    enum        FileFormatPropertyTypeId;
    struct      FileFormatProperty_struct;
    typedef     FileFormatProperty;
    struct      FileFormat_struct;
    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 convienient 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()` returns 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

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

### struct FileFormat_struct

    struct FileFormat_struct {
      /* This is the list of file patterns, for example (*.jpg; *.jpeg; *.jpe). */
      GList *fileType;

      /* This is a short text to describe this file format.
         It should not be bigger than 30 characters. */
      gchar *description;

      /* This is a private field, it is a concatenation
         of "description ({patterns},)". */
      gchar *labelString;

      /* This is a private field. It enables to add some properties
         to a file format. See fileFormatAdd_property*() and fileFormatGet_property*()
         to control them. */
      GList *properties;
    };

This structure is used to describe a file format, for example JPEG image.

GList *`fileType`; | a GList, containing file patterns, for example (*.jpg; *.jpeg; *.jpe) ;
gchar *`description`; | a short text to describe this file format. It should not be bigger than 30 characters ;
gchar *`labelString`; | a private field, it is a concatenation of "description ({patterns},)" ;
GList *`properties`; | a private field to store some properties, see fileFormatAdd_property*() and fileFormatGet_property*().

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