## GnomeDbDict

GnomeDbDict — GnomeDb dictionary

##

# Synopsis

    struct      GnomeDbDict;
    struct      GnomeDbDictPrivate;
    GType       gnome_db_dict_get_type          (void);
    GObject*    gnome_db_dict_new               (void);
    gchar*      gnome_db_dict_compute_xml_filename
                                                (GnomeDbDict *dict,
                                                 const gchar *datasource,
                                                 const gchar *app_id,
                                                 GError **error);
    void        gnome_db_dict_set_xml_filename  (GnomeDbDict *dict,
                                                 const gchar *xmlfile);
    const gchar* gnome_db_dict_get_xml_filename (GnomeDbDict *dict);
    gboolean    gnome_db_dict_load_xml          (GnomeDbDict *dict,
                                                 GError **error);
    gboolean    gnome_db_dict_save_xml          (GnomeDbDict *dict,
                                                 GError **error);
    gboolean    gnome_db_dict_load_xml_file     (GnomeDbDict *dict,
                                                 const gchar *xmlfile,
                                                 GError **error);
    gboolean    gnome_db_dict_save_xml_file     (GnomeDbDict *dict,
                                                 const gchar *xmlfile,
                                                 GError **error);
    void        gnome_db_dict_declare_query     (GnomeDbDict *dict,
                                                 GnomeDbQuery *query);
    void        gnome_db_dict_assume_query      (GnomeDbDict *dict,
                                                 GnomeDbQuery *query);
    void        gnome_db_dict_unassume_query    (GnomeDbDict *dict,
                                                 GnomeDbQuery *query);
    GSList*     gnome_db_dict_get_queries       (GnomeDbDict *dict);
    GnomeDbQuery* gnome_db_dict_get_query_by_xml_id
                                                (GnomeDbDict *dict,
                                                 const gchar *xml_id);
    void        gnome_db_dict_declare_graph     (GnomeDbDict *dict,
                                                 GnomeDbGraph *graph);
    void        gnome_db_dict_assume_graph      (GnomeDbDict *dict,
                                                 GnomeDbGraph *graph);
    void        gnome_db_dict_unassume_graph    (GnomeDbDict *dict,
                                                 GnomeDbGraph *graph);
    GSList*     gnome_db_dict_get_graphs        (GnomeDbDict *dict,
                                                 GnomeDbGraphType type_of_graphs);
    GnomeDbGraph* gnome_db_dict_get_graph_by_xml_id
                                                (GnomeDbDict *dict,
                                                 const gchar *xml_id);
    GnomeDbGraph* gnome_db_dict_get_graph_for_object
                                                (GnomeDbDict *dict,
                                                 GObject *obj);
    void        gnome_db_dict_declare_layout    (GnomeDbDict *dict,
                                                 GnomeDbCustomLayout *layout);
    void        gnome_db_dict_assume_layout     (GnomeDbDict *dict,
                                                 GnomeDbCustomLayout *layout);
    void        gnome_db_dict_unassume_layout   (GnomeDbDict *dict,
                                                 GnomeDbCustomLayout *layout);
    GSList*     gnome_db_dict_get_layouts       (GnomeDbDict *dict);
    GnomeDbCustomLayout* gnome_db_dict_get_layout_by_xml_id
                                                (GnomeDbDict *dict,
                                                 const gchar *xml_id);
    GnomeDbServer* gnome_db_dict_get_server     (GnomeDbDict *dict);
    GnomeDbDatabase* gnome_db_dict_get_database (GnomeDbDict *dict);
    GSList*     gnome_db_dict_get_entities_fk_constraints
                                                (GnomeDbDict *dict,
                                                 GnomeDbEntity *entity1,
                                                 GnomeDbEntity *entity2,
                                                 gboolean entity1_has_fk);
    void        gnome_db_dict_dump              (GnomeDbDict *dict);

## Object Hierarchy

      GObject
       +----GnomeDbDict

## Properties

      "graph-serial"         guint                : Read
      "layout-serial"        guint                : Read
      "query-serial"         guint                : Read

## Signal Prototypes

    "changed"   void        user_function      (GnomeDbDict *dbdict,
                                                gpointer user_data);
    "graph-added"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);
    "graph-removed"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);
    "graph-updated"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);
    "layout-added"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);
    "layout-removed"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);
    "layout-updated"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);
    "query-added"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);
    "query-removed"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);
    "query-updated"
                void        user_function      (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

## Description

This object is a "container" for all the objects which are used within the libgnomedb library: connection to the DBMS server (through a GnomeDbServer object), database structure (through a GnomeDbDatabase object) and queries (GnomeDbQuery objects).

There MUST be a GnomeDbDict object for each connection to a DBMS, and there can be several ones at the same time. The GnomeDbDict object, when instantiated, will create a GnomeDbServer and a GnomeDbDatabase objects; the other objects will be created as necessary when an XML file is loaded.

When the GnomeDbDict object is destroyed, it calls `mg_base_nullify()` on _ALL_ the GnomeDbQuery objects which have been defined at any point using that GnomeDbDict object. So, this means that any object/widget creating GnomeDbQuery objects for their own purpose must make sure to listen to the "nullified" signal of every GnomeDbQuery they created (and release any reference they might have using `g_object_unref()`), unless of course they are always destroyed before the GnomeDbDict object is itself destroyed.

The libgnomedb library has de default builtin dictionary object created when the `gnome_db_init()` function is called, which can be retreived using the `gnome_db_get_default_dict()` function.

## Details

### struct GnomeDbDict

    struct GnomeDbDict;

### struct GnomeDbDictPrivate

    struct GnomeDbDictPrivate;

### gnome_db_dict_get_type ()

    GType       gnome_db_dict_get_type          (void);

Returns : |

### gnome_db_dict_new ()

    GObject*    gnome_db_dict_new               (void);

Create a new GnomeDbDict object.

Returns : | the newly created object.

### gnome_db_dict_compute_xml_filename ()

    gchar*      gnome_db_dict_compute_xml_filename
                                                (GnomeDbDict *dict,
                                                 const gchar *datasource,
                                                 const gchar *app_id,
                                                 GError **error);

Get the prefered filename which represents the data dictionary associated to the `datasource` data source. Using the returned value in conjunction with `gnome_db_dict_load_xml_file()` and `gnome_db_dict_save_xml_file()` has the advantage of letting the library handle file naming onventions.

The `app_id` argument allows to give an extra identification to the request, when some special features must be saved but not interfere with the default dictionary.

`dict` : | a GnomeDbDict object
`datasource` : | a data source
`app_id` : | an extra identification, or `NULL`
`error` : | location to store error, or `NULL`
Returns : | a new string

### gnome_db_dict_set_xml_filename ()

    void        gnome_db_dict_set_xml_filename  (GnomeDbDict *dict,
                                                 const gchar *xmlfile);

Sets the filename `dict` will use when `gnome_db_dict_save_xml()` and `gnome_db_dict_load_xml()` are called.

`dict` : | a GnomeDbDict object
`xmlfile` : | a file name

### gnome_db_dict_get_xml_filename ()

    const gchar* gnome_db_dict_get_xml_filename (GnomeDbDict *dict);

Get the filename `dict` will use when `gnome_db_dict_save_xml()` and `gnome_db_dict_load_xml()` are called.

`dict` : | a GnomeDbDict object
Returns : | the filename, or `NULL` if none have been set.

### gnome_db_dict_load_xml ()

    gboolean    gnome_db_dict_load_xml          (GnomeDbDict *dict,
                                                 GError **error);

Loads an XML file which respects the Libgnomedb DTD, and creates all the necessary objects that are defined within the XML file. During the creation of the other objects, all the normal signals are emitted.

If the GnomeDbDict object already has some contents, then it is first of all nullified (to return its state as when it was first created).

If an error occurs during loading then the GnomeDbDict object is left as empty as when it is first created.

The file loaded is the one specified using `gnome_db_dict_set_xml_filename()`

`dict` : | a GnomeDbDict object
`error` : | location to store error, or `NULL`
Returns : | TRUE if loading was successfull and FALSE otherwise.

### gnome_db_dict_save_xml ()

    gboolean    gnome_db_dict_save_xml          (GnomeDbDict *dict,
                                                 GError **error);

Saves the contents of a GnomeDbDict object to a file which is specified using the `gnome_db_dict_set_xml_filename()` method.

`dict` : | a GnomeDbDict object
`error` : | location to store error, or `NULL`
Returns : | TRUE if saving was successfull and FALSE otherwise.

### gnome_db_dict_load_xml_file ()

    gboolean    gnome_db_dict_load_xml_file     (GnomeDbDict *dict,
                                                 const gchar *xmlfile,
                                                 GError **error);

Loads an XML file which respects the Libgnomedb DTD, and creates all the necessary objects that are defined within the XML file. During the creation of the other objects, all the normal signals are emitted.

If the GnomeDbDict object already has some contents, then it is first of all nullified (to return its state as when it was first created).

If an error occurs during loading then the GnomeDbDict object is left as empty as when it is first created.

`dict` : | a GnomeDbDict object
`xmlfile` : | the name of the file to which the XML will be written to
`error` : | location to store error, or `NULL`
Returns : | TRUE if loading was successfull and FALSE otherwise.

### gnome_db_dict_save_xml_file ()

    gboolean    gnome_db_dict_save_xml_file     (GnomeDbDict *dict,
                                                 const gchar *xmlfile,
                                                 GError **error);

Saves the contents of a GnomeDbDict object to a file which is given as argument.

`dict` : | a GnomeDbDict object
`xmlfile` : | the name of the file to which the XML will be written to
`error` : | location to store error, or `NULL`
Returns : | TRUE if saving was successfull and FALSE otherwise.

### gnome_db_dict_declare_query ()

    void        gnome_db_dict_declare_query     (GnomeDbDict *dict,
                                                 GnomeDbQuery *query);

Declares the existence of a new query to `dict`. All the GnomeDbQuery objects MUST be declared to the corresponding GnomeDbDict object for the library to work correctly. Once `query` has been declared, `dict` does not hold any reference to `query`. If `dict` must hold such a reference, then use `gnome_db_dict_assume_query()`.

This functions is called automatically from each gnome_db_query_new* function, and it should not be necessary to call it except for classes extending the GnomeDbQuery class.

`dict` : | a GnomeDbDict object
`query` : | a GnomeDbQuery object

### gnome_db_dict_assume_query ()

    void        gnome_db_dict_assume_query      (GnomeDbDict *dict,
                                                 GnomeDbQuery *query);

Force `dict` to manage `query`: it will get a reference to it.

`dict` : | a GnomeDbDict object
`query` : | a GnomeDbQuery object

### gnome_db_dict_unassume_query ()

    void        gnome_db_dict_unassume_query    (GnomeDbDict *dict,
                                                 GnomeDbQuery *query);

Forces `dict` to lose a reference it has on `query`

`dict` : | a GnomeDbDict object
`query` : | a GnomeDbQuery object

### gnome_db_dict_get_queries ()

    GSList*     gnome_db_dict_get_queries       (GnomeDbDict *dict);

Get a list of all the non interdependant queries managed by `dict` (only queries with no parent query are listed)

`dict` : | a GnomeDbDict object
Returns : | a new list of GnomeDbQuery objects

### gnome_db_dict_get_query_by_xml_id ()

    GnomeDbQuery* gnome_db_dict_get_query_by_xml_id
                                                (GnomeDbDict *dict,
                                                 const gchar *xml_id);

Find a GnomeDbQuery object from its XML Id

`dict` : | a GnomeDbDict object
`xml_id` : | the XML Id of the query being searched
Returns : | the GnomeDbQuery object, or NULL if not found

### gnome_db_dict_declare_graph ()

    void        gnome_db_dict_declare_graph     (GnomeDbDict *dict,
                                                 GnomeDbGraph *graph);

Declares the existence of a new graph to `dict`. All the GnomeDbGraph objects MUST be declared to the corresponding GnomeDbDict object for the library to work correctly. Once `graph` has been declared, `dict` does not hold any reference to `graph`. If `dict` must hold such a reference, then use `gnome_db_dict_assume_graph()`.

This functions is called automatically from each gnome_db_graph_new* function, and it should not be necessary to call it except for classes extending the GnomeDbGraph class.

`dict` : | a GnomeDbDict object
`graph` : | a GnomeDbGraph object

### gnome_db_dict_assume_graph ()

    void        gnome_db_dict_assume_graph      (GnomeDbDict *dict,
                                                 GnomeDbGraph *graph);

Force `dict` to manage `graph`: it will get a reference to it.

`dict` : | a GnomeDbDict object
`graph` : | a GnomeDbGraph object

### gnome_db_dict_unassume_graph ()

    void        gnome_db_dict_unassume_graph    (GnomeDbDict *dict,
                                                 GnomeDbGraph *graph);

Forces `dict` to lose a reference it has on `graph`

`dict` : | a GnomeDbDict object
`graph` : | a GnomeDbGraph object

### gnome_db_dict_get_graphs ()

    GSList*     gnome_db_dict_get_graphs        (GnomeDbDict *dict,
                                                 GnomeDbGraphType type_of_graphs);

Get a list of the graphs managed by `dict`, which are of the requested type.

`dict` : | a GnomeDbDict object
`type_of_graphs` : | the requested type of graphs
Returns : | a new list of GnomeDbGraph objects

### gnome_db_dict_get_graph_by_xml_id ()

    GnomeDbGraph* gnome_db_dict_get_graph_by_xml_id
                                                (GnomeDbDict *dict,
                                                 const gchar *xml_id);

Find a GnomeDbGraph object from its XML Id

`dict` : | a GnomeDbDict object
`xml_id` : | the XML Id of the graph being searched
Returns : | the GnomeDbGraph object, or NULL if not found

### gnome_db_dict_get_graph_for_object ()

    GnomeDbGraph* gnome_db_dict_get_graph_for_object
                                                (GnomeDbDict *dict,
                                                 GObject *obj);

Find a GnomeDbGraph object guiven the object it is related to.

`dict` : | a GnomeDbDict object
`obj` : | a Gobject object
Returns : | the GnomeDbGraph object, or NULL if not found

### gnome_db_dict_declare_layout ()

    void        gnome_db_dict_declare_layout    (GnomeDbDict *dict,
                                                 GnomeDbCustomLayout *layout);

Declares the existence of a new layout to `dict`. All the GnomeDbCustomLayout objects MUST be declared to the corresponding GnomeDbDict object for the library to work correctly. Once `layout` has been declared, `dict` does not hold any reference to `layout`. If `dict` must hold such a reference, then use `gnome_db_dict_assume_layout()`.

This functions is called automatically from each gnome_db_layout_new* function, and it should not be necessary to call it except for classes extending the GnomeDbCustomLayout class.

`dict` : | a GnomeDbDict object
`layout` : | a GnomeDbLayout object

### gnome_db_dict_assume_layout ()

    void        gnome_db_dict_assume_layout     (GnomeDbDict *dict,
                                                 GnomeDbCustomLayout *layout);

Force `dict` to manage `layout`: it will get a reference to it.

`dict` : | a GnomeDbDict object
`layout` : | a GnomeDbCustomLayout object

### gnome_db_dict_unassume_layout ()

    void        gnome_db_dict_unassume_layout   (GnomeDbDict *dict,
                                                 GnomeDbCustomLayout *layout);

Forces `dict` to lose a reference it has on `layout`

`dict` : | a GnomeDbDict object
`layout` : | a GnomeDbCustomLayout object

### gnome_db_dict_get_layouts ()

    GSList*     gnome_db_dict_get_layouts       (GnomeDbDict *dict);

Get a list of all the layouts managed by `dict`

`dict` : | a GnomeDbDict object
Returns : | a new list of GnomeDbCustomLayout objects

### gnome_db_dict_get_layout_by_xml_id ()

    GnomeDbCustomLayout* gnome_db_dict_get_layout_by_xml_id
                                                (GnomeDbDict *dict,
                                                 const gchar *xml_id);

Find a GnomeDbCustomLayout object from its XML Id

`dict` : | a GnomeDbDict object
`xml_id` : | the XML Id of the layout being searched
Returns : | the GnomeDbCustomLayout object, or NULL if not found

### gnome_db_dict_get_server ()

    GnomeDbServer* gnome_db_dict_get_server     (GnomeDbDict *dict);

Fetch a pointer to the GnomeDbServer used by the GnomeDbDict object.

`dict` : | a GnomeDbDict object
Returns : | a pointer to the GnomeDbServer

### gnome_db_dict_get_database ()

    GnomeDbDatabase* gnome_db_dict_get_database (GnomeDbDict *dict);

Fetch a pointer to the GnomeDbDatabase used by the GnomeDbDict object.

`dict` : | a GnomeDbDict object
Returns : | a pointer to the GnomeDbDatabase

### gnome_db_dict_get_entities_fk_constraints ()

    GSList*     gnome_db_dict_get_entities_fk_constraints
                                                (GnomeDbDict *dict,
                                                 GnomeDbEntity *entity1,
                                                 GnomeDbEntity *entity2,
                                                 gboolean entity1_has_fk);

Get a list of all the constraints which represent a foreign constrains, between `entity1` and `entity2`. If `entity1` and `entity2` are GnomeDbTable objects, then the constraints are the ones from the database.

Constraints are represented as GnomeDbConstraint objects.

`dict` : | a GnomeDbDict object
`entity1` : | an object implementing the GnomeDbEntity interface
`entity2` : | an object implementing the GnomeDbEntity interface
`entity1_has_fk` : | TRUE if the returned constraints are the one for which `entity1` contains the foreign key
Returns : | a new list of the constraints

### gnome_db_dict_dump ()

    void        gnome_db_dict_dump              (GnomeDbDict *dict);

Dumps the whole dictionary managed by the GnomeDbDict object

`dict` : | a GnomeDbDict object

## Properties

"`graph-serial`" (guint : Read) |
"`layout-serial`" (guint : Read) |
"`query-serial`" (guint : Read) |

## Signals

### The "changed" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer user_data);

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

### The "graph-added" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "graph-removed" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "graph-updated" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "layout-added" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "layout-removed" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "layout-updated" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "query-added" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "query-removed" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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

### The "query-updated" signal

    void        user_function                  (GnomeDbDict *dbdict,
                                                gpointer arg1,
                                                gpointer user_data);

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