# Gnome::GdaUI::BasicForm Class Reference

BasicForm - Form widget mapping the values contained in a Gnome::Gda::Set. More...

Inherits Gtk::VBox.

Inherited by Gnome::GdaUI::RawForm.

Collaboration diagram for Gnome::GdaUI::BasicForm:
[legend]

List of all members.

## Public Member Functions

virtual | ~BasicForm ()
GdauiBasicForm* | gobj ()
| Provides access to the underlying C GtkObject.
const GdauiBasicForm* | gobj () const
| Provides access to the underlying C GtkObject.
| BasicForm (const Glib::RefPtr< Gnome::Gda::Set >& data_set)
| Creates a new Gdaui::BasicForm widget using all the Gda::Holder objects provided in data_set.
| BasicForm (const Glib::RefPtr< Gnome::Gda::Set >& data_set, Gtk::Window* parent, const Glib::ustring& title, const Glib::ustring& header)
| Creates a new Gdaui::BasicForm widget in the same way as new() and puts it into a Gtk::Dialog widget.
Glib::RefPtr< Gnome::Gda::Set > | get_data_set ()
| Get a pointer to the Gda::Set object which is modified by form.
Glib::RefPtr< const Gnome::Gda::Set > | get_data_set () const
| Get a pointer to the Gda::Set object which is modified by form.
bool | is_valid () const
| Tells if the form can be used as-is (if all the parameters do have some valid values).
bool | has_changed () const
| Tells if the form has had at least on entry changed since form was created or set_as_reference() has been called.
void | reset ()
| Resets all the entries in the form to their original values.
void | set_as_reference ()
| 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 has_changed() will return `false` (of course until any entry is changed).
void | entry_set_visible (const Glib::RefPtr< Gnome::Gda::Holder >& holder, bool show)
| Shows or hides the Gdaui::DataEntry in form which corresponds to the.
void | entry_grab_focus (const Glib::RefPtr< Gnome::Gda::Holder >& holder)
| Makes the data entry corresponding to.
void | entry_set_editable (const Glib::RefPtr< Gnome::Gda::Holder >& holder, bool editable)
| Sets the Gdaui::DataEntry in form which corresponds to the.
void | set_entries_to_default ()
| For each entry in the form, sets it to a default value if it is possible to do so.
Gtk::Widget* | get_entry_widget (const Glib::RefPtr< Gnome::Gda::Holder >& holder)
| Get the Gdaui::DataEntry in form which corresponds to the param parameter.
const Gtk::Widget* | get_entry_widget (const Glib::RefPtr< Gnome::Gda::Holder >& holder) const
| Get the Gdaui::DataEntry in form which corresponds to the param parameter.
Gtk::Widget* | get_label_widget (const Glib::RefPtr< Gnome::Gda::Holder >& holder)
| Get the label in form which corresponds to the param parameter.
const Gtk::Widget* | get_label_widget (const Glib::RefPtr< Gnome::Gda::Holder >& holder) const
| Get the label in form which corresponds to the param parameter.
void | set_layout_from_file (const std::string& file_name, const Glib::ustring& 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).
Gtk::Widget* | get_place_holder (const Glib::ustring& placeholder_id)
| Retreives a pointer to a place holder widget.
const Gtk::Widget* | get_place_holder (const Glib::ustring& placeholder_id) const
| Retreives a pointer to a place holder widget.
Glib::SignalProxy0< void > | signal_activated ()
Glib::SignalProxy2< void, const Glib::RefPtr < Gnome::Gda::Holder >&, bool > | signal_holder_changed ()
Glib::SignalProxy0< void > | signal_layout_changed ()
Glib::PropertyProxy_ReadOnly < bool > | property_can_expand () const
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::PropertyProxy< bool > | property_entries_auto_default ()
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::PropertyProxy_ReadOnly < bool > | property_entries_auto_default () const
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::PropertyProxy< bool > | property_headers_sensitive ()
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::PropertyProxy_ReadOnly < bool > | property_headers_sensitive () const
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::PropertyProxy< bool > | property_show_actions ()
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.
Glib::PropertyProxy_ReadOnly < bool > | property_show_actions () const
| You rarely need to use properties because there are get_ and set_ methods for almost all of them.

## Protected Member Functions

virtual void | on_activated ()
virtual void | on_holder_changed (const Glib::RefPtr< Gnome::Gda::Holder >& holder, bool is_user_modified)
virtual void | on_layout_changed ()

## Related Functions

(Note that these are not member functions.)
Gnome::GdaUI::BasicForm* | wrap (GdauiBasicForm* object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

BasicForm - Form widget mapping the values contained in a Gnome::Gda::Set.

The BasicForm widget is a form containing an entry for each Gnome::Gda::Holder object contained in a Gnome::Gda::Set (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):

- TODO: Translate and include example from C API docs.

The default layout within a BasicForm is a vertical column: all the data entry widgets are aligned in a single column. This behaviour can be changed using the set_layout_from_file() method or setting the xml-layout property.

### XML Layout Definitions

The BasicForm 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 BasicForm 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>

## Constructor & Destructor Documentation

virtual Gnome::GdaUI::BasicForm::~BasicForm | ( |  | ) | `[virtual]`

Gnome::GdaUI::BasicForm::BasicForm | ( | const Glib::RefPtr< Gnome::Gda::Set > & | data_set | ) | `[explicit]`

Creates a new Gdaui::BasicForm widget using all the Gda::Holder objects provided in data_set.

The global layout is rendered using a table (a Gtk::Table), and an entry is created for each node of data_set.

Parameters:

  | data_set | A Gda::Set structure.

Returns:
  The new widget

Since libgda-uimm 4.2:

Gnome::GdaUI::BasicForm::BasicForm | ( | const Glib::RefPtr< Gnome::Gda::Set > & | data_set,
|  | Gtk::Window * | parent,
|  | const Glib::ustring & | title,
|  | const Glib::ustring & | header |
| ) |  |  | `[explicit]`

Creates a new Gdaui::BasicForm widget in the same way as new() and puts it into a Gtk::Dialog widget.

The returned dialog has the "Ok" and "Cancel" buttons which respectively return GTK_RESPONSE_ACCEPT and GTK_RESPONSE_REJECT.

The Gdaui::BasicForm widget is attached to the dialog using the user property "form".

Parameters:

  | data_set | A Gda::Set object.
  | parent | The parent window for the new dialog, or `0`.
  | title | The title of the dialog window, or `0`.
  | header | A helper text displayed at the top of the dialog, or `0`.

Returns:
  The new Gtk::Dialog widget

Since libgda-uimm 4.2:

## Member Function Documentation

void Gnome::GdaUI::BasicForm::entry_grab_focus | ( | const Glib::RefPtr< Gnome::Gda::Holder > & | holder | ) |

Makes the data entry corresponding to.

Parameters:

  | grab | the focus for the window it's in

Since libgda-uimm 4.2:

Parameters:

  | param | A Gda::Holder object.

void Gnome::GdaUI::BasicForm::entry_set_editable | ( | const Glib::RefPtr< Gnome::Gda::Holder > & | holder,
|  | bool | editable |
| ) |  |  |

Sets the Gdaui::DataEntry in form which corresponds to the.

Parameters:

  | parameter | editable or not. If
  | is | `0`, then all the parameters are concerned.

Since libgda-uimm 4.2:

Parameters:

  | param | A Gda::Holder object; or `0`.
  | editable | `true` if corresponding data entry must be editable.

void Gnome::GdaUI::BasicForm::entry_set_visible | ( | const Glib::RefPtr< Gnome::Gda::Holder > & | holder,
|  | bool | show |
| ) |  |  |

Shows or hides the Gdaui::DataEntry in form which corresponds to the.

Parameters:

  | parameter |

Since libgda-uimm 4.2:

Parameters:

  | param | A Gda::Holder object.

Glib::RefPtr<const Gnome::Gda::Set> Gnome::GdaUI::BasicForm::get_data_set | ( |  | ) | const

Get a pointer to the Gda::Set object which is modified by form.

Returns:
  A pointer to the Gda::Set

Since libgda-uimm 4.2:

Glib::RefPtr<Gnome::Gda::Set> Gnome::GdaUI::BasicForm::get_data_set | ( |  | ) |

Get a pointer to the Gda::Set object which is modified by form.

Returns:
  A pointer to the Gda::Set

Since libgda-uimm 4.2:

const Gtk::Widget* Gnome::GdaUI::BasicForm::get_entry_widget | ( | const Glib::RefPtr< Gnome::Gda::Holder > & | holder | ) | const

Get the Gdaui::DataEntry in form which corresponds to the param parameter.

Parameters:

  | param | A Gda::Holder object.

Returns:
  The requested widget, or `0` if not found

Since libgda-uimm 4.2:

Gtk::Widget* Gnome::GdaUI::BasicForm::get_entry_widget | ( | const Glib::RefPtr< Gnome::Gda::Holder > & | holder | ) |

Get the Gdaui::DataEntry in form which corresponds to the param parameter.

Parameters:

  | param | A Gda::Holder object.

Returns:
  The requested widget, or `0` if not found

Since libgda-uimm 4.2:

const Gtk::Widget* Gnome::GdaUI::BasicForm::get_label_widget | ( | const Glib::RefPtr< Gnome::Gda::Holder > & | holder | ) | const

Get the label in form which corresponds to the param parameter.

Parameters:

  | param | A Gda::Holder object.

Returns:
  The requested widget, or `0` if not found

Since libgda-uimm 4.2:

Gtk::Widget* Gnome::GdaUI::BasicForm::get_label_widget | ( | const Glib::RefPtr< Gnome::Gda::Holder > & | holder | ) |

Get the label in form which corresponds to the param parameter.

Parameters:

  | param | A Gda::Holder object.

Returns:
  The requested widget, or `0` if not found

Since libgda-uimm 4.2:

const Gtk::Widget* Gnome::GdaUI::BasicForm::get_place_holder | ( | const Glib::ustring & | placeholder_id | ) | const

Retreives a pointer to a place holder widget.

Parameters:

  | placeholder_id | The name of the requested place holder.

Returns:
  A pointer to the requested place holder, or `0` if not found

Since libgda-uimm 4.2:

Gtk::Widget* Gnome::GdaUI::BasicForm::get_place_holder | ( | const Glib::ustring & | placeholder_id | ) |

Retreives a pointer to a place holder widget.

Parameters:

  | placeholder_id | The name of the requested place holder.

Returns:
  A pointer to the requested place holder, or `0` if not found

Since libgda-uimm 4.2:

const GdauiBasicForm* Gnome::GdaUI::BasicForm::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::VBox.

Reimplemented in Gnome::GdaUI::RawForm.

GdauiBasicForm* Gnome::GdaUI::BasicForm::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GtkObject.

Reimplemented from Gtk::VBox.

Reimplemented in Gnome::GdaUI::RawForm.

bool Gnome::GdaUI::BasicForm::has_changed | ( |  | ) | const

Tells if the form has had at least on entry changed since form was created or set_as_reference() has been called.

Returns:
  `true` if one entry has changed at least

Since libgda-uimm 4.2:

bool Gnome::GdaUI::BasicForm::is_valid | ( |  | ) | const

Tells if the form can be used as-is (if all the parameters do have some valid values).

Returns:
  `true` if the form is valid

Since libgda-uimm 4.2:

virtual void Gnome::GdaUI::BasicForm::on_activated | ( |  | ) | `[protected, virtual]`

virtual void Gnome::GdaUI::BasicForm::on_holder_changed | ( | const Glib::RefPtr< Gnome::Gda::Holder > & | holder,
|  | bool | is_user_modified |
| ) |  |  | `[protected, virtual]`

virtual void Gnome::GdaUI::BasicForm::on_layout_changed | ( |  | ) | `[protected, virtual]`

Glib::PropertyProxy_ReadOnly<bool> Gnome::GdaUI::BasicForm::property_can_expand | ( |  | ) | const

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Gnome::GdaUI::BasicForm::property_entries_auto_default | ( |  | ) | const

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Gnome::GdaUI::BasicForm::property_entries_auto_default | ( |  | ) |

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Gnome::GdaUI::BasicForm::property_headers_sensitive | ( |  | ) | const

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Gnome::GdaUI::BasicForm::property_headers_sensitive | ( |  | ) |

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy_ReadOnly<bool> Gnome::GdaUI::BasicForm::property_show_actions | ( |  | ) | const

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Glib::PropertyProxy<bool> Gnome::GdaUI::BasicForm::property_show_actions | ( |  | ) |

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
  A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

void Gnome::GdaUI::BasicForm::reset | ( |  | ) |

Resets all the entries in the form to their original values.

Since libgda-uimm 4.2:

void Gnome::GdaUI::BasicForm::set_as_reference | ( |  | ) |

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 has_changed() will return `false` (of course until any entry is changed).

Since libgda-uimm 4.2:

void Gnome::GdaUI::BasicForm::set_entries_to_default | ( |  | ) |

For each entry in the form, sets it to a default value if it is possible to do so.

Since libgda-uimm 4.2:

void Gnome::GdaUI::BasicForm::set_layout_from_file | ( | const std::string & | file_name,
|  | const Glib::ustring & | 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).

Since libgda-uimm 4.2:

Parameters:

  | file_name | XML file name to use.
  | form_name | The name of the form to use, in file_name.

Glib::SignalProxy0< void > Gnome::GdaUI::BasicForm::signal_activated | ( |  | ) |

Prototype:
  `void on_my_activated()`

Glib::SignalProxy2< void,const Glib::RefPtr<Gnome::Gda::Holder>&,bool > Gnome::GdaUI::BasicForm::signal_holder_changed | ( |  | ) |

Prototype:
  `void on_my_holder_changed(const Glib::RefPtr<Gnome::Gda::Holder>& holder, bool is_user_modified)`

Glib::SignalProxy0< void > Gnome::GdaUI::BasicForm::signal_layout_changed | ( |  | ) |

Prototype:
  `void on_my_layout_changed()`

## Friends And Related Function Documentation

Gnome::GdaUI::BasicForm* wrap | ( | GdauiBasicForm * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

A Glib::wrap() method for this object.

Parameters:

  | object | The C instance.
  | take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- libgda-uimm/basicform.h