GeglMetadataStore

GeglMetadataStore — A metadata store base class for use with file modules.

Functions

void gegl_metadata_store_set_resolution_unit ()
GeglResolutionUnit gegl_metadata_store_get_resolution_unit ()
void gegl_metadata_store_set_resolution_x ()
gdouble gegl_metadata_store_get_resolution_x ()
void gegl_metadata_store_set_resolution_y ()
gdouble gegl_metadata_store_get_resolution_y ()
const gchar * gegl_metadata_store_get_file_module_name ()
void gegl_metadata_store_set_title ()
const gchar * gegl_metadata_store_get_title ()
void gegl_metadata_store_set_artist ()
const gchar * gegl_metadata_store_get_artist ()
void gegl_metadata_store_set_description ()
const gchar * gegl_metadata_store_get_description ()
void gegl_metadata_store_set_copyright ()
const gchar * gegl_metadata_store_get_copyright ()
void gegl_metadata_store_set_disclaimer ()
const gchar * gegl_metadata_store_get_disclaimer ()
void gegl_metadata_store_set_warning ()
const gchar * gegl_metadata_store_get_warning ()
void gegl_metadata_store_set_comment ()
const gchar * gegl_metadata_store_get_comment ()
void gegl_metadata_store_set_software ()
const gchar * gegl_metadata_store_get_software ()
void gegl_metadata_store_set_source ()
const gchar * gegl_metadata_store_get_source ()
void gegl_metadata_store_set_timestamp ()
GDateTime * gegl_metadata_store_get_timestamp ()
void gegl_metadata_store_declare ()
gboolean gegl_metadata_store_has_value ()
GType gegl_metadata_store_typeof_value ()
void gegl_metadata_store_set_value ()
void gegl_metadata_store_get_value ()
void gegl_metadata_store_set_string ()
const gchar * gegl_metadata_store_get_string ()
void gegl_metadata_store_register ()
void gegl_metadata_store_notify ()

Types and Values

Description

GeglMetadataStore is a non-instantiable base class implementing the GeglMetadata interface and provides methods for metadata access using well-known names. For consistency with other GObject features, the naming convention for metadata variables is the same as for GObject properties.

Methods are provided allowing the application to test whether a particular metadata item has a value and to set or get the values. If a metadata value does not exist, a GLib warning is printed. The gegl_metadata_store_has_value() method can be used to test silently for unset variables.

Signals are provided to allow an application to intercept metadata values from file modules, for example a Jpeg comment block might be parsed to set multiple metadata values, or multiple values may be formatted into the comment block.

Image resolution and resolution units are accessible only as properties. Well-known metatdata values are shadowed by properties to allow applications to take advantage of features such as introspection and property binding.

GeglMetadataStore does not itself implement the storage mechanism, it must be subclassed to provide this. GeglMetadataHash implements a store using a hash table. For convenience gegl_metadata_hash_new() casts its return value to GeglMetadataStore as it does not add any new methods or properties.

Functions

gegl_metadata_store_set_resolution_unit ()

void
gegl_metadata_store_set_resolution_unit
                               (GeglMetadataStore *self,
                                GeglResolutionUnit unit);

Set the units used for the resolution (density) values.

Parameters

self

A GeglMetadataStore

 

unit

Units as a GeglResolutionUnit

 

gegl_metadata_store_get_resolution_unit ()

GeglResolutionUnit
gegl_metadata_store_get_resolution_unit
                               (GeglMetadataStore *self);

Get the units used for resolution.

Parameters

self

A GeglMetadataStore

 

Returns

a GeglResolutionUnit.


gegl_metadata_store_set_resolution_x ()

void
gegl_metadata_store_set_resolution_x (GeglMetadataStore *self,
                                      gdouble resolution_x);

Set the X resolution or density in dots per unit.

Parameters

self

A GeglMetadataStore

 

resolution_x

X resolution or density

 

gegl_metadata_store_get_resolution_x ()

gdouble
gegl_metadata_store_get_resolution_x (GeglMetadataStore *self);

Get the X resolution or density in dots per unit.

Parameters

self

A GeglMetadataStore

 

Returns

X resolution


gegl_metadata_store_set_resolution_y ()

void
gegl_metadata_store_set_resolution_y (GeglMetadataStore *self,
                                      gdouble resolution_y);

Set the Y resolution or density in dots per unit.

Parameters

self

A GeglMetadataStore

 

resolution_y

Y resolution or density

 

gegl_metadata_store_get_resolution_y ()

gdouble
gegl_metadata_store_get_resolution_y (GeglMetadataStore *self);

Get the Y resolution or density in dots per unit.

Parameters

self

A GeglMetadataStore

 

Returns

Y resolution


gegl_metadata_store_get_file_module_name ()

const gchar *
gegl_metadata_store_get_file_module_name
                               (GeglMetadataStore *self);

Return the name registered by the current file module.

Parameters

self

A GeglMetadataStore

 

Returns

Current file module name or NULL.

[transfer none]


gegl_metadata_store_set_title ()

void
gegl_metadata_store_set_title (GeglMetadataStore *self,
                               const gchar *title);

Set title or caption for image.

Parameters

self

A GeglMetadataStore

 

title

Title string

 

gegl_metadata_store_get_title ()

const gchar *
gegl_metadata_store_get_title (GeglMetadataStore *self);

Get title or caption for image.

Parameters

self

A GeglMetadataStore

 

Returns

Title or NULL if not set.

[transfer none]


gegl_metadata_store_set_artist ()

void
gegl_metadata_store_set_artist (GeglMetadataStore *self,
                                const gchar *artist);

Set name of image creator.

Parameters

self

A GeglMetadataStore

 

artist

Artist string

 

gegl_metadata_store_get_artist ()

const gchar *
gegl_metadata_store_get_artist (GeglMetadataStore *self);

Get name of image creator.

Parameters

self

A GeglMetadataStore

 

Returns

Artist or NULL if not set.

[transfer none]


gegl_metadata_store_set_description ()

void
gegl_metadata_store_set_description (GeglMetadataStore *self,
                                     const gchar *description);

Set description of image.

Parameters

self

A GeglMetadataStore

 

description

Description string

 

gegl_metadata_store_get_description ()

const gchar *
gegl_metadata_store_get_description (GeglMetadataStore *self);

Get description of image.

Parameters

self

A GeglMetadataStore

 

Returns

Description or NULL if not set.

[transfer none]


gegl_metadata_store_set_copyright ()

void
gegl_metadata_store_set_copyright (GeglMetadataStore *self,
                                   const gchar *copyright);

Set the copyright notice.

Parameters

self

A GeglMetadataStore

 

copyright

Copyright string

 

gegl_metadata_store_get_copyright ()

const gchar *
gegl_metadata_store_get_copyright (GeglMetadataStore *self);

Get the copyright notice.

Parameters

self

A GeglMetadataStore

 

Returns

Copyright or NULL if not set.

[transfer none]


gegl_metadata_store_set_disclaimer ()

void
gegl_metadata_store_set_disclaimer (GeglMetadataStore *self,
                                    const gchar *disclaimer);

Set the legal disclaimer.

Parameters

self

A GeglMetadataStore

 

disclaimer

Disclaimer string

 

gegl_metadata_store_get_disclaimer ()

const gchar *
gegl_metadata_store_get_disclaimer (GeglMetadataStore *self);

Get the legal disclaimer.

Parameters

self

A GeglMetadataStore

 

Returns

Disclaimer or NULL if not set.

[transfer none]


gegl_metadata_store_set_warning ()

void
gegl_metadata_store_set_warning (GeglMetadataStore *self,
                                 const gchar *warning);

Set the warning of nature of content.

Parameters

self

A GeglMetadataStore

 

warning

Warning string

 

gegl_metadata_store_get_warning ()

const gchar *
gegl_metadata_store_get_warning (GeglMetadataStore *self);

Get warning.

Parameters

self

A GeglMetadataStore

 

Returns

Warning or NULL if not set.

[transfer none]


gegl_metadata_store_set_comment ()

void
gegl_metadata_store_set_comment (GeglMetadataStore *self,
                                 const gchar *comment);

Set the miscellaneous comment; conversion from GIF comment.

Parameters

self

A GeglMetadataStore

 

comment

Comment string

 

gegl_metadata_store_get_comment ()

const gchar *
gegl_metadata_store_get_comment (GeglMetadataStore *self);

Get the comment.

Parameters

self

A GeglMetadataStore

 

Returns

Comment or NULL if not set.

[transfer none]


gegl_metadata_store_set_software ()

void
gegl_metadata_store_set_software (GeglMetadataStore *self,
                                  const gchar *software);

Set software used to create the image.

Parameters

self

A GeglMetadataStore

 

software

Software string

 

gegl_metadata_store_get_software ()

const gchar *
gegl_metadata_store_get_software (GeglMetadataStore *self);

Get software used to create the image.

Parameters

self

A GeglMetadataStore

 

Returns

Software or NULL if not set.

[transfer none]


gegl_metadata_store_set_source ()

void
gegl_metadata_store_set_source (GeglMetadataStore *self,
                                const gchar *source);

Set device used to create the image.

Parameters

self

A GeglMetadataStore

 

source

Source string

 

gegl_metadata_store_get_source ()

const gchar *
gegl_metadata_store_get_source (GeglMetadataStore *self);

Get device used to create the image.

Parameters

self

A GeglMetadataStore

 

Returns

source or NULL if not set.

[transfer none]


gegl_metadata_store_set_timestamp ()

void
gegl_metadata_store_set_timestamp (GeglMetadataStore *self,
                                   const GDateTime *timestamp);

Set time of original image creation.

Parameters

self

A GeglMetadataStore

 

timestamp

A GDateTime

 

gegl_metadata_store_get_timestamp ()

GDateTime *
gegl_metadata_store_get_timestamp (GeglMetadataStore *self);

Get time of original image creation.

Parameters

self

A GeglMetadataStore

 

Returns

GDateTime or NULL if not set. Free with g_date_time_unref() when done.

[transfer full]


gegl_metadata_store_declare ()

void
gegl_metadata_store_declare (GeglMetadataStore *self,
                             GParamSpec *pspec);

Declare a metadata value using a GParamSpec.

Parameters

self

A GeglMetadataStore

 

pspec

A GParamSpec.

[transfer none]

gegl_metadata_store_has_value ()

gboolean
gegl_metadata_store_has_value (GeglMetadataStore *self,
                               const gchar *name);

Test whether the GeglMetadataStore contains a value for the specified name.

Parameters

self

A GeglMetadataStore

 

name

Metadata name

 

Returns

TRUE if metadata is declared and contains a valid value.


gegl_metadata_store_typeof_value ()

GType
gegl_metadata_store_typeof_value (GeglMetadataStore *self,
                                  const gchar *name);

Get the declared type of the value in the GeglMetadataStore.

Parameters

self

A GeglMetadataStore

 

name

Metadata name

 

Returns

Declared GType of metadata value or G_TYPE_INVALID.


gegl_metadata_store_set_value ()

void
gegl_metadata_store_set_value (GeglMetadataStore *self,
                               const gchar *name,
                               const GValue *value);

Set the specified metadata value. If value is NULL the default value from the associated GParamSpec is used. This operation will fail if the value has not been previously declared. A changed::name signal is emitted when the value is set. If the value is shadowed by a property a notify::name signal is also emitted.

Parameters

self

A GeglMetadataStore

 

name

Metadata name

 

value

(nullable): A valid GValue or NULL.

[in]

gegl_metadata_store_get_value ()

void
gegl_metadata_store_get_value (GeglMetadataStore *self,
                               const gchar *name,
                               GValue *value);

Retrieve the metadata value. value must be initialised with a compatible type. If the value is unset or has not been previously declared value is unchanged and an error message is logged.

Parameters

self

A GeglMetadataStore

 

name

Metadata name

 

value

An initialised GValue.

[inout]

gegl_metadata_store_set_string ()

void
gegl_metadata_store_set_string (GeglMetadataStore *self,
                                const gchar *name,
                                const gchar *string);

A slightly more efficient version of gegl_metadata_store_set_value() for string values avoiding a duplication. Otherwise it behaves the same gegl_metadata_store_set_value().

Parameters

self

A GeglMetadataStore

 

name

Metadata name

 

string

String value to set

 

gegl_metadata_store_get_string ()

const gchar *
gegl_metadata_store_get_string (GeglMetadataStore *self,
                                const gchar *name);

A slightly more efficient version of gegl_metadata_store_get_value() for string values avoiding a duplication. Otherwise it behaves the same gegl_metadata_store_get_value().

Parameters

self

A GeglMetadataStore

 

name

Metadata name

 

Returns

String or NULL.

[transfer none]


gegl_metadata_store_register ()

void
gegl_metadata_store_register (GeglMetadataStore *self,
                              const gchar *local_name,
                              const gchar *name,
                              GValueTransform transform);

Parameters

self

A GeglMetadataStore

 

local_name

Metadata name known to file module

 

name

Metadata name

 

transform

A GValueTransform function or NULL.

[scope async]

gegl_metadata_store_notify ()

void
gegl_metadata_store_notify (GeglMetadataStore *self,
                            GParamSpec *pspec,
                            gboolean shadow);

gegl_metadata_store_notify() is called by subclasses when the value of a metadata variable changes. It emits the ::changed signal with the variable name as the detail parameter. Set shadow = TRUE if variable is shadowed by a property so that a notify signal is emitted with the property name as the detail parameter.

Parameters

self

A GeglMetadataStore

 

pspec

The GParamSpec used to declare the variable.

 

shadow

The metadata variable shadows a property.

 

Types and Values

GEGL_TYPE_METADATA_STORE

#define GEGL_TYPE_METADATA_STORE   gegl_metadata_store_get_type ()

struct GeglMetadataStoreClass

struct GeglMetadataStoreClass {
  /* Subclass MUST provide the following */
  void          (*_declare)       (GeglMetadataStore *self,
                                   GParamSpec *pspec,
                                   gboolean shadow);
  GParamSpec   *(*pspec)          (GeglMetadataStore *self,
                                   const gchar *name);
  void          (*set_value)      (GeglMetadataStore *self,
                                   const gchar *name,
                                   const GValue *value);
  const GValue *(*_get_value)     (GeglMetadataStore *self,
                                   const gchar *name);
  gboolean      (*has_value)      (GeglMetadataStore *self,
                                   const gchar *name);

  /* Subclass MAY provide the following */
  void          (*register_hook)  (GeglMetadataStore *self,
                                   const gchar *file_module_name,
                                   guint flags);
  gboolean      (*parse_value)    (GeglMetadataStore *self,
                                   GParamSpec *pspec,
                                   GValueTransform transform,
                                   const GValue *value);
  gboolean      (*generate_value) (GeglMetadataStore *self,
                                   GParamSpec *pspec,
                                   GValueTransform transform,
                                   GValue *value);
};

The class structure for the GeglMetadataStore

Members

_declare ()

The _declare virtual method creates a metadata variable in the underlying data store. It implements gegl_metadata_store_declare(). A GParamSpec is used to describe the variable. If the metadata shadows an object property, shadow should be TRUE, otherwise FALSE. It is acceptable for a subclass to provide additional variables which are implicitly declared, that is, they need not be declared using gegl_metadata_store_declare(), however the pspec method must still retrieve a GParamSpec describing such variables. This method MUST be provided by the subclass.

 

pspec ()

The pspec virtual method returns the GParamSpec used to declare a metadata variable. It is used to implement gegl_metadata_store_typeof_value(). This method MUST be provided by the subclass.

 

set_value ()

Set a metadata variable using a GValue. Implements gegl_metadata_store_set_value(). The metadata variable should be declared and the GValue must be of the correct type. Note that failure to set a variable may be dependent of properties of the underlying storage mechanism. This method MUST be provided by the subclass.

 

_get_value ()

Return a pointer to a GValue with the value of the metadata variable or NULL if not declared or the variable does not contain a valid value. Implements gegl_metadata_store_get_value(). This method MUST be provided by the subclass.

 

has_value ()

The has_value virtual method implements gegl_metadata_store_has_value() It should return TRUE if the variable is declared and contains a valid value of the correct type, otherwise FALSE. This method MUST be provided by the subclass.

 

register_hook ()

This method is called after a file loader or saver registers a GeglMetadataMap and before any further processing takes place. It is intended to allow an application to create further application-specific mappings using gegl_metadata_store_register(). GeglMetadataStore provides a default method which emits the ::mapped signal.

 

parse_value ()

This method is called to optionally parse image file metadata prior to setting metadata variables in the GeglMetadataStore. If no parser is available it returns FALSE and the registered mapping is used. If a parser available it should set one or more metadata variables using gegl_metadata_store_set_value() and return TRUE. Note that the parser MUST return TRUE even if setting individual values fails. The default method checks if a signal handler is registered for the parse-value signal with the variable name as the detail parameter. If a handler is registered it emits the signal with the file metadata provided as a GValue and returns TRUE otherwise FALSE.

 

generate_value ()

This method is called to optionally generate a value to be written to and image file. If no generator is available it returns FALSE and the registered mapping is used. If a generator is available it should create a suitable value to be written to the image file and return TRUE. The default method checks if a signal handler is registered for the generate-value signal with the variable name as the detail parameter. If a handler is registered it emits the signal with an initialised GValue to receive the file metadata and returns TRUE otherwise FALSE. parse_value and generate_value are provided to handle the case where some file formats overload, for example, image comments. A typical case is formatting many values into a TIFF file's ImageDescription field.

 

GeglMetadataStore

typedef struct _GeglMetadataStore GeglMetadataStore;

See Also

GeglMetadata GeglMetadataHash