GdauiBasicForm

GdauiBasicForm — Form widget mapping the values contained in a GdaSet

Stability Level

Stable, unless otherwise indicated

Properties

Signals

void activated Run First
void holder-changed Run First
void layout-changed Run First
void populate-popup Run First

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkBox
                    ╰── GdauiBasicForm
                        ╰── GdauiRawForm

Implemented Interfaces

GdauiBasicForm implements AtkImplementorIface, GtkBuildable and GtkOrientable.

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>


Functions

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 .

Parameters

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".

Parameters

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

Parameters

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)

Parameters

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.

Parameters

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

Parameters

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).

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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).

Parameters

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().

Parameters

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


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()).

Parameters

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()).

Parameters

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).

Parameters

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

Types and Values

struct GdauiBasicForm

struct GdauiBasicForm;

enum GdauiBasicFormPart

Members

GDAUI_BASIC_FORM_LABELS

   

GDAUI_BASIC_FORM_ENTRIES

   

Property Details

The “can-expand-v” property

  “can-expand-v”             gboolean

Flags: Read

Default value: FALSE


The “entries-auto-default” property

  “entries-auto-default”     gboolean

Flags: Read / Write

Default value: FALSE


The “headers-sensitive” property

  “headers-sensitive”        gboolean

Deprecated

Flags: Read / Write

Default value: FALSE


The “paramlist” property

  “paramlist”                gpointer

Flags: Read / Write


The “show-actions” property

  “show-actions”             gboolean

Flags: Read / Write

Default value: FALSE


The “xml-layout” property

  “xml-layout”               gpointer

Flags: Write

Signal Details

The “activated” signal

void
user_function (GdauiBasicForm *form,
               gpointer        user_data)

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

Parameters

form

GdauiBasicForm

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “holder-changed” signal

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

Emitted when a GdaHolder changed in form

Parameters

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.

 

Flags: Run First


The “layout-changed” signal

void
user_function (GdauiBasicForm *form,
               gpointer        user_data)

Emitted when the form's layout changes

Parameters

form

GdauiBasicForm

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “populate-popup” signal

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

Connect this signal and modify the popup menu.

Parameters

form

GdauiBasicForm

 

menu

a GtkMenu to modify

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First

Since 4.2.4