GwyResource

GwyResource — Built-in and/or user supplied application resources

Synopsis

#include <libgwyddion/gwyddion.h>

struct              GwyResource;
struct              GwyResourceClass;
const gchar *       gwy_resource_get_name               (GwyResource *resource);
gboolean            gwy_resource_get_is_modifiable      (GwyResource *resource);
gboolean            gwy_resource_get_is_preferred       (GwyResource *resource);
void                gwy_resource_set_is_preferred       (GwyResource *resource,
                                                         gboolean is_preferred);
const gchar *       gwy_resource_class_get_name         (GwyResourceClass *klass);
GwyInventory *      gwy_resource_class_get_inventory    (GwyResourceClass *klass);
const GwyInventoryItemType * gwy_resource_class_get_item_type
                                                        (GwyResourceClass *klass);
void                gwy_resource_use                    (GwyResource *resource);
void                gwy_resource_release                (GwyResource *resource);
gboolean            gwy_resource_is_used                (GwyResource *resource);
void                gwy_resource_data_changed           (GwyResource *resource);
void                gwy_resource_data_saved             (GwyResource *resource);
gchar *             gwy_resource_build_filename         (GwyResource *resource);
GString *           gwy_resource_dump                   (GwyResource *resource);
GwyResource *       gwy_resource_parse                  (const gchar *text,
                                                         GType expected_type);
void                gwy_resource_class_load             (GwyResourceClass *klass);
gboolean            gwy_resource_class_mkdir            (GwyResourceClass *klass);
void                gwy_resource_classes_finalize       (void);

Object Hierarchy

  GObject
   +----GwyResource
         +----GwyNLFitPreset

Properties

  "is-const"                 gboolean              : Read / Write / Construct Only
  "is-preferred"             gboolean              : Read / Write
  "name"                     gchar*                : Read

Signals

  "data-changed"                                   : Run First

Description

GwyResource is a base class for various application resources. It defines common interface: questioning resource name (gwy_resource_get_name()), modifiability (gwy_resource_get_is_modifiable()), loading resources from files and saving them.

Details

struct GwyResource

struct GwyResource;

The GwyResource struct contains private data only and should be accessed using the functions below.


struct GwyResourceClass

struct GwyResourceClass {
    GwyInventory *inventory;
    const gchar *name;

    /* Traits */
    GwyInventoryItemType item_type;

    /* Signals */
    void (*data_changed)(GwyResource *resource);

    /* Virtual table */
    void (*use)(GwyResource *resource);
    void (*release)(GwyResource *resource);
    void (*dump)(GwyResource *resource,
                 GString *string);
    GwyResource* (*parse)(const gchar *text,
                          gboolean is_const);
};

Resource class.

GwyInventory *inventory;

Inventory with resources.

const gchar *name;

Resource class name, usable as resource directory name for on-disk resources.

GwyInventoryItemType item_type;

Inventory item type. Most fields are pre-filled, but namely type and copy must be filled by particular resource type.

data_changed ()

"data-changed" signal method.

use ()

gwy_resource_use() virtual method.

release ()

gwy_resource_release() virtual method.

dump ()

gwy_resource_dump() virtual method, it only cares about resource data itself, the envelope is handled by GwyResource.

parse ()

gwy_resource_parse() virtual method, in only cares about resource data itself, the envelope is handled by GwyResource.

gwy_resource_get_name ()

const gchar *       gwy_resource_get_name               (GwyResource *resource);

Returns resource name.

resource :

A resource.

Returns :

Name of resource. The string is owned by resource and must not be modfied or freed.

gwy_resource_get_is_modifiable ()

gboolean            gwy_resource_get_is_modifiable      (GwyResource *resource);

Returns whether a resource is modifiable.

resource :

A resource.

Returns :

TRUE if resource is modifiable, FALSE if it's fixed (system) resource.

gwy_resource_get_is_preferred ()

gboolean            gwy_resource_get_is_preferred       (GwyResource *resource);

Returns whether a resource is preferred.

resource :

A resource.

Returns :

TRUE if resource is preferred, FALSE otherwise.

gwy_resource_set_is_preferred ()

void                gwy_resource_set_is_preferred       (GwyResource *resource,
                                                         gboolean is_preferred);

Sets preferability of a resource.

resource :

A resource.

is_preferred :

TRUE to make resource preferred, FALSE to make it not preferred.

gwy_resource_class_get_name ()

const gchar *       gwy_resource_class_get_name         (GwyResourceClass *klass);

Gets the name of resource class.

This is an simple identifier usable for example as directory name.

klass :

A resource class.

Returns :

Resource class name, as a constant string that must not be modified nor freed.

gwy_resource_class_get_inventory ()

GwyInventory *      gwy_resource_class_get_inventory    (GwyResourceClass *klass);

Gets inventory which holds resources of a resource class.

klass :

A resource class.

Returns :

Resource class inventory.

gwy_resource_class_get_item_type ()

const GwyInventoryItemType * gwy_resource_class_get_item_type
                                                        (GwyResourceClass *klass);

Gets inventory item type for a resource class.

klass :

A resource class.

Returns :

Inventory item type.

gwy_resource_use ()

void                gwy_resource_use                    (GwyResource *resource);

Starts using a resource.

Call to this function is necessary to use a resource properly. It makes the resource to create any auxiliary structures that consume considerable amount of memory and perform other initialization to ready-to-use form.

When a resource is no longer used, it should be released with gwy_resource_release().

In addition, it calls g_object_ref() on the resource.

Resources usually exist through almost whole program lifetime from GObject perspective, but from the viewpoint of use this method is the constructor and gwy_resource_release() is the destructor.

resource :

A resource.

gwy_resource_release ()

void                gwy_resource_release                (GwyResource *resource);

Releases a resource.

When the number of resource uses drops to zero, it frees all auxiliary data and returns back to `latent' form. In addition, it calls g_object_unref() on it. See gwy_resource_use() for more.

resource :

A resource.

gwy_resource_is_used ()

gboolean            gwy_resource_is_used                (GwyResource *resource);

Tells whether a resource is currently in use.

See gwy_resource_use() for details.

resource :

A resource.

Returns :

TRUE if resource is in use, FALSE otherwise.

gwy_resource_data_changed ()

void                gwy_resource_data_changed           (GwyResource *resource);

Emits signal "data-changed" on a resource.

It can be called only on non-constant resources. The default handler sets is_modified flag on the resource.

Mostly useful in resource implementation.

resource :

A resource.

gwy_resource_data_saved ()

void                gwy_resource_data_saved             (GwyResource *resource);

Clears is_modified flag of a resource.

resource :

A resource.

Since 2.8


gwy_resource_build_filename ()

gchar *             gwy_resource_build_filename         (GwyResource *resource);

Builds file name a resource should be saved to.

If the resource has not been newly created, renamed, or system it was probably loaded from file of the same name.

resource :

A resource.

Returns :

Resource file name as a newly allocated string that must be freed by caller.

gwy_resource_dump ()

GString *           gwy_resource_dump                   (GwyResource *resource);

Dumps a resource to a textual (human readable) form.

resource :

A resource.

Returns :

Textual resource representation.

gwy_resource_parse ()

GwyResource *       gwy_resource_parse                  (const gchar *text,
                                                         GType expected_type);

Reconstructs a resource from human readable form.

text :

Textual resource representation.

expected_type :

Resource object type. If not 0, only resources of give type are allowed. Zero value means any GwyResource is allowed.

Returns :

Newly created resource (or NULL).

gwy_resource_class_load ()

void                gwy_resource_class_load             (GwyResourceClass *klass);

Loads resources of a resources class from disk.

Resources are loaded from system directory (and marked constant) and from user directory (marked modifiable).

klass :

A resource class.

gwy_resource_class_mkdir ()

gboolean            gwy_resource_class_mkdir            (GwyResourceClass *klass);

Creates directory for user resources if it does not exist.

klass :

A resource class.

Returns :

TRUE if the directory exists or has been successfully created. FALSE if it doesn't exist and cannot be created, consult errno for reason.

gwy_resource_classes_finalize ()

void                gwy_resource_classes_finalize       (void);

Destroys the inventories of all resource classes.

This function makes the affected resource classes unusable. Its purpose is to faciliate reference leak debugging by destroying a large number of objects that normally live forever.

Note static resource classes that never called gwy_resource_class_load() are excluded.

Since 2.8

Property Details

The "is-const" property

  "is-const"                 gboolean              : Read / Write / Construct Only

Whether a resource is constant (system).

Default value: FALSE


The "is-preferred" property

  "is-preferred"             gboolean              : Read / Write

Whether a resource is preferred.

Default value: FALSE


The "name" property

  "name"                     gchar*                : Read

Resource name.

Default value: NULL

Signal Details

The "data-changed" signal

void                user_function                      (GwyResource *gwyresource,
                                                        gpointer     user_data)        : Run First

The ::data-changed signal is emitted when resource data changes.

gwyresource :

The GwyResource which received the signal.

user_data :

user data set when the signal handler was connected.

See Also

GwyInventory