GnomeDbRefBase

GnomeDbRefBase — Used to reference other objects

Synopsis




enum        GnomeDbRefBaseType;
            GnomeDbRefBase;
GType       gnome_db_ref_base_get_type      (void);
GObject*    gnome_db_ref_base_new           (GnomeDbDict *dict);
GObject*    gnome_db_ref_base_new_no_ref_count
                                            (GnomeDbDict *dict);
GObject*    gnome_db_ref_base_new_copy      (GnomeDbRefBase *orig);
void        gnome_db_ref_base_set_ref_name  (GnomeDbRefBase *ref,
                                             GType ref_type,
                                             GnomeDbRefBaseType type,
                                             const gchar *name);
const gchar* gnome_db_ref_base_get_ref_name (GnomeDbRefBase *ref,
                                             GType *ref_type,
                                             GnomeDbRefBaseType *type);
GType       gnome_db_ref_base_get_ref_type  (GnomeDbRefBase *ref);
void        gnome_db_ref_base_set_ref_object
                                            (GnomeDbRefBase *ref,
                                             GnomeDbBase *object);
void        gnome_db_ref_base_set_ref_object_type
                                            (GnomeDbRefBase *ref,
                                             GnomeDbBase *object,
                                             GType type);
void        gnome_db_ref_base_replace_ref_object
                                            (GnomeDbRefBase *ref,
                                             GHashTable *replacements);
GnomeDbBase* gnome_db_ref_base_get_ref_object
                                            (GnomeDbRefBase *ref);
gboolean    gnome_db_ref_base_activate      (GnomeDbRefBase *ref);
void        gnome_db_ref_base_deactivate    (GnomeDbRefBase *ref);
gboolean    gnome_db_ref_base_is_active     (GnomeDbRefBase *ref);

Object Hierarchy


  GObject
   +----GnomeDbBase
         +----GnomeDbRefBase

Properties


  "prop"                 gpointer              : Read / Write

Signals


"ref-found" void        user_function      (GnomeDbRefBase *dbrefbase,
                                            gpointer        user_data)      : Run first
"ref-lost"  void        user_function      (GnomeDbRefBase *dbrefbase,
                                            gpointer        user_data)      : 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 GnomeDbRefBase object, give it the xml ID or name of the object which is to be referenced, and activate the GnomeDbRefBase object. If it is activated, then the real object can be fetched through the GnomeDbRefBase object.

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

Details

enum GnomeDbRefBaseType

typedef enum
{
	REFERENCE_BY_XML_ID,
	REFERENCE_BY_NAME
} GnomeDbRefBaseType;


GnomeDbRefBase

typedef struct _GnomeDbRefBase GnomeDbRefBase;


gnome_db_ref_base_get_type ()

GType       gnome_db_ref_base_get_type      (void);

Returns :

gnome_db_ref_base_new ()

GObject*    gnome_db_ref_base_new           (GnomeDbDict *dict);

Creates a new GnomeDbRefBase object. This GnomeDbRefBase 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 GnomeDbRefBase still has a reference on it. Use gnome_db_ref_base_new_no_ref_count() if you don't want to increase the reference count of the referenced object.

dict : a GnomeDbDict object
Returns : the new object

gnome_db_ref_base_new_no_ref_count ()

GObject*    gnome_db_ref_base_new_no_ref_count
                                            (GnomeDbDict *dict);

Creates a new GnomeDbRefBase object. This GnomeDbRefBase 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 gnome_db_ref_base_new() if you want to increase the count of the referenced object.

dict : a GnomeDbDict object
Returns : the new object

gnome_db_ref_base_new_copy ()

GObject*    gnome_db_ref_base_new_copy      (GnomeDbRefBase *orig);

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

orig : a GnomeDbRefBase object
Returns : the new object

gnome_db_ref_base_set_ref_name ()

void        gnome_db_ref_base_set_ref_name  (GnomeDbRefBase *ref,
                                             GType ref_type,
                                             GnomeDbRefBaseType 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 GnomeDbRefBase 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

gnome_db_ref_base_get_ref_name ()

const gchar* gnome_db_ref_base_get_ref_name (GnomeDbRefBase *ref,
                                             GType *ref_type,
                                             GnomeDbRefBaseType *type);

Get the caracteristics of the requested object

ref : a GnomeDbRefBase 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)

gnome_db_ref_base_get_ref_type ()

GType       gnome_db_ref_base_get_ref_type  (GnomeDbRefBase *ref);

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

ref : a GnomeDbRefBase object
Returns : the type

gnome_db_ref_base_set_ref_object ()

void        gnome_db_ref_base_set_ref_object
                                            (GnomeDbRefBase *ref,
                                             GnomeDbBase *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 GnomeDbRefBase object
object : the object to keep a reference to

gnome_db_ref_base_set_ref_object_type ()

void        gnome_db_ref_base_set_ref_object_type
                                            (GnomeDbRefBase *ref,
                                             GnomeDbBase *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 GnomeDbRefBase 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

gnome_db_ref_base_replace_ref_object ()

void        gnome_db_ref_base_replace_ref_object
                                            (GnomeDbRefBase *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 GnomeDbRefBase object
replacements : a GHashTable

gnome_db_ref_base_get_ref_object ()

GnomeDbBase* gnome_db_ref_base_get_ref_object
                                            (GnomeDbRefBase *ref);

Get the referenced object by ref

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

gnome_db_ref_base_activate ()

gboolean    gnome_db_ref_base_activate      (GnomeDbRefBase *ref);

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

ref : a GnomeDbRefBase object
Returns : TRUE on success

gnome_db_ref_base_deactivate ()

void        gnome_db_ref_base_deactivate    (GnomeDbRefBase *ref);

Desctivates the object (loses the reference to the object)

ref : a GnomeDbRefBase object

gnome_db_ref_base_is_active ()

gboolean    gnome_db_ref_base_is_active     (GnomeDbRefBase *ref);

Find wether ref is active

ref : a GnomeDbRefBase object
Returns : TRUE if ref is active

Property Details

The "prop" property

  "prop"                 gpointer              : Read / Write

Signal Details

The "ref-found" signal

void        user_function                  (GnomeDbRefBase *dbrefbase,
                                            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                  (GnomeDbRefBase *dbrefbase,
                                            gpointer        user_data)      : Run first

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