## GdaObjectRef

GdaObjectRef — Used to reference other objects

## Synopsis

                        GdaObjectRef;
    enum                GdaObjectRefType;
    GObject*            gda_object_ref_new                  (GdaDict *dict);
    GObject*            gda_object_ref_new_no_ref_count     (GdaDict *dict);
    GObject*            gda_object_ref_new_copy             (GdaObjectRef *orig);
    void                gda_object_ref_set_ref_name         (GdaObjectRef *ref,
                                                             GType ref_type,
                                                             GdaObjectRefType type,
                                                             const gchar *name);
    void                gda_object_ref_set_ref_object_type  (GdaObjectRef *ref,
                                                             GdaObject *object,
                                                             GType type);
    void                gda_object_ref_set_ref_object       (GdaObjectRef *ref,
                                                             GdaObject *object);
    void                gda_object_ref_replace_ref_object   (GdaObjectRef *ref,
                                                             GHashTable *replacements);
    const gchar*        gda_object_ref_get_ref_name         (GdaObjectRef *ref,
                                                             GType *ref_type,
                                                             GdaObjectRefType *type);
    const gchar*        gda_object_ref_get_ref_object_name  (GdaObjectRef *ref);
    GType               gda_object_ref_get_ref_type         (GdaObjectRef *ref);
    GdaObject*          gda_object_ref_get_ref_object       (GdaObjectRef *ref);
    gboolean            gda_object_ref_activate             (GdaObjectRef *ref);
    void                gda_object_ref_deactivate           (GdaObjectRef *ref);
    gboolean            gda_object_ref_is_active            (GdaObjectRef *ref);

## Object Hierarchy

      GObject
       +----GdaObject
             +----GdaObjectRef

## Properties

      "helper-ref"               GdaObject*            : Read / Write
      "obj-name"                 gchar*                : Read / Write

## Signals

      "ref-found"                                      : Run First
      "ref-lost"                                       : Run First

## Description

This object is a simple wrapper to reference other objects. It can be used in places where referenced objects do not yet exist when they are needed, and their xml ID or their name is known. In this situation, create a GdaObjectRef object, give it the xml ID or name of the object which is to be referenced, and activate the GdaObjectRef object. If it is activated, then the real object can be fetched through the GdaObjectRef object.

There are restrictions on the types of objects which can be handled:

- GdaDictTable

- GdaDictField

- GdaQuery

- GdaQueryTarget

- GdaEntityField (for any GdaDictField of GdaQueryField object)

## Details

### GdaObjectRef

    typedef struct _GdaObjectRef GdaObjectRef;

### enum GdaObjectRefType

    typedef enum
    {
    	REFERENCE_BY_XML_ID,
    	REFERENCE_BY_NAME
    } GdaObjectRefType;

### gda_object_ref_new ()

    GObject*            gda_object_ref_new                  (GdaDict *dict);

Creates a new GdaObjectRef object. This GdaObjectRef object does itself increase the reference count of the referenced object, so if all the reference count holders call `g_object_unref()` on there referenced object, then that object will not be destroyed because this GdaObjectRef still has a reference on it. Use `gda_object_ref_new_no_ref_count()` if you don't want to increase the reference count of the referenced object.

`dict` : | a GdaDict object
Returns : | the new object

### gda_object_ref_new_no_ref_count ()

    GObject*            gda_object_ref_new_no_ref_count     (GdaDict *dict);

Creates a new GdaObjectRef object. This GdaObjectRef object does not itself increase the reference count of the object it keeps a reference to, which means that if all the reference count holders call `g_object_unref()` on there referenced object, then that object will actually be destroyed and a "ref_lost" signal will be emitted. Use `gda_object_ref_new()` if you want to increase the count of the referenced object.

`dict` : | a GdaDict object
Returns : | the new object

### gda_object_ref_new_copy ()

    GObject*            gda_object_ref_new_copy             (GdaObjectRef *orig);

Creates a new GdaObjectRef object which is a copy of `orig`. This is a copy constructor.

`orig` : | a GdaObjectRef object
Returns : | the new object

### gda_object_ref_set_ref_name ()

    void                gda_object_ref_set_ref_name         (GdaObjectRef *ref,
                                                             GType ref_type,
                                                             GdaObjectRefType type,
                                                             const gchar *name);

Sets the type and XML Id of the object we want to reference. If any other object was already referenced `ref` is first reinitialized

Rem: the name format is dependant on the type of object which is requested

`ref` : | a GdaObjectRef object
`ref_type` : | the requested referenced object's data type, or 0 if not specified and `type` = REFERENCE_BY_XML_ID
`type` : | how to interpret the `name` argument
`name` : | the name of the requested object

### gda_object_ref_set_ref_object_type ()

    void                gda_object_ref_set_ref_object_type  (GdaObjectRef *ref,
                                                             GdaObject *object,
                                                             GType type);

Rather than to set the XML Id of the object `ref` has to reference, this function allows to directly give the object, and specify the requested type, in case the object is known.

`ref` : | a GdaObjectRef object
`object` : | the object to keep a reference to
`type` : | the type of object requested: it must be a type in the class hierarchy of `object`

### gda_object_ref_set_ref_object ()

    void                gda_object_ref_set_ref_object       (GdaObjectRef *ref,
                                                             GdaObject *object);

Rather than to set the XML Id of the object `ref` has to reference, this function allows to directly give the object, in case the object is known.

`ref` : | a GdaObjectRef object
`object` : | the object to keep a reference to

### gda_object_ref_replace_ref_object ()

    void                gda_object_ref_replace_ref_object   (GdaObjectRef *ref,
                                                             GHashTable *replacements);

Changes the referenced object with a new one: it looks into `replacements` and if the currently referenced object appears there as a key, then the reference is replaced with the corresponding value.

Nothing happens if `ref` is not active, or if the referenced object is not found in `replacaments`.

`ref` : | a GdaObjectRef object
`replacements` : | a GHashTable

### gda_object_ref_get_ref_name ()

    const gchar*        gda_object_ref_get_ref_name         (GdaObjectRef *ref,
                                                             GType *ref_type,
                                                             GdaObjectRefType *type);

Get the caracteristics of the requested object

`ref` : | a GdaObjectRef object
`ref_type` : | where to store the requested referenced object's data type, or NULL
`type` : | where to store how to interpret the returned name, or NULL
Returns : | the name of the object (to be interpreted with `type`)

### gda_object_ref_get_ref_object_name ()

    const gchar*        gda_object_ref_get_ref_object_name  (GdaObjectRef *ref);

Get the name (as returned by `gda_object_get_name()`) of the last object referenced

`ref` : | a GdaObjectRef object
Returns : | the name of the object (to be interpreted with `type`)

### gda_object_ref_get_ref_type ()

    GType               gda_object_ref_get_ref_type         (GdaObjectRef *ref);

Get the type of the referenced object by `ref` (or the requested type if `ref` is not active)

`ref` : | a GdaObjectRef object
Returns : | the type

### gda_object_ref_get_ref_object ()

    GdaObject*          gda_object_ref_get_ref_object       (GdaObjectRef *ref);

Get the referenced object by `ref`

`ref` : | a GdaObjectRef object
Returns : | a pointer to the object, or NULL if the reference is not active

### gda_object_ref_activate ()

    gboolean            gda_object_ref_activate             (GdaObjectRef *ref);

Tries to "activate" a reference (to find the referenced object). Nothing happens if the object is already activated

`ref` : | a GdaObjectRef object
Returns : | TRUE on success

### gda_object_ref_deactivate ()

    void                gda_object_ref_deactivate           (GdaObjectRef *ref);

Desctivates the object (loses the reference to the referenced object)

`ref` : | a GdaObjectRef object

### gda_object_ref_is_active ()

    gboolean            gda_object_ref_is_active            (GdaObjectRef *ref);

Find wether `ref` is active

`ref` : | a GdaObjectRef object
Returns : | TRUE if `ref` is active

## Property Details

### The `"helper-ref"` property

      "helper-ref"               GdaObject*            : Read / Write

### The `"obj-name"` property

      "obj-name"                 gchar*                : Read / Write

Default value: NULL

## Signal Details

### The `"ref-found"` signal

    void                user_function                      (GdaObjectRef *gdaobjectref,
                                                            gpointer      user_data)         : Run First

`dbrefbase` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"ref-lost"` signal

    void                user_function                      (GdaObjectRef *gdaobjectref,
                                                            gpointer      user_data)         : Run First

`dbrefbase` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.