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_is_modifiable ()
gboolean | gwy_resource_is_managed ()
gboolean | gwy_resource_is_modified ()
gboolean | gwy_resource_get_preferred ()
void | gwy_resource_set_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_data_changed ()
void | gwy_resource_data_saved ()
gchar * | gwy_resource_build_filename ()
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 | const | Read / Write / Construct Only
gboolean | managed | Read
char * | name | Read / Write / Construct Only
gboolean | preferred | Read / Write

## Signals

void | data-changed | Run First

## Types and Values

struct | GwyResource
struct | GwyResourceClass

## Object Hierarchy

        GObject
        ╰── GwyResource
            ├── GwyCDLine
            ├── GwyNLFitPreset
            ├── GwyGLMaterial
            ├── GwyGradient
            ├── GwyGrainValue
            ├── GwyShapeFitPreset
            ╰── GwyTipModel

## 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_is_modifiable()`), loading resources from files and saving them.

Resources of one type are typically managed in an inventory which is filled during initialisation. Resource objects are created, deleted and modified using GwyResource and GwyInventory methods. You can create standalone (unmanaged) resource objects outside the inventory using `g_object_new()` or class-specific means and it is useful sometimes for private resources, but program-wide resources are handled through the inventory.

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

    gboolean
    gwy_resource_is_modifiable (GwyResource *resource);

Returns whether a resource is modifiable.

Resources loaded from user directories and unmanaged resources are generally modifiable. System resources are not.

#### Parameters

resource | A resource. |

#### Returns

`TRUE` if resource is modifiable, `FALSE` if it is a fixed (system) resource.

### gwy_resource_is_managed()

    gboolean
    gwy_resource_is_managed (GwyResource *resource);

Returns whether a resource is managed.

Managed resources are in the class inventory returned by `gwy_resource_class_get_inventory()` (or class-specific functions). They are usualy backed up by on disk files. New are created using inventory functions.

Unmanaged resources are standalone objects, not in the class inventory and not saved to disk.

#### Parameters

resource | A resource. |

#### Returns

`TRUE` if resource is managed, `FALSE` if it is not.

### gwy_resource_is_modified()

    gboolean
    gwy_resource_is_modified (GwyResource *resource);

Returns whether a resource has been modified.

Resources loaded from user directories and unmanaged resources are generally modifiable. System resources are not.

#### Parameters

resource | A resource. |

#### Returns

`TRUE` if resource has been modified since last save or loading from disk, `FALSE` if it has not been modified.

### gwy_resource_get_preferred()

    gboolean
    gwy_resource_get_preferred (GwyResource *resource);

Returns whether a resource is preferred.

#### Parameters

resource | A resource. |

#### Returns

`TRUE` if resource is preferred, `FALSE` otherwise.

### gwy_resource_set_preferred()

    void
    gwy_resource_set_preferred (GwyResource *resource,
                                gboolean is_preferred);

Sets preferability of a resource.

Preferred resources are offered more readily. For instance short lists can offer only preferred resources and the user may have to go to a full list to access the non-preferred.

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

[transfer none]

### 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_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 the modified flag on the resource which can be queried with `gwy_resource_is_modified()`.

Mostly useful in resource implementation.

#### Parameters

resource | A resource. |

### gwy_resource_data_saved()

    void
    gwy_resource_data_saved (GwyResource *resource);

Clears the modified flag of a resource.

#### Parameters

resource | A resource. |

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

Constant (system) resources cannot be renamed. Unmanaged resources can be renamed using this function; it just does not change anything on disk in such case.

#### Parameters

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

#### Returns

`TRUE` if the renaming succeeded.

### 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 and unmanaged resources cannot be removed (simply unref unmananged resources as any other object to destroy them).

#### Parameters

resource | A resource. |

#### Returns

`TRUE` if the removal succeeded.

### gwy_resource_save()

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

Saves a resource to disk.

Constant resources cannot be saved. Unmanaged resources cannot be saved using this function because they have no associated on-disk location.

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.

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

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

## Types and Values

### struct GwyResource

    struct GwyResource;

### struct GwyResourceClass

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

        /* Traits */
        GwyInventoryItemType item_type;

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

        /* Virtual table */
        void (*dump)(GwyResource *resource, GString *string);
        GwyResource* (*parse)(const gchar *text);
        GwyResource* (*parse_with_type)(GType type, const gchar *text);
        void (*setup_builtins)(GwyInventory *inventory);
    };

Resource class.

Method `setup_builtins` is mostly only useful for resources defined within Gwyddion itself. An initialisation function, such as `gwy_init()`, must know that the class exists in the first place to call its `setup_builtins` . By the time `gwy_init()` is called, third-party classes are usually not registered yet. Therefore, you can use `setup_builtins` in other classes if you find having class methods convenient. However, they will not be called by `gwy_init()`; you need to call them yourself.

#### 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. |
`dump`() | Format resource data to text. Only the data itself is formatted; the envelope is handled by GwyResource. |
`parse`() | Fill resource data from a string. The function only gets the resource data itself, the envelope is handled by GwyResource. This is the usual method as the parser normally knows its type. |
`parse_with_type`() | Alternative construction from a string, with the type to construct explicitly passed. It takes precedence over `parse` if both are defined. |
`setup_builtins`() | Method putting predefined constant resources in the class inventory. |

## Property Details

### The `“const”` property

      “const”                    gboolean

Whether a resource is constant (system).

Owner: GwyResource

Flags: Read / Write / Construct Only

Default value: FALSE

### The `“managed”` property

      “managed”                  gboolean

Whether a resource is managed in the inventory.

Owner: GwyResource

Flags: Read

Default value: FALSE

### The `“name”` property

      “name”                     char *

Resource name.

Owner: GwyResource

Flags: Read / Write / Construct Only

Default value: NULL

### The `“preferred”` property

      “preferred”                gboolean

Whether a resource is preferred (shown in shortlists).

Owner: GwyResource

Flags: Read / Write

Default value: FALSE

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