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

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

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. If param is NULL, then the focus is on the first entry which needs attention.

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


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 4.2.13

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