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

## Synopsis

                        ToolFileFormat;
                        ToolFileFormatIter;
    #define             TOOL_FILE_FORMAT_ERROR
    GQuark              tool_file_format_getQuark           (void);
    enum                ToolFileFormatErrorFlag;
    ToolFileFormat*     tool_file_format_new                (gchar *descr,
                                                             gchar **patterns);
    ToolFileFormat*     tool_file_format_newRestricted      (gchar *descr,
                                                             gchar **patterns);
    void                tool_file_format_free               (ToolFileFormat *format);
    ToolFileFormat*     tool_file_format_copy               (const ToolFileFormat *from);
    const gchar*        tool_file_format_getName            (ToolFileFormat *format);
    const gchar*        tool_file_format_getLabel           (ToolFileFormat *format);
    const GList*        tool_file_format_getFilePatterns    (ToolFileFormat *format);
    gboolean            tool_file_format_canMatch           (ToolFileFormat *format);
    const gchar*        tool_file_format_match              (ToolFileFormat *format,
                                                             const gchar *filename);
    ToolOption*         tool_file_format_addPropertyBoolean (ToolFileFormat *format,
                                                             const gchar *name,
                                                             const gchar *label,
                                                             gboolean defaultVal);
    ToolOption*         tool_file_format_addPropertyInt     (ToolFileFormat *format,
                                                             const gchar *name,
                                                             const gchar *label,
                                                             gint defaultVal);
    ToolOption*         tool_file_format_getPropertyByName  (ToolFileFormat *format,
                                                             const gchar *name);
    const GList*        tool_file_format_getPropertyList    (ToolFileFormat *format);
    gboolean            tool_file_format_iterNextProperty   (ToolFileFormat *format,
                                                             ToolFileFormatIter *iter);

## 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 `tool_file_format_new()`. A ToolFileFormat object can be used in a GtkFileChooser object, using a GtkFileFilter. `tool_file_format_getLabel()` will return directly the label to give to the GtkFileFilter and the name patterns can be passed to it also.

A file format property is a ToolOption value. There are some convenient routines to add common boolean or integer properties. For instance, use `tool_file_format_addPropertyBoolean()` to add a boolean property to a given ToolFileFormat object. Then the stored properties can be iterated on using a ToolFileFormatIter iterator.

## Details

### ToolFileFormat

    typedef struct _ToolFileFormat ToolFileFormat;

An opaque structure.

### ToolFileFormatIter

    typedef struct {
      GList *lst;

      gchar *name;
      gchar *label;
      GValue *val;
    } ToolFileFormatIter;

Iterator on ToolFileFormat object properties. See `tool_file_format_iterNextProperty()`.

GList *`lst`; | internal pointer.
gchar *`name`; | name of the current iterated property (read only).
gchar *`label`; | label of the current iterated property (read only).
GValue *`val`; | its value (read only).

Since 3.6

### TOOL_FILE_FORMAT_ERROR

    #define TOOL_FILE_FORMAT_ERROR tool_file_format_getQuark()

### tool_file_format_getQuark ()

    GQuark              tool_file_format_getQuark           (void);

### enum ToolFileFormatErrorFlag

    typedef enum
      {
        TOOL_FILE_FORMAT_ERROR_METHOD,   /* Error from the rendering method. */
        TOOL_FILE_FORMAT_ERROR_FILE,     /* Error when opening. */
        TOOL_FILE_FORMAT_ERROR_FORMAT,   /* Wrongness in format. */
        TOOL_FILE_FORMAT_ERROR_UNKNOWN_FORMAT
      } ToolFileFormatErrorFlag;

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

`TOOL_FILE_FORMAT_ERROR_METHOD` | Error from the loading method.
`TOOL_FILE_FORMAT_ERROR_FILE` | Error when opening.
`TOOL_FILE_FORMAT_ERROR_FORMAT` | Wrongness in format.
`TOOL_FILE_FORMAT_ERROR_UNKNOWN_FORMAT` | the file is not recognised.

### tool_file_format_new ()

    ToolFileFormat*     tool_file_format_new                (gchar *descr,
                                                             gchar **patterns);

Allocate a new ToolFileFormat. The `patterns` argument is copied in the ToolFileFormat 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.. array zero-terminated=1. element-type utf8.
Returns : | a newly allocated ToolFileFormat, or NULL if something goes wrong.. transfer none.

### tool_file_format_newRestricted ()

    ToolFileFormat*     tool_file_format_newRestricted      (gchar *descr,
                                                             gchar **patterns);

Allocate a new ToolFileFormat. The `patterns` argument is copied in the ToolFileFormat object and can be freed safely after the call to this method. The `patterns` list is not all the patterns supported by the format.

`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 ToolFileFormat, or NULL if something goes wrong.. transfer none.

### tool_file_format_free ()

    void                tool_file_format_free               (ToolFileFormat *format);

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

`format` : | a ToolFileFormat to free.

### tool_file_format_copy ()

    ToolFileFormat*     tool_file_format_copy               (const ToolFileFormat *from);

Copy the given file format `from` a create a new one.

`from` : | a ToolFileFormat object.
Returns : | a newly created ToolFileFormat. Should be freed with `tool_file_format_free()`.. transfer none.

Since 3.6

### tool_file_format_getName ()

    const gchar*        tool_file_format_getName            (ToolFileFormat *format);

This method gives the name describing the file format.

`format` : | a ToolFileFormat.
Returns : | a string with the name. This string should not be freed.. transfer none.

### tool_file_format_getLabel ()

    const gchar*        tool_file_format_getLabel           (ToolFileFormat *format);

This method gives a label describing the file format.

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

### tool_file_format_getFilePatterns ()

    const GList*        tool_file_format_getFilePatterns    (ToolFileFormat *format);

This method gives a list with the file patterns.

`format` : | a ToolFileFormat.
Returns : | a list with the file patterns. This list should not be freed. . transfer none. element-type utf8.

Since 3.6

### tool_file_format_canMatch ()

    gboolean            tool_file_format_canMatch           (ToolFileFormat *format);

This method is used to know if the file pattern list can be used to match a given filename with @`tool_file_format_match()`.

`format` : | a ToolFileFormat.
Returns : | TRUE if a call to @`tool_file_format_match()` is safe.

Since 3.6

### tool_file_format_match ()

    const gchar*        tool_file_format_match              (ToolFileFormat *format,
                                                             const gchar *filename);

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

`format` : | a ToolFileFormat ;
`filename` : | a string to match.
Returns : | the matching pattern, if any.

### tool_file_format_addPropertyBoolean ()

    ToolOption*         tool_file_format_addPropertyBoolean (ToolFileFormat *format,
                                                             const gchar *name,
                                                             const gchar *label,
                                                             gboolean defaultVal);

Add a new boolean property to the file format `format`.

`format` : | the ToolFileFormat object.
`name` : | a name ;
`label` : | a description ;
`defaultVal` : | a default value.
Returns : | a newly created ToolOption, free with `tool_option_free()`.. transfer none.

### tool_file_format_addPropertyInt ()

    ToolOption*         tool_file_format_addPropertyInt     (ToolFileFormat *format,
                                                             const gchar *name,
                                                             const gchar *label,
                                                             gint defaultVal);

Add a new integer property to the file format `format`.

`format` : | the ToolFileFormat object.
`name` : | a name ;
`label` : | a description ;
`defaultVal` : | a default value.
Returns : | a newly created ToolOption, free with `tool_option_free()`.. transfer none.

### tool_file_format_getPropertyByName ()

    ToolOption*         tool_file_format_getPropertyByName  (ToolFileFormat *format,
                                                             const gchar *name);

Retrieve the corresponding property to `name` from the biven `format`.

`format` : | a ToolFileFormat.
`name` : | the name of a property.
Returns : | the found ToolOption or NULL.. transfer none.

Since 3.5

### tool_file_format_getPropertyList ()

    const GList*        tool_file_format_getPropertyList    (ToolFileFormat *format);

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

`format` : | a ToolFileFormat.
Returns : | a GList* that is read-only.. transfer none. element-type ToolOption*.

### tool_file_format_iterNextProperty ()

    gboolean            tool_file_format_iterNextProperty   (ToolFileFormat *format,
                                                             ToolFileFormatIter *iter);

Run to the next property of the file format `format`. The iterator attributes are updated so it's convenient to access the property values and details, see ToolFileFormatIter.

`format` : | a ToolFileFormat object.
`iter` : | an iterator.
Returns : | TRUE if any.

Since 3.6