GwyResource: Gwyddion Library Reference Manual

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

## Functions

const gchar * | gwy_resource_get_name ()
gboolean | gwy_resource_get_is_modifiable ()
gboolean | gwy_resource_get_is_preferred ()
void | gwy_resource_set_is_preferred ()
const gchar * | gwy_resource_class_get_name ()
GwyInventory * | gwy_resource_class_get_inventory ()
const GwyInventoryItemType * | gwy_resource_class_get_item_type ()
void | gwy_resource_use ()
void | gwy_resource_release ()
gboolean | gwy_resource_is_used ()
void | gwy_resource_data_changed ()
void | gwy_resource_data_saved ()
gchar * | gwy_resource_build_filename ()
GString * | gwy_resource_dump ()
GwyResource * | gwy_resource_parse ()
gboolean | gwy_resource_rename ()
gboolean | gwy_resource_delete ()
gboolean | gwy_resource_save ()
void | gwy_resource_class_load ()
void | gwy_resource_class_save_modified ()
gboolean | gwy_resource_class_mkdir ()
void | gwy_resource_classes_finalize ()

## Properties

gboolean | is-const | Read / Write / Construct Only
gboolean | is-preferred | Read / Write
char * | name | Read / Write / Construct Only

## Signals

void | data-changed | Run First

## Types and Values

struct | GwyResource
struct | GwyResourceClass

## Object Hierarchy

        GObject
        ╰── GwyResource
            ╰── GwyNLFitPreset

## Includes

    #include <libgwyddion/gwyddion.h>

## 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.

## Functions

### gwy_resource_get_name ()

    const gchar *
    gwy_resource_get_name (GwyResource *resource);

Returns resource name.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

resource | A resource. |

### gwy_resource_data_saved ()

    void
    gwy_resource_data_saved (GwyResource *resource);

Clears `is_modified` flag of a resource.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

    gboolean
    gwy_resource_rename (GwyResource *resource,
                         const gchar *newname);

Renames a resource, including renaming it on disk.

The method renames the resource both in the inventory and on disk. The renaming must not conflict with an existing resource, constant resources cannot be renamed, etc. It is OK to rename a resource to the same name (nothing happens then).

#### Parameters

resource | A resource. |
newname | New resource name. |

#### Returns

`TRUE` if the renaming succeeded.

Since: 2.51

### gwy_resource_delete ()

    gboolean
    gwy_resource_delete (GwyResource *resource);

Deletes a resource, including removal from disk.

The method deletes the resource both in the inventory and on disk. Constant resources cannot be deleted.

#### Parameters

resource | A resource. |

#### Returns

`TRUE` if the removal succeeded.

Since: 2.51

### gwy_resource_save ()

    gboolean
    gwy_resource_save (GwyResource *resource,
                       GError **error);

Saves a resource to disk.

Only non-constant resources can be saved. The file name is determined by `gwy_resource_build_filename()`. The resource data are saved even if the modified flag is not set. Upon successful save, the modified flag is cleared.

Instead of saving individual resources, consider also using `gwy_resource_class_save_modified()`.

#### Parameters

resource | A resource. |
error | Return location for a GError. |

#### Returns

`TRUE` if resource was saved to disk, `FALSE` otherwise.

Since: 2.62

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

#### Parameters

klass | A resource class. |

### gwy_resource_class_save_modified ()

    void
    gwy_resource_class_save_modified (GwyResourceClass *klass);

Saves all modified resource of given class to disk.

#### Parameters

klass | A resource class. |

Since: 2.62

### gwy_resource_class_mkdir ()

    gboolean
    gwy_resource_class_mkdir (GwyResourceClass *klass);

Creates directory for user resources if it does not exist.

#### Parameters

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

## Types and Values

### 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);
        GwyResource* (*parse_with_type)(GType type, const gchar *text, gboolean is_const);
    };

Resource class.

#### Members

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. It only cares about resource data itself, the envelope is handled by GwyResource. This is the usual method as the parse normally knows its type. |
`parse_with_type` () | gwy_resource_parse() virtual method. It only cares about resource data itself, the envelope is handled by GwyResource. It takes precedence over `parse` if both are defined. (Since 2.62) |

## Property Details

### The `“is-const”` property

      “is-const”                 gboolean

Whether a resource is constant (system).

Owner: GwyResource

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“is-preferred”` property

      “is-preferred”             gboolean

Whether a resource is preferred.

Owner: GwyResource

Flags: Read / Write

Default value: FALSE

### The `“name”` property

      “name”                     char *

Resource name.

Owner: GwyResource

Flags: Read / Write / Construct Only

Default value: NULL

## Signal Details

### The `“data-changed”` signal

    void
    user_function (GwyResource *gwyresource,
                   gpointer     user_data)

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

#### Parameters

gwyresource | The GwyResource which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

GwyInventory