## The Object Interface

The Object Interface

## Functions

void * | cogl_object_ref ()
void | cogl_object_unref ()
void * | cogl_object_get_user_data ()
void | cogl_object_set_user_data ()

## Types and Values

| CoglObject
| CoglUserDataKey
typedef | CoglUserDataDestroyCallback

## Description

## Functions

### cogl_object_ref ()

    void *
    cogl_object_ref (void *object);

Increases the reference count of `object` by 1

[skip]

#### Parameters

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

[skip]

#### Parameters

object | a CoglObject |

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

[skip]

#### Parameters

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

[skip]

#### Parameters

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

## Types and Values

### CoglObject

    typedef struct _CoglObject CoglObject;

Ref Func: cogl_object_ref Unref Func: cogl_object_unref Set Value Func: cogl_object_value_set_object Get Value Func: cogl_object_value_get_object

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

#### Members

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