## MgForm

MgForm — Simple form layout for the user to fill MgParameter objects

## Synopsis

    struct      MgForm;
    guint       mg_form_get_type                (void);
    GtkWidget*  mg_form_new                     (MgConf *conf,
                                                 MgContext *context);
    GtkWidget*  mg_form_new_in_layout           (MgConf *conf,
                                                 MgContext *context,
                                                 GtkWidget *layout,
                                                 GHashTable *box_widgets);
    GtkWidget*  mg_form_new_in_dialog           (MgConf *conf,
                                                 MgContext *context,
                                                 GtkWindow *parent,
                                                 const gchar *title,
                                                 const gchar *header);
    gboolean    mg_form_is_valid                (MgForm *form);
    gboolean    mg_form_has_been_changed        (MgForm *form);
    void        mg_form_set_current_as_orig     (MgForm *form);
    void        mg_form_reset                   (MgForm *form);
    void        mg_form_show_entries_actions    (MgForm *form,
                                                 gboolean show_actions);
    void        mg_form_entry_show              (MgForm *form,
                                                 MgParameter *param,
                                                 gboolean show);
    void        mg_form_entry_set_sensitive     (MgForm *form,
                                                 MgParameter *param,
                                                 gboolean sensitive);
    void        mg_form_set_entries_auto_default
                                                (MgForm *form,
                                                 gboolean auto_default);
    void        mg_form_set_entries_default     (MgForm *form);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBox
                               +----GtkVBox
                                     +----MgForm

## Implemented Interfaces

MgForm implements AtkImplementorIface.

## Signal Prototypes

    "param-changed"
                void        user_function      (MgForm *mgform,
                                                GObject *arg1,
                                                gboolean arg2,
                                                gpointer user_data);

## Description

## Details

### struct MgForm

    struct MgForm;

### mg_form_get_type ()

    guint       mg_form_get_type                (void);

Returns : |

### mg_form_new ()

    GtkWidget*  mg_form_new                     (MgConf *conf,
                                                 MgContext *context);

Creates a new MgForm widget using all the parameters provided in `context`. `context` is copied in the process.

The global layout is rendered using a table (a GtkTable), and an entry is created for each node of `context`.

`conf` : | a MgConf object
`context` : | a MgContext structure
Returns : | the new widget

### mg_form_new_in_layout ()

    GtkWidget*  mg_form_new_in_layout           (MgConf *conf,
                                                 MgContext *context,
                                                 GtkWidget *layout,
                                                 GHashTable *box_widgets);

Creates a new MgForm widget using all the parameters provided in `context`. `context` is copied in the process.

This function is identical to `mg_form_new()` except that the layout is not done using a table, but using the `layout` widget; and each entry is packed into one of the GtkBox widgets of `box_widgets` (specifically each entry corresponds to a MgContextNode of `context`, and that context node is used a the key to `box_widgets` to find the box to pack the entry in).

If any of `layout` or `box_widgets` is `NULL`, then this function is equivalent to `mg_form_new()`.

`conf` : | a MgConf object
`context` : | a MgContext structure
`layout` : | a GtkWidget container of all the widgets in `box_widgets`
`box_widgets` : | a GHashTable of GtkBox widgets
Returns : | the new widget

### mg_form_new_in_dialog ()

    GtkWidget*  mg_form_new_in_dialog           (MgConf *conf,
                                                 MgContext *context,
                                                 GtkWindow *parent,
                                                 const gchar *title,
                                                 const gchar *header);

Creates a new MgForm widget in the same way as `mg_form_new()` and puts it into a GtkDialog widget.

The MgForm widget is attached to the dialog using the user property "form".

`conf` : | a MgConf object
`context` : | a MgContext structure
`parent` : | the parent window for the new dialog, or `NULL`
`title` : | the title of the dialog window, or `NULL`
`header` : | a helper text displayed at the top of the dialog, or `NULL`
Returns : | the new GtkDialog widget

### mg_form_is_valid ()

    gboolean    mg_form_is_valid                (MgForm *form);

Tells if the form can be used as-is (if all the parameters do have some valid values)

`form` : | a MgForm widget
Returns : | TRUE if the form is valid

### mg_form_has_been_changed ()

    gboolean    mg_form_has_been_changed        (MgForm *form);

Tells if the form has had at least on entry changed, or not

`form` : | a MgForm widget
Returns : |

### mg_form_set_current_as_orig ()

    void        mg_form_set_current_as_orig     (MgForm *form);

Tells `form` that the current values in the different entries are to be considered as the original values for all the entries; the immediate consequence is that any sub-sequent call to `mg_form_has_been_changed()` will return FALSE (of course until any entry is changed).

`form` : | a MgForm widget

### mg_form_reset ()

    void        mg_form_reset                   (MgForm *form);

Resets all the entries in the form to their original values

`form` : | a MgForm widget

### mg_form_show_entries_actions ()

    void        mg_form_show_entries_actions    (MgForm *form,
                                                 gboolean show_actions);

Show or hide the actions button available at the end of each data entry in the form

`form` : | a MgForm widget
`show_actions` : | a boolean

### mg_form_entry_show ()

    void        mg_form_entry_show              (MgForm *form,
                                                 MgParameter *param,
                                                 gboolean show);

Shows or hides the MgDataEntry in `form` which corresponds to the `param` parameter

`form` : | a MgForm widget
`param` : | a MgParameter object
`show` : |

### mg_form_entry_set_sensitive ()

    void        mg_form_entry_set_sensitive     (MgForm *form,
                                                 MgParameter *param,
                                                 gboolean sensitive);

Shows or hides the MgDataEntry in `form` which corresponds to the `param` parameter

`form` : | a MgForm widget
`param` : | a MgParameter object
`sensitive` : |

### mg_form_set_entries_auto_default ()

    void        mg_form_set_entries_auto_default
                                                (MgForm *form,
                                                 gboolean auto_default);

Sets weather all the MgDataEntry entries in the form must default to a default value if they are assigned a non valid value. Depending on the real type of entry, it will provide a default value which the user does not need to modify if it is OK.

For example a date entry can by default display the current date.

`form` : | a MgForm widget
`auto_default` : |

### mg_form_set_entries_default ()

    void        mg_form_set_entries_default     (MgForm *form);

For each entry in the form, sets it to a default value if it is possible to do so.

`form` : | a MgForm widget

## Signals

### The "param-changed" signal

    void        user_function                  (MgForm *mgform,
                                                GObject *arg1,
                                                gboolean arg2,
                                                gpointer user_data);

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