GwyResource (HEAD)

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