## MgCustomLayout

MgCustomLayout — Object to store the model part of custom layouts

## Synopsis

    enum        MgCustomLayoutType;
    guint       mg_custom_layout_get_type       (void);
    GObject*    mg_custom_layout_new            (MgConf *conf);
    MgCustomLayoutType mg_custom_layout_get_layout_type
                                                (MgCustomLayout *layout);
    MgCustomLayoutData* mg_custom_layout_get_data
                                                (MgCustomLayout *layout,
                                                 GError **error);
    void        mg_custom_layout_data_free      (MgCustomLayoutData *data);
    GladeXML*   mg_custom_layout_get_glade_instance
                                                (MgCustomLayout *layout,
                                                 GtkWidget **root_widget,
                                                 GHashTable **box_widgets,
                                                 GError **error);
    GtkWidget*  mg_custom_layout_get_widget     (MgCustomLayout *layout,
                                                 GError **error);
    MgContext*  mg_custom_layout_get_exec_context
                                                (MgCustomLayout *layout);
    MgContext*  mg_custom_layout_get_data_context
                                                (MgCustomLayout *layout);

## Description

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

## Details

### enum MgCustomLayoutType

    typedef enum {
    	MG_CUSTOM_LAYOUT_LAYOUT,
    	MG_CUSTOM_LAYOUT_GRID,
    	MG_CUSTOM_LAYOUT_FORM,
    	MG_CUSTOM_LAYOUT_MATRIX
    } MgCustomLayoutType;

`MG_CUSTOM_LAYOUT_LAYOUT` | The layout is made of other sub-layouts
`MG_CUSTOM_LAYOUT_GRID` | The layout specifies a MgWorkGrid widget
`MG_CUSTOM_LAYOUT_FORM` | The layout specifies a MgWorkForm widget
`MG_CUSTOM_LAYOUT_MATRIX` | The layout specifies a MgWorkMatrix widget

### mg_custom_layout_get_type ()

    guint       mg_custom_layout_get_type       (void);

Returns : |

### mg_custom_layout_new ()

    GObject*    mg_custom_layout_new            (MgConf *conf);

Creates a new MgCustomLayout object

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

### mg_custom_layout_get_layout_type ()

    MgCustomLayoutType mg_custom_layout_get_layout_type
                                                (MgCustomLayout *layout);

Get the kind of custom layout `layout` is.

`layout` : | a MgCustomLayout object
Returns : |

### mg_custom_layout_get_data ()

    MgCustomLayoutData* mg_custom_layout_get_data
                                                (MgCustomLayout *layout,
                                                 GError **error);

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

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

The returned MgCustomLayoutData 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 MgCustomLayout object
`error` : | place to store the error, or `NULL`
Returns : | a new MgCustomLayoutData structure, to be free'ed by the caller using `mg_custom_layout_data_free()`

### mg_custom_layout_data_free ()

    void        mg_custom_layout_data_free      (MgCustomLayoutData *data);

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

`data` : | a MgCustomLayoutData structure

### mg_custom_layout_get_glade_instance ()

    GladeXML*   mg_custom_layout_get_glade_instance
                                                (MgCustomLayout *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 MgCustomLayout 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`.

### mg_custom_layout_get_widget ()

    GtkWidget*  mg_custom_layout_get_widget     (MgCustomLayout *layout,
                                                 GError **error);

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

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

### mg_custom_layout_get_exec_context ()

    MgContext*  mg_custom_layout_get_exec_context
                                                (MgCustomLayout *layout);

Use this function to retreive a MgContext object containing all the MgParameter parameters required to be able to 'run' a widget obtained using the `mg_custom_layout_get_widget()` function.

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

`layout` : | a MgCustomLayout object
Returns : | a new MgContext object

### mg_custom_layout_get_data_context ()

    MgContext*  mg_custom_layout_get_data_context
                                                (MgCustomLayout *layout);

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

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

`layout` : | a MgCustomLayout object
Returns : | a new MgContext object