GdauiBasicForm

GdauiBasicForm — Form widget mapping the values contained in a GdaSet

Synopsis

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

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBox
                                 +----GtkVBox
                                       +----GdauiBasicForm
                                             +----GdauiRawForm

Implemented Interfaces

GdauiBasicForm implements GtkBuildable, GtkOrientable and AtkImplementorIface.

Properties

  "can-expand"               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

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

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

GdauiBasicForm

typedef struct _GdauiBasicForm GdauiBasicForm;


gdaui_basic_form_new ()

GtkWidget *         gdaui_basic_form_new                (GdaSet *data_set);

Creates a new GdauiBasicForm widget using all the parameters provided in paramlist.

The global layout is rendered using a table (a GtkTable), and an entry is created for each node of paramlist.

data_set :

Returns :

the new widget

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 :

parent :

the parent window for the new dialog, or NULL

title :

the title of the dialog window, or NULL

header :

a helper text displayed at the top of the dialog, or NULL

Returns :

the new GtkDialog widget

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

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

holder :

show :

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

form :

a GdauiBasicForm widget

holder :

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 param parameter editable or not. If param is NULL, then all the parameters are concerned.

form :

a GdauiBasicForm widget

holder :

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

holder :

Returns :

the requested widget, or NULL if not found

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

holder :

Returns :

the requested widget, or NULL if not found

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

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

Since 4.2

Property Details

The "can-expand" property

  "can-expand"               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 changes

form :

GdauiBasicForm

param :

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.