![]() |
![]() |
![]() |
GNOME Data Access 4 manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Implemented Interfaces | Properties | Signals |
GdauiBasicFormGdauiBasicForm — Form widget mapping the values contained in a GdaSet |
![]() |
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
);
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
"activated" :Run First
"holder-changed" :Run First
"layout-changed" :Run First
"populate-popup" :Run First
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
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> |
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. If param
is NULL
,
then the focus is on the first entry which needs attention.
|
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
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).
|
a GdauiBasicForm widget |
|
the red component of a color |
|
the green component of a color |
|
the blue component of a color |
|
the alpha component of a color |
Since 4.2.13
"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 changed in form
|
GdauiBasicForm |
|
the GdaHolder 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. |
"populate-popup"
signalvoid user_function (GdauiBasicForm *form,
GtkMenu *menu,
gpointer user_data) : Run First
Connect this signal and modify the popup menu.
|
GdauiBasicForm |
|
a GtkMenu to modify |
|
user data set when the signal handler was connected. |
Since 4.2.4