## GwyResource

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

## Synopsis

    #include <libgwyddion/gwyddion.h>

                        GwyResource;
                        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

### GwyResource

    typedef struct _GwyResource GwyResource;

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

### GwyResourceClass

    typedef struct {
        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);
    } GwyResourceClass;

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