## GdauiBasicForm

GdauiBasicForm — Form widget mapping the values contained in a GdaSet

## Synopsis

    struct              GdauiBasicForm;
    GtkWidget *         gdaui_basic_form_new                (GdaSet *data_set);
    GtkWidget *         gdaui_basic_form_new_in_dialog      (GdaSet *data_set,
                                                             GtkWindow *parent,
                                                             const gchar *title,
                                                             const gchar *header);
    GdaSet *            gdaui_basic_form_get_data_set       (GdauiBasicForm *form);
    gboolean            gdaui_basic_form_is_valid           (GdauiBasicForm *form);
    gboolean            gdaui_basic_form_has_changed        (GdauiBasicForm *form);
    void                gdaui_basic_form_reset              (GdauiBasicForm *form);
    void                gdaui_basic_form_set_as_reference   (GdauiBasicForm *form);
    void                gdaui_basic_form_entry_set_visible  (GdauiBasicForm *form,
                                                             GdaHolder *holder,
                                                             gboolean show);
    void                gdaui_basic_form_entry_grab_focus   (GdauiBasicForm *form,
                                                             GdaHolder *holder);
    void                gdaui_basic_form_entry_set_editable (GdauiBasicForm *form,
                                                             GdaHolder *holder,
                                                             gboolean editable);
    void                gdaui_basic_form_set_entries_to_default
                                                            (GdauiBasicForm *form);
    GtkWidget *         gdaui_basic_form_get_entry_widget   (GdauiBasicForm *form,
                                                             GdaHolder *holder);
    GtkWidget *         gdaui_basic_form_get_label_widget   (GdauiBasicForm *form,
                                                             GdaHolder *holder);

    void                gdaui_basic_form_set_layout_from_file
                                                            (GdauiBasicForm *form,
                                                             const gchar *file_name,
                                                             const gchar *form_name);
    GtkWidget *         gdaui_basic_form_get_place_holder   (GdauiBasicForm *form,
                                                             const gchar *placeholder_id);

    enum                GdauiBasicFormPart;
    void                gdaui_basic_form_add_to_size_group  (GdauiBasicForm *form,
                                                             GtkSizeGroup *size_group,
                                                             GdauiBasicFormPart part);
    void                gdaui_basic_form_remove_from_size_group
                                                            (GdauiBasicForm *form,
                                                             GtkSizeGroup *size_group,
                                                             GdauiBasicFormPart part);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkWidget
                         +----GtkContainer
                               +----GtkBox
                                     +----GtkVBox
                                           +----GdauiBasicForm
                                                 +----GdauiRawForm

## Implemented Interfaces

GdauiBasicForm implements AtkImplementorIface, GtkBuildable and GtkOrientable.

## Properties

      "can-expand-v"             gboolean              : Read
      "entries-auto-default"     gboolean              : Read / Write
      "headers-sensitive"        gboolean              : Read / Write
      "paramlist"                gpointer              : Read / Write
      "show-actions"             gboolean              : Read / Write
      "xml-layout"               gpointer              : Write

## Signals

      "activated"                                      : Run First
      "holder-changed"                                 : Run First
      "layout-changed"                                 : Run First
      "populate-popup"                                 : Run First

## Description

The GdauiBasicForm widget is a form containing an entry for each GdaHolder object contained in a GdaSet (specified when the form is created). A typical usage is when the user is requested to enter a value which will be used in a statement (without any error checking for clarity):

    GdaStatement *stmt;
    GdaSet *params;
    stmt = gda_sql_parser_parse_string (parser, "SELECT * FROM customers where name LIKE #name::string", NULL, NULL);
    gda_statement_get_parameters (stmt, &params, NULL);
    GtkWidget *form;
    gint result;
    form = gdaui_basic_form_new_in_dialog (params, NULL, "Customer search", "Enter Customer search expression");
    result = gtk_dialog_run (GTK_DIALOG (form));
    gtk_widget_destroy (form);
    if (result == GTK_RESPONSE_ACCEPT) {
        /* execute statement */
        GdaDataModel *model;
        model = gda_connection_statement_execute_select (cnc, stmt, params, NULL);
        [...]
    }
    g_object_unref (params);
    g_object_unref (stmt);

The default layout within a GdauiBasicForm is a vertical column: all the data entry widgets are aligned in a single column. This behaviour can be changed using the `gdaui_basic_form_set_layout_from_file()` method or setting the xml-layout property.

### XML Layout Definitions

The GdauiBasicForm class parses textual descriptions of XML layout which which can be described by the following DTD.

    <!ELEMENT gdaui_layouts (gdaui_form | gdaui_grid)>
    <!ELEMENT gdaui_form (gdaui_section | gdaui_column | gdaui_notebook)*>
    <!ATTLIST gdaui_form
              name CDATA #REQUIRED
    	  container (columns|rows|hpaned|vpaned) #IMPLIED>
    <!ELEMENT gdaui_section (gdaui_section | gdaui_column | gdaui_notebook)*>
    <!ATTLIST gdaui_section
              title CDATA #IMPLIED >
    <!ELEMENT gdaui_notebook (gdaui_section | gdaui_column | gdaui_notebook)*>
    <!ELEMENT gdaui_column (gdaui_entry | gdaui_placeholder)*>
    <!ELEMENT gdaui_entry EMPTY>
    <!ATTLIST gdaui_entry
              name CDATA #REQUIRED
    	  editable (true|false) #IMPLIED
    	  label CDATA #IMPLIED
    	  plugin CDATA #IMPLIED>
    <!ELEMENT gdaui_placeholder EMPTY>
    <!ATTLIST gdaui_placeholder
    	  id CDATA #REQUIRED
    	  label CDATA #IMPLIED>

Example 1. A GdauiBasicForm layout example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18

    <?xml version="1.0" encoding="UTF-8"?>
    <gdaui_layouts>
      <gdaui_form name="customers" container="hpaned">
        <gdaui_section title="Summary">
          <gdaui_column>
        <gdaui_entry name="id" editable="no"/>
        <gdaui_entry name="name"/>
        <gdaui_entry name="comments" plugin="text"/>
        <gdaui_entry name="total_orders" label="Total ordered" plugin="number:NB_DECIMALS=2;CURRENCY=€"/>
          </gdaui_column>
        </gdaui_section>
        <gdaui_section title="Photo">
          <gdaui_column>
        <gdaui_entry name="photo" plugin="picture"/>
          </gdaui_column>
        </gdaui_section>
      </gdaui_form>
    </gdaui_layouts>

## Details

### struct GdauiBasicForm

    struct GdauiBasicForm;

### gdaui_basic_form_new ()

    GtkWidget *         gdaui_basic_form_new                (GdaSet *data_set);

Creates a new GdauiBasicForm widget using all the GdaHolder objects provided in `data_set`.

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

`data_set` : | a GdaSet structure
Returns : | the new widget. [transfer full]

Since 4.2

### gdaui_basic_form_new_in_dialog ()

    GtkWidget *         gdaui_basic_form_new_in_dialog      (GdaSet *data_set,
                                                             GtkWindow *parent,
                                                             const gchar *title,
                                                             const gchar *header);

Creates a new GdauiBasicForm widget in the same way as `gdaui_basic_form_new()` and puts it into a GtkDialog widget. The returned dialog has the "Ok" and "Cancel" buttons which respectively return GTK_RESPONSE_ACCEPT and GTK_RESPONSE_REJECT.

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

`data_set` : | a GdaSet object
`parent` : | the parent window for the new dialog, or `NULL`. [allow-none]
`title` : | the title of the dialog window, or `NULL`. [allow-none]
`header` : | a helper text displayed at the top of the dialog, or `NULL`. [allow-none]
Returns : | the new GtkDialog widget. [transfer full]

Since 4.2

### gdaui_basic_form_get_data_set ()

    GdaSet *            gdaui_basic_form_get_data_set       (GdauiBasicForm *form);

Get a pointer to the GdaSet object which is modified by `form`

`form` : | a GdauiBasicForm widget
Returns : | a pointer to the GdaSet. [transfer none]

Since 4.2

### gdaui_basic_form_is_valid ()

    gboolean            gdaui_basic_form_is_valid           (GdauiBasicForm *form);

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

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

Since 4.2

### gdaui_basic_form_has_changed ()

    gboolean            gdaui_basic_form_has_changed        (GdauiBasicForm *form);

Tells if the form has had at least on entry changed since `form` was created or `gdaui_basic_form_set_as_reference()` has been called.

`form` : | a GdauiBasicForm widget
Returns : | `TRUE` if one entry has changed at least

Since 4.2

### gdaui_basic_form_reset ()

    void                gdaui_basic_form_reset              (GdauiBasicForm *form);

Resets all the entries in the form to their original values

`form` : | a GdauiBasicForm widget

Since 4.2

### gdaui_basic_form_set_as_reference ()

    void                gdaui_basic_form_set_as_reference   (GdauiBasicForm *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 `gdaui_basic_form_has_changed()` will return `FALSE` (of course until any entry is changed).

`form` : | a GdauiBasicForm widget

Since 4.2

### gdaui_basic_form_entry_set_visible ()

    void                gdaui_basic_form_entry_set_visible  (GdauiBasicForm *form,
                                                             GdaHolder *holder,
                                                             gboolean show);

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

`form` : | a GdauiBasicForm widget
`show` : | set to `TRUE` to show the data entry, and to `FALSE` to hide it

Since 4.2

### gdaui_basic_form_entry_grab_focus ()

    void                gdaui_basic_form_entry_grab_focus   (GdauiBasicForm *form,
                                                             GdaHolder *holder);

Makes the data entry corresponding to `param` grab the focus for the window it's in

`form` : | a GdauiBasicForm widget

Since 4.2

### gdaui_basic_form_entry_set_editable ()

    void                gdaui_basic_form_entry_set_editable (GdauiBasicForm *form,
                                                             GdaHolder *holder,
                                                             gboolean editable);

Sets the GdauiDataEntry in `form` which corresponds to the `holder` parameter editable or not. If `holder` is `NULL`, then all the parameters are concerned.

`form` : | a GdauiBasicForm widget
`holder` : | a GdaHolder object; or `NULL`. [allow-none]
`editable` : | `TRUE` if corresponding data entry must be editable

Since 4.2

### gdaui_basic_form_set_entries_to_default ()

    void                gdaui_basic_form_set_entries_to_default
                                                            (GdauiBasicForm *form);

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

`form` : | a GdauiBasicForm widget

Since 4.2

### gdaui_basic_form_get_entry_widget ()

    GtkWidget *         gdaui_basic_form_get_entry_widget   (GdauiBasicForm *form,
                                                             GdaHolder *holder);

Get the GdauiDataEntry in `form` which corresponds to the param parameter.

`form` : | a GdauiBasicForm widget
Returns : | the requested widget, or `NULL` if not found. [transfer none]

Since 4.2

### gdaui_basic_form_get_label_widget ()

    GtkWidget *         gdaui_basic_form_get_label_widget   (GdauiBasicForm *form,
                                                             GdaHolder *holder);

Get the label in `form` which corresponds to the param parameter.

`form` : | a GdauiBasicForm widget
Returns : | the requested widget, or `NULL` if not found. [transfer none]

Since 4.2

### gdaui_basic_form_set_layout_from_file ()

    void                gdaui_basic_form_set_layout_from_file
                                                            (GdauiBasicForm *form,
                                                             const gchar *file_name,
                                                             const gchar *form_name);

Sets a form layout according an XML description contained in `file_name`, for the form identified by the `form_name` name (as an XML layout file can contain the descriptions of several forms and grids).

`form` : | a GdauiBasicForm
`file_name` : | XML file name to use
`form_name` : | the name of the form to use, in `file_name`

Since 4.2

### gdaui_basic_form_get_place_holder ()

    GtkWidget *         gdaui_basic_form_get_place_holder   (GdauiBasicForm *form,
                                                             const gchar *placeholder_id);

Retreives a pointer to a place holder widget. This feature is only available if a specific layout has been defined for `form` using `gdaui_basic_form_set_layout_from_file()`.

`form` : | a GdauiBasicForm
`placeholder_id` : | the name of the requested place holder
Returns : | a pointer to the requested place holder, or `NULL` if not found. [transfer none]

Since 4.2

### enum GdauiBasicFormPart

    typedef enum {
    	GDAUI_BASIC_FORM_LABELS,
    	GDAUI_BASIC_FORM_ENTRIES
    } GdauiBasicFormPart;

### gdaui_basic_form_add_to_size_group ()

    void                gdaui_basic_form_add_to_size_group  (GdauiBasicForm *form,
                                                             GtkSizeGroup *size_group,
                                                             GdauiBasicFormPart part);

Add `form`'s widgets specified by `part` to `size_group` (the widgets can then be removed using `gdaui_basic_form_remove_from_size_group()`).

`form` : | a GdauiBasicForm
`size_group` : | a GtkSizeGroup object
`part` : | specifies which widgets in `form` are concerned

Since 4.2

### gdaui_basic_form_remove_from_size_group ()

    void                gdaui_basic_form_remove_from_size_group
                                                            (GdauiBasicForm *form,
                                                             GtkSizeGroup *size_group,
                                                             GdauiBasicFormPart part);

Removes `form`'s widgets specified by `part` from `size_group` (the widgets must have been added using `gdaui_basic_form_add_to_size_group()`).

`form` : | a GdauiBasicForm
`size_group` : | a GtkSizeGroup object
`part` : | specifies which widgets in `form` are concerned

Since 4.2

## Property Details

### The `"can-expand-v"` property

      "can-expand-v"             gboolean              : Read

Default value: FALSE

### The `"entries-auto-default"` property

      "entries-auto-default"     gboolean              : Read / Write

Default value: FALSE

### The `"headers-sensitive"` property

      "headers-sensitive"        gboolean              : Read / Write

Default value: FALSE

### The `"paramlist"` property

      "paramlist"                gpointer              : Read / Write

### The `"show-actions"` property

      "show-actions"             gboolean              : Read / Write

Default value: FALSE

### The `"xml-layout"` property

      "xml-layout"               gpointer              : Write

## Signal Details

### The `"activated"` signal

    void                user_function                      (GdauiBasicForm *form,
                                                            gpointer        user_data)      : Run First

Emitted when the use has activated any of the GdaDataEntry widget in `form`.

`form` : | GdauiBasicForm
`user_data` : | user data set when the signal handler was connected.

### The `"holder-changed"` signal

    void                user_function                      (GdauiBasicForm *form,
                                                            GdaHolder      *param,
                                                            gboolean        is_user_modif,
                                                            gpointer        user_data)          : Run First

Emitted when a GdaHolder changed in `form`

`form` : | GdauiBasicForm
`param` : | the GdaHolder that changed
`is_user_modif` : | TRUE if the modification has been initiated by a user modification
`user_data` : | user data set when the signal handler was connected.

### The `"layout-changed"` signal

    void                user_function                      (GdauiBasicForm *form,
                                                            gpointer        user_data)      : Run First

Emitted when the form's layout changes

`form` : | GdauiBasicForm
`user_data` : | user data set when the signal handler was connected.

### The `"populate-popup"` signal

    void                user_function                      (GdauiBasicForm *form,
                                                            GtkMenu        *menu,
                                                            gpointer        user_data)      : Run First

Connect this signal and modify the popup menu.

`form` : | GdauiBasicForm
`menu` : | a GtkMenu to modify
`user_data` : | user data set when the signal handler was connected.

Since 4.2.4