ToolFileFormat

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

Functions

Properties

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

Types and Values

Object Hierarchy

    GObject
    ╰── ToolDbgObj
        ╰── ToolFileFormat
            ├── VisuDataLoader
            ├── VisuDump
            ╰── VisuScalarFieldMethod

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.

Functions

tool_file_format_getQuark ()

GQuark
tool_file_format_getQuark (void);

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

[skip]


ToolFileFormatValidate ()

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

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

Parameters

filename

a path.

[type filename]

Returns

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

Since: 3.7


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.

Parameters

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.

Parameters

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

ToolFileFormat *
tool_file_format_copy (const ToolFileFormat *from);

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

Parameters

from

a ToolFileFormat object.

 

Returns

a newly created ToolFileFormat. Should be freed with g_object_unref().

[transfer full]

Since: 3.6


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.

Parameters

fmt

a ToolFileFormat object.

 

patterns

a list of matching patterns.

[array zero-terminated=1]

Since: 3.7


tool_file_format_getName ()

const gchar *
tool_file_format_getName (ToolFileFormat *format);

This method gives the name describing the file format.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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 .

Parameters

format

a ToolFileFormat ;

 

filename

a string to match.

 

Returns

the matching pattern, if any.


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.

Parameters

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 is using a built-in one, based on pattern matching with file types, see tool_file_format_addPatterns().

Since: 3.7


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.

Parameters

format

a ToolFileFormat ;

 

validate

a pointer to a validator routine.

[scope call][allow-none]

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.

Parameters

format

a ToolFileFormat object.

 

opt

a ToolOption object.

 

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 .

Parameters

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 .

Parameters

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 .

Parameters

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

void
tool_file_format_setPropertiesFromCLI (ToolFileFormat *format);

Scan all options from command line and affects values.

Parameters

format

A ToolFileFormat object.

 

Since: 3.8


tool_file_format_getPropertyBoolean ()

gboolean
tool_file_format_getPropertyBoolean (const ToolFileFormat *format,
                                     const gchar *name);

Retrieves the value of property prop .

Parameters

format

a ToolFileFormat object.

 

name

a property name.

 

Returns

the property value if exists, FALSE otherwise.

Since: 3.8


tool_file_format_getPropertyInt ()

gint
tool_file_format_getPropertyInt (const ToolFileFormat *format,
                                 const gchar *name);

Retrieves the value of property prop .

Parameters

format

a ToolFileFormat object.

 

name

a property name.

 

Returns

the property value if exists, -1 otherwise.

Since: 3.8


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.

Parameters

format

a ToolFileFormat object.

 

iter

an iterator.

 

Returns

TRUE if any.

Since: 3.6

Types and Values

struct ToolFileFormat

struct ToolFileFormat;

An opaque structure.


struct ToolFileFormatClass

struct ToolFileFormatClass {
  VisuObjectClass parent;
};

An opaque structure.

Members

VisuObjectClass parent;

the parent.

 

struct ToolFileFormatIter

struct ToolFileFormatIter {
  GList *lst;

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

Iterator on ToolFileFormat object properties. See tool_file_format_iterNextProperty().

Members

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

Internal function for error handling.


enum ToolFileFormatErrorFlag

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

Members

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_CANCEL

Cancellation occurs.

 

TOOL_FILE_FORMAT_ERROR_UNKNOWN_FORMAT

the file is not recognised.

 

Property Details

The “ignore-type” property

  “ignore-type”              gboolean

Don't restrict file matching to the given patterns.

Flags: Read / Write

Default value: FALSE


The “label” property

  “label”                    gchar *

Label used to show the file pattern.

Flags: Read

Default value: ""


The “name” property

  “name”                     gchar *

File format description.

Flags: Read / Write / Construct Only

Default value: ""