## GnomeDbCustomLayout

GnomeDbCustomLayout — Object to store the model part of custom layouts

## Synopsis

    enum        GnomeDbCustomLayoutType;
    GType       gnome_db_custom_layout_get_type (void);
    GObject*    gnome_db_custom_layout_new      (GnomeDbDict *dict);
    GnomeDbCustomLayoutType gnome_db_custom_layout_get_layout_type
                                                (GnomeDbCustomLayout *layout);
    GnomeDbCustomLayoutData* gnome_db_custom_layout_get_data
                                                (GnomeDbCustomLayout *layout,
                                                 GError **error);
    void        gnome_db_custom_layout_data_free
                                                (GnomeDbCustomLayoutData *data);
    GladeXML*   gnome_db_custom_layout_get_glade_instance
                                                (GnomeDbCustomLayout *layout,
                                                 GtkWidget **root_widget,
                                                 GHashTable **box_widgets,
                                                 GError **error);
    GtkWidget*  gnome_db_custom_layout_get_widget
                                                (GnomeDbCustomLayout *layout,
                                                 GError **error);
    GnomeDbDataSet* gnome_db_custom_layout_get_exec_context
                                                (GnomeDbCustomLayout *layout);
    GnomeDbDataSet* gnome_db_custom_layout_get_data_context
                                                (GnomeDbCustomLayout *layout);

## Description

Custom layouts (forms) are specifications to dispose GnomeDbDataWidget widgets in a specific fashion (using a Glade file for instance) and to link the data displayed in each GnomeDbDataWidget to the other ones. This way complex layouts can be done with minimal work.

## Details

### enum GnomeDbCustomLayoutType

    typedef enum {
    	GNOME_DB_CUSTOM_LAYOUT_LAYOUT,
    	GNOME_DB_CUSTOM_LAYOUT_GRID,
    	GNOME_DB_CUSTOM_LAYOUT_FORM,
    	GNOME_DB_CUSTOM_LAYOUT_MATRIX
    } GnomeDbCustomLayoutType;

### gnome_db_custom_layout_get_type ()

    GType       gnome_db_custom_layout_get_type (void);

Returns : |

### gnome_db_custom_layout_new ()

    GObject*    gnome_db_custom_layout_new      (GnomeDbDict *dict);

Creates a new GnomeDbCustomLayout object

`dict` : | a GnomeDbDict object
Returns : | a new GnomeDbCustomLayout object

### gnome_db_custom_layout_get_layout_type ()

    GnomeDbCustomLayoutType gnome_db_custom_layout_get_layout_type
                                                (GnomeDbCustomLayout *layout);

Get the kind of custom layout `layout` is.

`layout` : | a GnomeDbCustomLayout object
Returns : |

### gnome_db_custom_layout_get_data ()

    GnomeDbCustomLayoutData* gnome_db_custom_layout_get_data
                                                (GnomeDbCustomLayout *layout,
                                                 GError **error);

Retreive all the information stored in `layout` to be able to create GnomeDbWorkLayout objects.

The caller is responsible to call `gnome_db_custom_layout_data_free()` on the returned structure, without trying to free its internals, or unref the objects pointer inside it.

The returned GnomeDbCustomLayoutData structure holds pointers to the referenced objects, and a check is made for all the pointers which cannot be `NULL` (if an error is found, then the function returns `NULL`, and `error` is set)

`layout` : | a GnomeDbCustomLayout object
`error` : | place to store the error, or `NULL`
Returns : | a new GnomeDbCustomLayoutData structure, to be free'ed by the caller using `gnome_db_custom_layout_data_free()`

### gnome_db_custom_layout_data_free ()

    void        gnome_db_custom_layout_data_free
                                                (GnomeDbCustomLayoutData *data);

Ensures that the `data` allocated through `gnome_db_custom_layout_get_data()` is de-allocated properly.

`data` : | a GnomeDbCustomLayoutData structure

### gnome_db_custom_layout_get_glade_instance ()

    GladeXML*   gnome_db_custom_layout_get_glade_instance
                                                (GnomeDbCustomLayout *layout,
                                                 GtkWidget **root_widget,
                                                 GHashTable **box_widgets,
                                                 GError **error);

Builds a GladeXML object, and if there is no error, creates a new GHashTable and stores it in `box_widgets`, and stores a pointer to the root widget into `root_widget`.

`layout` : | a GnomeDbCustomLayout object
`root_widget` : | a place to store a pointer to the root widget of the GladeXml instance
`box_widgets` : | a place to store the GHashTable for the GtkBox widgets
`error` : | location to store error, or `NULL`
Returns : | a new GladeXML object, or `NULL` if an error occured or no Glade file is to be used in `layout`.

### gnome_db_custom_layout_get_widget ()

    GtkWidget*  gnome_db_custom_layout_get_widget
                                                (GnomeDbCustomLayout *layout,
                                                 GError **error);

Creates a widget from the "specifications" stored within `layout`.

`layout` : | a GnomeDbCustomLayout object
`error` : | location to store error, or `NULL`
Returns : | a new GnomeDbWorkLayout widget, or `NULL` if an error occured.

### gnome_db_custom_layout_get_exec_context ()

    GnomeDbDataSet* gnome_db_custom_layout_get_exec_context
                                                (GnomeDbCustomLayout *layout);

Use this function to retreive a GnomeDbDataSet object containing all the GnomeDbParameter parameters required to be able to 'run' a widget obtained using the `gnome_db_custom_layout_get_widget()` function.

Note: the parameters contained within the returned GnomeDbDataSet won't be used by any widget obtained using the `gnome_db_custom_layout_get_widget()`; accessing those parameters is done using the methods of the GnomeDbDataWidget interface.

`layout` : | a GnomeDbCustomLayout object
Returns : | a new GnomeDbDataSet object

### gnome_db_custom_layout_get_data_context ()

    GnomeDbDataSet* gnome_db_custom_layout_get_data_context
                                                (GnomeDbCustomLayout *layout);

Use this function to retreive a GnomeDbDataSet object containing all the GnomeDbParameter parameters which get updated when a widget obtained using the `gnome_db_custom_layout_get_widget()` is used.

Note: the parameters contained within the returned GnomeDbDataSet won't be used by any widget obtained using the `gnome_db_custom_layout_get_widget()`; accessing those parameters is done using the methods of the GnomeDbDataWidget interface.

`layout` : | a GnomeDbCustomLayout object
Returns : | a new GnomeDbDataSet object