GdaObject

## GdaObject GdaObject — The base class for many of the library's objects |

## Synopsis

                GdaObject;
    GdaDict*    gda_object_get_dict             (GdaObject *object);
    void        gda_object_set_id               (GdaObject *object,
                                                 const gchar *strid);
    void        gda_object_set_name             (GdaObject *object,
                                                 const gchar *name);
    void        gda_object_set_description      (GdaObject *object,
                                                 const gchar *descr);
    void        gda_object_set_owner            (GdaObject *object,
                                                 const gchar *owner);
    const gchar* gda_object_get_id              (GdaObject *object);
    const gchar* gda_object_get_id              (GdaObject *object);
    const gchar* gda_object_get_name            (GdaObject *object);
    const gchar* gda_object_get_description     (GdaObject *object);
    const gchar* gda_object_get_owner           (GdaObject *object);
    void        gda_object_destroy              (GdaObject *object);
    void        gda_object_destroy_check        (GdaObject *object);
    gulong      gda_object_connect_destroy      (gpointer object,
                                                 GCallback callback,
                                                 gpointer data);
    void        gda_object_changed              (GdaObject *object);
    void        gda_object_block_changed        (GdaObject *object);
    void        gda_object_unblock_changed      (GdaObject *object);
    void        gda_object_dump                 (GdaObject *object,
                                                 guint offset);

## Object Hierarchy

      GObject
       +----GdaObject
             +----GdaDataModelRow
             +----GdaDataModelImport
             +----GdaParameterList
             +----GdaDataModelQuery
             +----GdaDataAccessWrapper
             +----GdaDataProxy
             +----GdaDictAggregate
             +----GdaDictConstraint
             +----GdaDictDatabase
             +----GdaDictField
             +----GdaDictFunction
             +----GdaDictTable
             +----GdaDictType
             +----GdaGraphviz
             +----GdaObjectRef
             +----GdaParameter
             +----GdaQueryObject

## Known Derived Interfaces

GdaObject is required by GdaDataModel, GdaEntity, GdaEntityField and GdaXmlStorage.

## Properties

      "changed-blocked"      gboolean              : Read / Write
      "dict"                 gpointer              : Read / Write / Construct Only
      "string-id"            gchararray            : Read / Write

## Signal Prototypes

    "changed"   void        user_function      (GdaObject *gdaobject,
                                                gpointer user_data);
    "descr-changed"
                void        user_function      (GdaObject *gdaobject,
                                                gpointer user_data);
    "destroyed" void        user_function      (GdaObject *gdaobject,
                                                gpointer user_data);
    "id-changed"
                void        user_function      (GdaObject *gdaobject,
                                                gpointer user_data);
    "name-changed"
                void        user_function      (GdaObject *gdaobject,
                                                gpointer user_data);
    "owner-changed"
                void        user_function      (GdaObject *gdaobject,
                                                gpointer user_data);
    "to-be-destroyed"
                void        user_function      (GdaObject *gdaobject,
                                                gpointer user_data);

## Description

This class defines a common behaviour for most of the objects of this library. As the data dictionary is quite dynamic, the default way by which GObjects are managed (referenced and unreferenced when not needed anymore using g_object_[un]`ref()`) is not enough: sometimes this behaviour should be kept, and sometimes an object's destruction should be forced and all the other reference holders of that object should take appropriate actions and drop their reference on that object.

Just an example to illustrate this: suppose a data type has been removed from the database itself, then the corresponding GdaDictType must be destroyed since it does not represent a valid data type anymore. GdaDictType object are all managed by a GdaDict which has a reference on them. When the GdaDict object does a metadata sychronization (using `gda_dict_update_dbms_data()`), it calls `gda_object_destroy()` on the proper GdaDictType which must be destroyed. The other objects which did use tha particular GdaDictType object (such as GdaDictField and GdaDictFunction for example) catch the "destroy" signal which is emitted by the GdaDictType object being destroyed and take appropriate actions (in this case both these objects will destroy themselves and release any reference they had on the GdaDictType object). The reference count of the GdaDictType object being destroyed then should normally reach 0 and the destruction occur as for any other GObject object.

This class also introduces common attributes that can be exploited by the classes inheriting that class, such as:

- The GdaDict object to which any GdaObject relates

- The string ID of the object: any string which uniquely identifies a GdaObject within a dictionary

- The ID as a guint, the name, description and owner attached to the GdaObject.

## Details

### GdaObject

    typedef struct _GdaObject GdaObject;

### gda_object_get_dict ()

    GdaDict*    gda_object_get_dict             (GdaObject *object);

Fetch the corresponding GdaDict object.

`object` : |
Returns : | the GdaDict object to which `gdaobj` is attached to

### gda_object_set_id ()

    void        gda_object_set_id               (GdaObject *object,
                                                 const gchar *strid);

Sets the string ID of the `gdaobj` object.

The string ID must be unique for all the objects related to a given GdaDict object.

`object` : |
`strid` : | the string Identifier

### gda_object_set_name ()

    void        gda_object_set_name             (GdaObject *object,
                                                 const gchar *name);

Sets the name of the GdaObject object. If the name is changed, then the "name_changed" signal is emitted.

`object` : |
`name` : |

### gda_object_set_description ()

    void        gda_object_set_description      (GdaObject *object,
                                                 const gchar *descr);

Sets the description of the GdaObject object. If the description is changed, then the "descr_changed" signal is emitted.

`object` : |
`descr` : |

### gda_object_set_owner ()

    void        gda_object_set_owner            (GdaObject *object,
                                                 const gchar *owner);

Sets the owner of the GdaObject object. If the owner is changed, then the "owner_changed" signal is emitted.

`object` : |
`owner` : |

### gda_object_get_id ()

    const gchar* gda_object_get_id              (GdaObject *object);

Fetch the string ID of the GdaObject object.

`object` : |
Returns : | the id.

### gda_object_get_id ()

    const gchar* gda_object_get_id              (GdaObject *object);

Fetch the string ID of the GdaObject object.

`object` : |
Returns : | the id.

### gda_object_get_name ()

    const gchar* gda_object_get_name            (GdaObject *object);

Fetch the name of the GdaObject object.

`object` : |
Returns : | the object's name.

### gda_object_get_description ()

    const gchar* gda_object_get_description     (GdaObject *object);

Fetch the description of the GdaObject object.

`object` : |
Returns : | the object's description.

### gda_object_get_owner ()

    const gchar* gda_object_get_owner           (GdaObject *object);

Fetch the owner of the GdaObject object.

`object` : |
Returns : | the object's owner.

### gda_object_destroy ()

    void        gda_object_destroy              (GdaObject *object);

Force the `gdaobj` object to be destroyed, even if we don't have a reference on it (we can't call `g_object_unref()` then) and even if the object is referenced multiple times by other objects.

The "destroyed" signal is then emitted to tell the other reference holders that the object must be destroyed and that they should give back their reference (using `g_object_unref()`). However if a reference is still present, the object will not actually be destroyed and will still be alive, but its state may not be deterministic.

This is usefull because sometimes objects need to disappear even if they are referenced by other objects. This usage is the same as with the `gtk_widget_destroy()` function on widgets.

When this method returns, `gdaobj` should have been destroyed and should not be used anymore.

`object` : |

### gda_object_destroy_check ()

    void        gda_object_destroy_check        (GdaObject *object);

Checks that the object has been destroyed, and if not, then calls `gda_object_destroy()` on it. This is usefull for objects inheriting the GdaObject object to be called first line in their `dispose()` method.

`object` : |

### gda_object_connect_destroy ()

    gulong      gda_object_connect_destroy      (gpointer object,
                                                 GCallback callback,
                                                 gpointer data);

Connects the "destoy" signal of the `gdaobj` object but first cheks that `gdaobj` exists and has not yet been destroyed.

`object` : |
`callback` : |
`data` : |
Returns : | the handler id of the signal

### gda_object_changed ()

    void        gda_object_changed              (GdaObject *object);

Force emission of the "changed" signal, except if `gda_object_block_changed()` has been called.

`object` : |

### gda_object_block_changed ()

    void        gda_object_block_changed        (GdaObject *object);

No "changed" signal will be emitted.

`object` : |

### gda_object_unblock_changed ()

    void        gda_object_unblock_changed      (GdaObject *object);

The "changed" signal will again be emitted.

`object` : |

### gda_object_dump ()

    void        gda_object_dump                 (GdaObject *object,
                                                 guint offset);

Writes a textual description of the object to STDOUT. This function only exists if libergeant is compiled with the "--enable-debug" option. This is a virtual function.

`object` : |
`offset` : | the offset (in caracters) at which the dump will start

## Properties

### The "`changed-blocked`" property

      "changed-blocked"      gboolean              : Read / Write

Default value: FALSE

### The "`dict`" property

      "dict"                 gpointer              : Read / Write / Construct Only

Dictionary to which the object is related.

### The "`string-id`" property

      "string-id"            gchararray            : Read / Write

Default value: NULL

## Signals

### The "changed" signal

    void        user_function                  (GdaObject *gdaobject,
                                                gpointer user_data);

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

### The "descr-changed" signal

    void        user_function                  (GdaObject *gdaobject,
                                                gpointer user_data);

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

### The "destroyed" signal

    void        user_function                  (GdaObject *gdaobject,
                                                gpointer user_data);

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

### The "id-changed" signal

    void        user_function                  (GdaObject *gdaobject,
                                                gpointer user_data);

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

### The "name-changed" signal

    void        user_function                  (GdaObject *gdaobject,
                                                gpointer user_data);

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

### The "owner-changed" signal

    void        user_function                  (GdaObject *gdaobject,
                                                gpointer user_data);

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

### The "to-be-destroyed" signal

    void        user_function                  (GdaObject *gdaobject,
                                                gpointer user_data);

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