## MgRefBase

MgRefBase — Used to reference other objects

## Synopsis

    enum        MgRefBaseType;
    struct      MgRefBase;
    guint       mg_ref_base_get_type            (void);
    GObject*    mg_ref_base_new                 (MgConf *conf);
    GObject*    mg_ref_base_new_copy            (MgRefBase *orig);
    void        mg_ref_base_set_ref_name        (MgRefBase *ref,
                                                 GType ref_type,
                                                 MgRefBaseType type,
                                                 const gchar *name);
    const gchar* mg_ref_base_get_ref_name       (MgRefBase *ref,
                                                 GType *ref_type,
                                                 MgRefBaseType *type);
    GType       mg_ref_base_get_ref_type        (MgRefBase *ref);
    void        mg_ref_base_set_ref_object      (MgRefBase *ref,
                                                 MgBase *object);
    void        mg_ref_base_set_ref_object_type (MgRefBase *ref,
                                                 MgBase *object,
                                                 GType type);
    void        mg_ref_base_replace_ref_object  (MgRefBase *ref,
                                                 GHashTable *replacements);
    MgBase*     mg_ref_base_get_ref_object      (MgRefBase *ref);
    gboolean    mg_ref_base_activate            (MgRefBase *ref);
    void        mg_ref_base_deactivate          (MgRefBase *ref);
    gboolean    mg_ref_base_is_active           (MgRefBase *ref);

## Object Hierarchy

      GObject
       +----MgBase
             +----MgRefBase

## Properties

      "prop"                 gpointer             : Read / Write

## Signal Prototypes

    "ref-found" void        user_function      (MgRefBase *mgrefbase,
                                                gpointer user_data);
    "ref-lost"  void        user_function      (MgRefBase *mgrefbase,
                                                gpointer user_data);

## 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 MgRefBase object, give it the xml ID or name of the object which is to be referenced, and activate the MgRefBase object. If it is activated, then the real object can be fetched through the MgRefBase object.

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

- MgDbTable

- MgDbField

- MgQuery

- MgTarget

- MgField (for any MgDbField of MgQfield object)

## Details

### enum MgRefBaseType

    typedef enum
    {
    	REFERENCE_BY_XML_ID,
    	REFERENCE_BY_NAME
    } MgRefBaseType;

### struct MgRefBase

    struct MgRefBase;

### mg_ref_base_get_type ()

    guint       mg_ref_base_get_type            (void);

Returns : |

### mg_ref_base_new ()

    GObject*    mg_ref_base_new                 (MgConf *conf);

Creates a new MgRefBase object

`conf` : | a MgConf object
Returns : | the new object

### mg_ref_base_new_copy ()

    GObject*    mg_ref_base_new_copy            (MgRefBase *orig);

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

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

### mg_ref_base_set_ref_name ()

    void        mg_ref_base_set_ref_name        (MgRefBase *ref,
                                                 GType ref_type,
                                                 MgRefBaseType 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 MgRefBase 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

### mg_ref_base_get_ref_name ()

    const gchar* mg_ref_base_get_ref_name       (MgRefBase *ref,
                                                 GType *ref_type,
                                                 MgRefBaseType *type);

Get the caracteristics of the requested object

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

### mg_ref_base_get_ref_type ()

    GType       mg_ref_base_get_ref_type        (MgRefBase *ref);

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

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

### mg_ref_base_set_ref_object ()

    void        mg_ref_base_set_ref_object      (MgRefBase *ref,
                                                 MgBase *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 MgRefBase object
`object` : | the object to keep a reference to

### mg_ref_base_set_ref_object_type ()

    void        mg_ref_base_set_ref_object_type (MgRefBase *ref,
                                                 MgBase *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 MgRefBase 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`

### mg_ref_base_replace_ref_object ()

    void        mg_ref_base_replace_ref_object  (MgRefBase *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 MgRefBase object
`replacements` : | a GHashTable

### mg_ref_base_get_ref_object ()

    MgBase*     mg_ref_base_get_ref_object      (MgRefBase *ref);

Get the referenced object by `ref`

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

### mg_ref_base_activate ()

    gboolean    mg_ref_base_activate            (MgRefBase *ref);

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

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

### mg_ref_base_deactivate ()

    void        mg_ref_base_deactivate          (MgRefBase *ref);

Desctivates the object (loses the reference to the object)

`ref` : | a MgRefBase object

### mg_ref_base_is_active ()

    gboolean    mg_ref_base_is_active           (MgRefBase *ref);

Find wether `ref` is active

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

## Properties

"`prop`" (gpointer : Read / Write) |

## Signals

### The "ref-found" signal

    void        user_function                  (MgRefBase *mgrefbase,
                                                gpointer user_data);

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

### The "ref-lost" signal

    void        user_function                  (MgRefBase *mgrefbase,
                                                gpointer user_data);

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