ToolFileFormat

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

Synopsis

#define             TOOL_FILE_FORMAT_ERROR
struct              ToolFileFormat;
struct              ToolFileFormatClass;
enum                ToolFileFormatErrorFlag;
struct              ToolFileFormatIter;
gboolean            (*ToolFileFormatValidate)           (const gchar *filename);
void                tool_file_format_addOption          (ToolFileFormat *format,
                                                         ToolOption *opt);
void                tool_file_format_addPatterns        (ToolFileFormat *fmt,
                                                         const gchar **patterns);
ToolOption *        tool_file_format_addPropertyBoolean (ToolFileFormat *format,
                                                         const gchar *name,
                                                         const gchar *label,
                                                         gboolean defaultVal);
ToolOption *        tool_file_format_addPropertyDouble  (ToolFileFormat *format,
                                                         const gchar *name,
                                                         const gchar *label,
                                                         gdouble defaultVal);
ToolOption *        tool_file_format_addPropertyInt     (ToolFileFormat *format,
                                                         const gchar *name,
                                                         const gchar *label,
                                                         gint defaultVal);
gboolean            tool_file_format_canMatch           (ToolFileFormat *format);
ToolFileFormat *    tool_file_format_copy               (const ToolFileFormat *from);
const GList *       tool_file_format_getFilePatterns    (ToolFileFormat *format);
const gchar *       tool_file_format_getLabel           (ToolFileFormat *format);
const gchar *       tool_file_format_getName            (ToolFileFormat *format);
ToolOption *        tool_file_format_getPropertyByName  (ToolFileFormat *format,
                                                         const gchar *name);
GQuark              tool_file_format_getQuark           (void);
gboolean            tool_file_format_iterNextProperty   (ToolFileFormat *format,
                                                         ToolFileFormatIter *iter);
const gchar *       tool_file_format_match              (ToolFileFormat *format,
                                                         const gchar *filename);
ToolFileFormat *    tool_file_format_new                (const gchar *descr,
                                                         const gchar **patterns);
ToolFileFormat *    tool_file_format_newRestricted      (const gchar *descr,
                                                         const gchar **patterns);
void                tool_file_format_setValidator       (ToolFileFormat *format,
                                                         ToolFileFormatValidate validate);
gboolean            tool_file_format_validate           (ToolFileFormat *format,
                                                         const gchar *filename);

Object Hierarchy

  GObject
   +----ToolFileFormat
         +----VisuDump
         +----VisuScalarFieldMethod

Properties

  "ignore-type"              gboolean              : Read / Write
  "label"                    gchar*                : Read
  "name"                     gchar*                : Read / Write / Construct Only

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

TOOL_FILE_FORMAT_ERROR

#define TOOL_FILE_FORMAT_ERROR tool_file_format_getQuark()

Internal function for error handling.

struct ToolFileFormat

struct ToolFileFormat;

An opaque structure.

struct ToolFileFormatClass

struct ToolFileFormatClass {
  GObjectClass parent;
};

An opaque structure.

GObjectClass parent;

 the parent.

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.

struct ToolFileFormatIter

struct ToolFileFormatIter {
  GList *lst;

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

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

ToolFileFormatValidate ()

gboolean            (*ToolFileFormatValidate)           (const gchar *filename);

Function to match a given filename for a file format. See tool_file_format_setValidator().

filename :

 a path. [type filename]

Returns :

 TRUE if filename is a valid name for a file format.

Since 3.7

tool_file_format_addOption ()

void                tool_file_format_addOption          (ToolFileFormat *format,
                                                         ToolOption *opt);

File format may have options, like pseudo-potential pparameters in case of BigDFT calculations.

format :

 a ToolFileFormat object.

opt :

 a ToolOption object.

Since 3.7

tool_file_format_addPatterns ()

void                tool_file_format_addPatterns        (ToolFileFormat *fmt,
                                                         const gchar **patterns);

A file format may have pattern for the naming scheme of files, like "*.jpg" and "*.jpeg" for JPEG files. It's not mandatory for a file format to match its own pattern anyway.

fmt :

 a ToolFileFormat object.

patterns :

 a list of matching patterns. [array zero-terminated=1]

Since 3.7

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_addPropertyDouble ()

ToolOption *        tool_file_format_addPropertyDouble  (ToolFileFormat *format,
                                                         const gchar *name,
                                                         const gchar *label,
                                                         gdouble 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]

Since 3.7

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_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_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 g_object_unref(). [transfer full]

Since 3.6

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_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_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_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_getQuark ()

GQuark              tool_file_format_getQuark           (void);

Internal routine to get the GQuark to handle error related to file formats.

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

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_new ()

ToolFileFormat *    tool_file_format_new                (const gchar *descr,
                                                         const 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      (const gchar *descr,
                                                         const 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_setValidator ()

void                tool_file_format_setValidator       (ToolFileFormat *format,
                                                         ToolFileFormatValidate validate);

Set up a validating routine that do a minimal parsing to check that a provided file corresponds to this file format.

format :

 a ToolFileFormat ;

validate :

 a pointer to a validator routine. [scope call]

Since 3.7

tool_file_format_validate ()

gboolean            tool_file_format_validate           (ToolFileFormat *format,
                                                         const gchar *filename);

This method runs a minimal parsing routine set with tool_file_format_setValidator() to check if the provided filename correspond to this file format.

format :

 a ToolFileFormat ;

filename :

 a string to match.

Returns :

 TRUE, if the file (after minimal parsing) is of this file format. If there is no validator routine, it returns FALSE anyway.

Since 3.7

Property Details

The "ignore-type" property

  "ignore-type"              gboolean              : Read / Write

Don't restrict file matching to the given patterns.

Default value: FALSE

The "label" property

  "label"                    gchar*                : Read

Label used to show the file pattern.

Default value: ""

The "name" property

  "name"                     gchar*                : Read / Write / Construct Only

File format description.

Default value: ""

Generated by GTK-Doc V1.18