The Object Interface

## The Object Interface The Object Interface |

## Synopsis

                        CoglObject;
    void *              cogl_object_ref                     (void *object);
    void                cogl_object_unref                   (void *object);
                        CoglUserDataKey;
    typedef             CoglUserDataDestroyCallback;
    void *              cogl_object_get_user_data           (CoglObject *object,
                                                             CoglUserDataKey *key);
    void                cogl_object_set_user_data           (CoglObject *object,
                                                             CoglUserDataKey *key,
                                                             void *user_data,
                                                             CoglUserDataDestroyCallback destroy);

## Description

## Details

### CoglObject

    typedef struct _CoglObject CoglObject;

### cogl_object_ref ()

    void *              cogl_object_ref                     (void *object);

Increases the reference count of `object` by 1

`object` : | a CoglObject
Returns : | the `object`, with its reference count increased

### cogl_object_unref ()

    void                cogl_object_unref                   (void *object);

Drecreases the reference count of `object` by 1; if the reference count reaches 0, the resources allocated by `object` will be freed

`object` : | a CoglObject

### CoglUserDataKey

    typedef struct {
      int unused;
    } CoglUserDataKey;

A CoglUserDataKey is used to declare a key for attaching data to a CoglObject using cogl_object_set_user_data. The typedef only exists as a formality to make code self documenting since only the unique address of a CoglUserDataKey is used.

Typically you would declare a static CoglUserDataKey and set private data on an object something like this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    static CoglUserDataKey path_private_key;

    static void
    destroy_path_private_cb (void *data)
    {
      g_free (data);
    }

    static void
    my_path_set_data (CoglPath *path, void *data)
    {
      cogl_object_set_user_data (COGL_OBJECT (path),
                                 &private_key,
                                 data,
                                 destroy_path_private_cb);
    }

int `unused`; | ignored.

Since 1.4

### CoglUserDataDestroyCallback

    typedef GDestroyNotify CoglUserDataDestroyCallback;

When associating private data with a CoglObject a callback can be given which will be called either if the object is destroyed or if `cogl_object_set_user_data()` is called with NULL user_data for the same key.

Since 1.4

### cogl_object_get_user_data ()

    void *              cogl_object_get_user_data           (CoglObject *object,
                                                             CoglUserDataKey *key);

Finds the user data previously associated with `object` using the given `key`. If no user data has been associated with `object` for the given `key` this function returns NULL.

`object` : | The object with associated private data to query
`key` : | The address of a CoglUserDataKey which provides a unique value with which to index the private data.
Returns : | The user data previously associated with `object` using the given `key`; or `NULL` if no associated data is found. [transfer none]

Since 1.4

### cogl_object_set_user_data ()

    void                cogl_object_set_user_data           (CoglObject *object,
                                                             CoglUserDataKey *key,
                                                             void *user_data,
                                                             CoglUserDataDestroyCallback destroy);

Associates some private `user_data` with a given CoglObject. To later remove the association call `cogl_object_set_user_data()` with the same `key` but NULL for the `user_data`.

`object` : | The object to associate private data with
`key` : | The address of a CoglUserDataKey which provides a unique value with which to index the private data.
`user_data` : | The data to associate with the given object, or `NULL` to remove a previous association.
`destroy` : | A CoglUserDataDestroyCallback to call if the object is destroyed or if the association is removed by later setting `NULL` data for the same key.

Since 1.4