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.