--- name: "qsqlform" section: "3qt" platform: "linux" package: "qt3-doc" version: "3:3.3.8b-7" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/qsqlform" --- # qsqlform(3qt) Creates and manages data entry forms tied to SQL databases ## NAME QSqlForm - Creates and manages data entry forms tied to SQL databases ## SYNOPSIS `#include ` Inherits QObject. ### Public Members **QSqlForm ( QObject \* parent = 0, const char \* name = 0 )**\ **~QSqlForm ()**\ **virtual void insert ( QWidget \* widget, const QString & field )**\ **virtual void remove ( const QString & field )**\ **uint count () const**\ **QWidget \* widget ( uint i ) const**\ **QSqlField \* widgetToField ( QWidget \* widget ) const**\ **QWidget \* fieldToWidget ( QSqlField \* field ) const**\ **void installPropertyMap ( QSqlPropertyMap \* pmap )**\ **virtual void setRecord ( QSqlRecord \* buf )**\ ### Public Slots **virtual void readField ( QWidget \* widget )**\ **virtual void writeField ( QWidget \* widget )**\ **virtual void readFields ()**\ **virtual void writeFields ()**\ **virtual void clear ()**\ **virtual void clearValues ( bool nullify = FALSE )**\ ### Protected Members **virtual void insert ( QWidget \* widget, QSqlField \* field )**\ **virtual void remove ( QWidget \* widget )**\ ## DESCRIPTION The QSqlForm class creates and manages data entry forms tied to SQL databases. Typical use of a QSqlForm consists of the following steps: - Create the widgets you want to appear in the form. - Create a cursor and navigate to the record to be edited. - Create the QSqlForm. - Set the form's record buffer to the cursor's update buffer. - Insert each widget and the field it is to edit into the form. - Use readFields() to update the editor widgets with values from the database's fields. - Display the form and let the user edit values etc. - Use writeFields() to update the database's field values with the values in the editor widgets. Note that a QSqlForm does not access the database directly, but most often via QSqlFields which are part of a QSqlCursor. A QSqlCursor::insert(), QSqlCursor::update() or QSqlCursor::del() call is needed to actually write values to the database. Some sample code to initialize a form successfully: ``` QLineEdit myEditor( this ); QSqlForm myForm( this ); QSqlCursor myCursor( "mytable" ); // Execute a query to make the cursor valid myCursor.select(); // Move the cursor to a valid record (the first record) myCursor.next(); // Set the form's record pointer to the cursor's edit buffer (which // contains the current record's values) myForm.setRecord( myCursor.primeUpdate() ); // Insert a field into the form that uses myEditor to edit the // field 'somefield' in 'mytable' myForm.insert( &myEditor, "somefield" ); // Update myEditor with the value from the mapped database field myForm.readFields(); ... // Let the user edit the form ... // Update the database myForm.writeFields(); // Update the cursor's edit buffer from the form myCursor.update(); // Update the database from the cursor's buffer ``` If you want to use custom editors for displaying and editing data fields, you must install a custom QSqlPropertyMap. The form uses this object to get or set the value of a widget. Note that Qt Designer provides a visual means of creating data-aware forms. See also installPropertyMap(), QSqlPropertyMap, and Database Classes. ## MEMBER FUNCTION DOCUMENTATION ## QSqlForm::QSqlForm ( QObject \* parent = 0, const char \* name = 0 ) Constructs a QSqlForm with parent *parent* and called *name*. ## QSqlForm::~QSqlForm () Destroys the object and frees any allocated resources. ## void QSqlForm::clear ()` [virtual slot]` Removes every widget, and the fields they're mapped to, from the form. ## void QSqlForm::clearValues ( bool nullify = FALSE )` [virtual slot]` Clears the values in all the widgets, and the fields they are mapped to, in the form. If *nullify* is TRUE (the default is FALSE), each field is also set to NULL. ## uint QSqlForm::count () const Returns the number of widgets in the form. ## QWidget \* QSqlForm::fieldToWidget ( QSqlField \* field ) const Returns the widget that field *field* is mapped to. ## void QSqlForm::insert ( QWidget \* widget, const QString & field )` [virtual]` Inserts a *widget*, and the name of the *field* it is to be mapped to, into the form. To actually associate inserted widgets with an edit buffer, use setRecord(). See also setRecord(). Examples: ## void QSqlForm::insert ( QWidget \* widget, QSqlField \* field )` [virtual protected]` This is an overloaded member function, provided for convenience. It behaves essentially like the above function. Inserts a *widget*, and the *field* it is to be mapped to, into the form. ## void QSqlForm::installPropertyMap ( QSqlPropertyMap \* pmap ) Installs a custom QSqlPropertyMap. This is useful if you plan to create your own custom editor widgets. QSqlForm takes ownership of *pmap*, so *pmap* is deleted when QSqlForm goes out of scope. See also QDataTable::installEditorFactory(). Example: sql/overview/custom1/main.cpp. ## void QSqlForm::readField ( QWidget \* widget )` [virtual slot]` Updates the widget *widget* with the value from the SQL field it is mapped to. Nothing happens if no SQL field is mapped to the *widget*. ## void QSqlForm::readFields ()` [virtual slot]` Updates the widgets in the form with current values from the SQL fields they are mapped to. Examples: ## void QSqlForm::remove ( QWidget \* widget )` [virtual protected]` Removes a *widget*, and hence the field it's mapped to, from the form. ## void QSqlForm::remove ( const QString & field )` [virtual]` This is an overloaded member function, provided for convenience. It behaves essentially like the above function. Removes *field* from the form. ## void QSqlForm::setRecord ( QSqlRecord \* buf )` [virtual]` Sets *buf* as the record buffer for the form. To force the display of the data from *buf*, use readFields(). See also readFields() and writeFields(). Examples: ## QWidget \* QSqlForm::widget ( uint i ) const Returns the *i*-th widget in the form. Useful for traversing the widgets in the form. ## QSqlField \* QSqlForm::widgetToField ( QWidget \* widget ) const Returns the SQL field that widget *widget* is mapped to. ## void QSqlForm::writeField ( QWidget \* widget )` [virtual slot]` Updates the SQL field with the value from the *widget* it is mapped to. Nothing happens if no SQL field is mapped to the *widget*. ## void QSqlForm::writeFields ()` [virtual slot]` Updates the SQL fields with values from the widgets they are mapped to. To actually update the database with the contents of the record buffer, use QSqlCursor::insert(), QSqlCursor::update() or QSqlCursor::del() as appropriate. Example: sql/overview/form2/main.cpp. ## SEE ALSO **http://doc.trolltech.com/qsqlform.html** **http://www.trolltech.com/faq/tech.html** ## COPYRIGHT Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the license file included in the distribution for a complete license statement. ## AUTHOR Generated automatically from the source code. ## BUGS If you find a bug in Qt, please report it as described in **http://doc.trolltech.com/bughowto.html**. Good bug reports help us to help you. Thank you. The definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. This man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech. If you find errors in this manual page, please report them to **qt-bugs@trolltech.com**. Please include the name of the manual page (qsqlform.3qt) and the Qt version (3.3.8).