GdauiBasicForm

## GdauiBasicForm GdauiBasicForm — Form widget mapping the values contained in a GdaSet |

## Stability Level

Stable, unless otherwise indicated

## 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);

    void                gdaui_basic_form_set_unknown_color  (GdauiBasicForm *form,
                                                             gdouble red,
                                                             gdouble green,
                                                             gdouble blue,
                                                             gdouble alpha);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkWidget
                   +----GtkContainer
                         +----GtkBox
                               +----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.

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

    <?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 `holder` data holder

`form` : | a GdauiBasicForm widget
`holder` : | a GdaHolder object
`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 `holder` grab the focus for the window it's in. If `holder` is `NULL`, then the focus is on the first entry which needs attention.

`form` : | a GdauiBasicForm widget
`holder` : | a GdaHolder object, or `NULL`. [allow-none]

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 `holder` place.

`form` : | a GdauiBasicForm widget
`holder` : | a GdaHolder object
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 `holder` holder.

`form` : | a GdauiBasicForm widget
`holder` : | a GdaHolder object
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_LABELS` |
`GDAUI_BASIC_FORM_ENTRIES` |

### 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

### gdaui_basic_form_set_unknown_color ()

    void                gdaui_basic_form_set_unknown_color  (GdauiBasicForm *form,
                                                             gdouble red,
                                                             gdouble green,
                                                             gdouble blue,
                                                             gdouble alpha);

Defines the color to be used when `form` displays an invalid value. Any value not between 0. and 1. will result in the default hard coded values to be used (grayish).

`form` : | a GdauiBasicForm widget
`red` : | the red component of a color
`green` : | the green component of a color
`blue` : | the blue component of a color
`alpha` : | the alpha component of a color

Since 5.0.3

## 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

Deprecated

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