![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
GdauiBasicFormGdauiBasicForm — Form widget mapping the values contained in a GdaSet |
![]() |
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
);
GObject +----GInitiallyUnowned +----GtkObject +----GtkWidget +----GtkContainer +----GtkBox +----GtkVBox +----GdauiBasicForm +----GdauiRawForm
GdauiBasicForm implements AtkImplementorIface, GtkBuildable and GtkOrientable.
"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
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, ¶ms, 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>
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
.
|
a GdaSet structure |
Returns : |
the new widget. [transfer full] |
Since 4.2
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".
|
a GdaSet object |
|
the parent window for the new dialog, or NULL . [allow-none]
|
|
the title of the dialog window, or NULL . [allow-none]
|
|
a helper text displayed at the top of the dialog, or NULL . [allow-none]
|
Returns : |
the new GtkDialog widget. [transfer full] |
Since 4.2
GdaSet * gdaui_basic_form_get_data_set (GdauiBasicForm *form
);
Get a pointer to the GdaSet object which
is modified by form
|
a GdauiBasicForm widget |
Returns : |
a pointer to the GdaSet. [transfer none] |
Since 4.2
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)
|
a GdauiBasicForm widget |
Returns : |
TRUE if the form is valid
|
Since 4.2
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.
|
a GdauiBasicForm widget |
Returns : |
TRUE if one entry has changed at least
|
Since 4.2
void gdaui_basic_form_reset (GdauiBasicForm *form
);
Resets all the entries in the form to their original values
|
a GdauiBasicForm widget |
Since 4.2
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).
|
a GdauiBasicForm widget |
Since 4.2
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
|
a GdauiBasicForm widget |
|
|
|
set to TRUE to show the data entry, and to FALSE to hide it
|
Since 4.2
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
|
a GdauiBasicForm widget |
|
Since 4.2
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.
|
a GdauiBasicForm widget |
|
a GdaHolder object; or NULL . [allow-none]
|
|
TRUE if corresponding data entry must be editable
|
Since 4.2
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.
|
a GdauiBasicForm widget |
Since 4.2
GtkWidget * gdaui_basic_form_get_entry_widget (GdauiBasicForm *form
,GdaHolder *holder
);
Get the GdauiDataEntry in form
which corresponds to the param parameter.
|
a GdauiBasicForm widget |
|
|
Returns : |
the requested widget, or NULL if not found. [transfer none]
|
Since 4.2
GtkWidget * gdaui_basic_form_get_label_widget (GdauiBasicForm *form
,GdaHolder *holder
);
Get the label in form
which corresponds to the param parameter.
|
a GdauiBasicForm widget |
|
|
Returns : |
the requested widget, or NULL if not found. [transfer none]
|
Since 4.2
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).
|
a GdauiBasicForm |
|
XML file name to use |
|
the name of the form to use, in file_name
|
Since 4.2
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()
.
|
a GdauiBasicForm |
|
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
typedef enum { GDAUI_BASIC_FORM_LABELS, GDAUI_BASIC_FORM_ENTRIES } GdauiBasicFormPart;
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()
).
|
a GdauiBasicForm |
|
a GtkSizeGroup object |
|
specifies which widgets in form are concerned
|
Since 4.2
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()
).
|
a GdauiBasicForm |
|
a GtkSizeGroup object |
|
specifies which widgets in form are concerned
|
Since 4.2
"entries-auto-default"
property"entries-auto-default" gboolean : Read / Write
Default value: FALSE
"activated"
signalvoid user_function (GdauiBasicForm *form, gpointer user_data) : Run First
Emitted when the use has activated any of the GdaDataEntry widget
in form
.
|
GdauiBasicForm |
|
user data set when the signal handler was connected. |
"holder-changed"
signalvoid user_function (GdauiBasicForm *form, GdaHolder *param, gboolean is_user_modif, gpointer user_data) : Run First
Emitted when a GdaHolder changes
|
GdauiBasicForm |
|
that changed |
|
TRUE if the modification has been initiated by a user modification |
|
user data set when the signal handler was connected. |
"layout-changed"
signalvoid user_function (GdauiBasicForm *form, gpointer user_data) : Run First
Emitted when the form's layout changes
|
GdauiBasicForm |
|
user data set when the signal handler was connected. |