toolFileFormat

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

Synopsis

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


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.