GdaObjectRef

GdaObjectRef — Used to reference other objects

Functions

Properties

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

Signals

void ref-found Run First
void ref-lost Run First

Types and Values

Object Hierarchy

    GObject
    ╰── GdaObject
        ╰── GdaObjectRef

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:

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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

Parameters

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

Parameters

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)

Parameters

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

Parameters

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

Parameters

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)

Parameters

ref

a GdaObjectRef object

 

gda_object_ref_is_active ()

gboolean
gda_object_ref_is_active (GdaObjectRef *ref);

Find wether ref is active

Parameters

ref

a GdaObjectRef object

 

Returns

TRUE if ref is active

Types and Values

GdaObjectRef

typedef struct _GdaObjectRef GdaObjectRef;


enum GdaObjectRefType

Members

REFERENCE_BY_XML_ID

   

REFERENCE_BY_NAME

   

Property Details

The “helper-ref” property

  “helper-ref”               GdaObject *

Flags: Read / Write


The “obj-name” property

  “obj-name”                 gchar *

Flags: Read / Write

Default value: NULL

Signal Details

The “ref-found” signal

void
user_function (GdaObjectRef *gdaobjectref,
               gpointer      user_data)

Parameters

dbrefbase

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “ref-lost” signal

void
user_function (GdaObjectRef *gdaobjectref,
               gpointer      user_data)

Parameters

dbrefbase

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First