![]() |
![]() |
![]() |
V_Sim API - Reference Manual | ![]() |
---|---|---|---|---|
toolFileFormattoolFileFormat — Describes file format objects (name patterns, description, properties...) |
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);
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()
.
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.
typedef enum { fileFormat_type_integer, fileFormat_type_boolean, fileFormat_type_string, fileFormat_nb_type } FileFormatPropertyTypeId;
Type for stored properties.
struct FileFormatProperty_struct;
Opaque structure to store some FileFormat properties.
typedef struct FileFormatProperty_struct FileFormatProperty;
Short definition for a FileFormatProperty_struct object.
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*(). |
typedef struct FileFormat_struct FileFormat;
A short name to identify FileFormat_struct structures.
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. |
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. |
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. |
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. |
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). |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |