GwyResource

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

Synopsis




            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);
gchar*      gwy_resource_build_filename     (GwyResource *resource);
GString*    gwy_resource_dump               (GwyResource *resource);
GwyResource* gwy_resource_parse             (const gchar *text,
                                             GType expected_type);
gboolean    gwy_resource_class_save         (GwyResourceClass *klass,
                                             GError **err);
void        gwy_resource_class_load         (GwyResourceClass *klass);

Object Hierarchy


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

Properties


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

Signal Prototypes


"data-changed"
            void        user_function      (GwyResource *gwyresource,
                                            gpointer user_data);

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 {
    GObjectClass parent_class;

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

    gpointer reserved1;
    gpointer reserved2;
} GwyResourceClass;

Resource class.

GObjectClass parent_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.
gpointer reserved1;
gpointer reserved2;

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.

Mostly useful in resource implementation.

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.

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

gboolean    gwy_resource_class_save         (GwyResourceClass *klass,
                                             GError **err);

Saves modified user resources of a resource class to user directory.

Warning

This function will be probably removed, as resources should be saved on disk immediately. Namely because it's impossible to handle renamed resources this way.

klass : A resource class.
err : Location to store save error to, or NULL.
Returns : TRUE if save succeeded, FALSE if it failed.

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.

Properties

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"                 gchararray            : Read

Resource name.

Default value: NULL

Signals

The "data-changed" signal

void        user_function                  (GwyResource *gwyresource,
                                            gpointer user_data);

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