Q3SqlForm Class Reference

#include <q3sqlform.h>

Inheritance diagram for Q3SqlForm:

Inheritance graph
[legend]
Collaboration diagram for Q3SqlForm:

Collaboration graph
[legend]
List of all members.

Detailed Description

The Q3SqlForm class creates and manages data entry forms tied to SQL databases.

Typical use of a Q3SqlForm 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 Q3SqlForm. 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 Q3SqlForm does not access the database directly, but most often via QSqlFields which are part of a Q3SqlCursor. A Q3SqlCursor::insert(), Q3SqlCursor::update() or Q3SqlCursor::del() call is needed to actually write values to the database.

Some sample code to initialize a form successfully:

    QLineEdit  myEditor(this);
    Q3SqlForm   myForm(this);
    Q3SqlCursor 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 Q3SqlPropertyMap. The form uses this object to get or set the value of a widget.

See also:
installPropertyMap(), Q3SqlPropertyMap

Definition at line 43 of file q3sqlform.h.

Public Slots

virtual void readField (QWidget *widget)
virtual void writeField (QWidget *widget)
virtual void readFields ()
virtual void writeFields ()
virtual void clear ()
virtual void clearValues ()

Public Member Functions

 Q3SqlForm (QObject *parent=0)
 ~Q3SqlForm ()
virtual void insert (QWidget *widget, const QString &field)
virtual void remove (const QString &field)
int count () const
QWidget * widget (int i) const
QSqlField * widgetToField (QWidget *widget) const
QWidget * fieldToWidget (QSqlField *field) const
void installPropertyMap (Q3SqlPropertyMap *map)
virtual void setRecord (QSqlRecord *buf)

Protected Member Functions

virtual void insert (QWidget *widget, QSqlField *field)
virtual void remove (QWidget *widget)
void clearMap ()

Private Member Functions

virtual void sync ()

Private Attributes

Q3SqlFormPrivate * d

Constructor & Destructor Documentation

Q3SqlForm::Q3SqlForm ( QObject *  parent = 0  ) 

Constructs a Q3SqlForm with parent parent.

Definition at line 114 of file q3sqlform.cpp.

References d.

00115     : QObject(parent)
00116 {
00117     d = new Q3SqlFormPrivate();
00118 }

Q3SqlForm::~Q3SqlForm (  ) 

Destroys the object and frees any allocated resources.

Definition at line 123 of file q3sqlform.cpp.

References d.

00124 {
00125     delete d;
00126 }

Member Function Documentation

void Q3SqlForm::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()

Definition at line 165 of file q3sqlform.cpp.

References d, Q3SqlFormPrivate::dirty, Q3SqlFormPrivate::fld, QHash< Key, T >::insert(), Q3SqlFormPrivate::wgt, and widget().

Referenced by sync().

00166 {
00167     d->dirty = true;
00168     d->wgt.insert(field, widget);
00169     d->fld += field;
00170 }

Here is the call graph for this function:

void Q3SqlForm::remove ( const QString &  field  )  [virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Removes field from the form.

Definition at line 178 of file q3sqlform.cpp.

References d, Q3SqlFormPrivate::dirty, Q3SqlFormPrivate::fld, i, QStringList::indexOf(), QHash< Key, T >::remove(), QList< T >::removeAt(), and Q3SqlFormPrivate::wgt.

00179 {
00180     d->dirty = true;
00181     int i = d->fld.indexOf(field);
00182     if (i >= 0)
00183         d->fld.removeAt(i);
00184     d->wgt.remove(field);
00185 }

Here is the call graph for this function:

int Q3SqlForm::count (  )  const

Returns the number of widgets in the form.

Definition at line 237 of file q3sqlform.cpp.

References d, Q3SqlFormPrivate::map, and QMap< Key, T >::size().

00238 {
00239     return d->map.size();
00240 }

Here is the call graph for this function:

QWidget * Q3SqlForm::widget ( int  i  )  const

Returns the {i}-th widget in the form. Useful for traversing the widgets in the form.

Definition at line 246 of file q3sqlform.cpp.

References QMap< Key, T >::constBegin(), QMap< Key, T >::constEnd(), d, QMap< Key, T >::key(), Q3SqlFormPrivate::map, and QMap< Key, T >::size().

Referenced by insert(), readField(), remove(), widgetToField(), and writeField().

00247 {
00248     QMap< QWidget *, QSqlField * >::ConstIterator it;
00249     int cnt = 0;
00250 
00251     if(i > d->map.size())
00252         return 0;
00253     for(it = d->map.constBegin(); it != d->map.constEnd(); ++it){
00254         if(cnt++ == i)
00255             return it.key();
00256     }
00257     return 0;
00258 }

Here is the call graph for this function:

QSqlField * Q3SqlForm::widgetToField ( QWidget *  widget  )  const

Returns the SQL field that widget widget is mapped to.

Definition at line 276 of file q3sqlform.cpp.

References d, Q3SqlFormPrivate::map, QMap< Key, T >::value(), and widget().

Referenced by readField(), readFields(), writeField(), and writeFields().

00277 {
00278     return d->map.value(widget, 0);
00279 }

Here is the call graph for this function:

QWidget * Q3SqlForm::fieldToWidget ( QSqlField *  field  )  const

Returns the widget that field field is mapped to.

Definition at line 263 of file q3sqlform.cpp.

References QMap< Key, T >::constBegin(), QMap< Key, T >::constEnd(), d, QMap< Key, T >::key(), and Q3SqlFormPrivate::map.

00264 {
00265     QMap< QWidget *, QSqlField * >::ConstIterator it;
00266     for(it = d->map.constBegin(); it != d->map.constEnd(); ++it){
00267         if(*it == field)
00268             return it.key();
00269     }
00270     return 0;
00271 }

Here is the call graph for this function:

void Q3SqlForm::installPropertyMap ( Q3SqlPropertyMap *  pmap  ) 

Installs a custom Q3SqlPropertyMap. This is useful if you plan to create your own custom editor widgets.

Q3SqlForm takes ownership of pmap, so pmap is deleted when Q3SqlForm goes out of scope.

See also:
Q3DataTable::installEditorFactory()

Definition at line 137 of file q3sqlform.cpp.

References d, and Q3SqlFormPrivate::propertyMap.

00138 {
00139     if(d->propertyMap)
00140         delete d->propertyMap;
00141     d->propertyMap = pmap;
00142 }

void Q3SqlForm::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() writeFields()

Definition at line 151 of file q3sqlform.cpp.

References buf, Q3SqlFormPrivate::buf, d, and Q3SqlFormPrivate::dirty.

Referenced by Q3SqlFormManager::setForm(), and Q3SqlFormManager::setRecord().

00152 {
00153     d->dirty = true;
00154     d->buf = buf;
00155 }

void Q3SqlForm::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.

Definition at line 327 of file q3sqlform.cpp.

References d, Q3SqlPropertyMap::defaultMap(), Q3SqlFormPrivate::propertyMap, Q3SqlPropertyMap::setProperty(), sync(), QSqlField::value(), widget(), and widgetToField().

00328 {
00329     sync();
00330     QSqlField * field = 0;
00331     Q3SqlPropertyMap * pmap = (d->propertyMap == 0) ?
00332                              Q3SqlPropertyMap::defaultMap() : d->propertyMap;
00333     field = widgetToField(widget);
00334     if(field)
00335         pmap->setProperty(widget, field->value());
00336 }

void Q3SqlForm::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.

Definition at line 343 of file q3sqlform.cpp.

References d, Q3SqlPropertyMap::defaultMap(), Q3SqlPropertyMap::property(), Q3SqlFormPrivate::propertyMap, QSqlField::setValue(), sync(), widget(), and widgetToField().

00344 {
00345     sync();
00346     QSqlField * field = 0;
00347     Q3SqlPropertyMap * pmap = (d->propertyMap == 0) ?
00348                              Q3SqlPropertyMap::defaultMap() : d->propertyMap;
00349     field = widgetToField(widget);
00350     if(field)
00351         field->setValue(pmap->property(widget));
00352 }

void Q3SqlForm::readFields (  )  [virtual, slot]

Updates the widgets in the form with current values from the SQL fields they are mapped to.

Definition at line 285 of file q3sqlform.cpp.

References QMap< Key, T >::begin(), d, Q3SqlPropertyMap::defaultMap(), QMap< Key, T >::end(), QMap< Key, T >::key(), Q3SqlFormPrivate::map, Q3SqlFormPrivate::propertyMap, Q3SqlPropertyMap::setProperty(), sync(), QSqlField::value(), and widgetToField().

Referenced by clearValues(), and Q3SqlFormManager::readFields().

00286 {
00287     sync();
00288     QSqlField * f;
00289     QMap< QWidget *, QSqlField * >::Iterator it;
00290     Q3SqlPropertyMap * pmap = (d->propertyMap == 0) ?
00291                              Q3SqlPropertyMap::defaultMap() : d->propertyMap;
00292     for(it = d->map.begin() ; it != d->map.end(); ++it){
00293         f = widgetToField(it.key());
00294         if(!f)
00295             continue;
00296         pmap->setProperty(it.key(), f->value());
00297     }
00298 }

void Q3SqlForm::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 Q3SqlCursor::insert(), Q3SqlCursor::update() or Q3SqlCursor::del() as appropriate.

Definition at line 306 of file q3sqlform.cpp.

References QMap< Key, T >::begin(), d, Q3SqlPropertyMap::defaultMap(), QMap< Key, T >::end(), QMap< Key, T >::key(), Q3SqlFormPrivate::map, Q3SqlPropertyMap::property(), Q3SqlFormPrivate::propertyMap, QSqlField::setValue(), sync(), and widgetToField().

Referenced by Q3SqlFormManager::writeFields().

00307 {
00308     sync();
00309     QSqlField * f;
00310     QMap< QWidget *, QSqlField * >::Iterator it;
00311     Q3SqlPropertyMap * pmap = (d->propertyMap == 0) ?
00312                              Q3SqlPropertyMap::defaultMap() : d->propertyMap;
00313 
00314     for(it = d->map.begin() ; it != d->map.end(); ++it){
00315         f = widgetToField(it.key());
00316         if(!f)
00317             continue;
00318         f->setValue(pmap->property(it.key()));
00319     }
00320 }

void Q3SqlForm::clear (  )  [virtual, slot]

Removes every widget, and the fields they're mapped to, from the form.

Definition at line 227 of file q3sqlform.cpp.

References QList< T >::clear(), clearMap(), d, Q3SqlFormPrivate::dirty, and Q3SqlFormPrivate::fld.

00228 {
00229     d->dirty = true;
00230     d->fld.clear();
00231     clearMap();
00232 }

void Q3SqlForm::clearValues (  )  [virtual, slot]

Clears the values in all the widgets, and the fields they are mapped to, in the form, and sets them to NULL.

Definition at line 213 of file q3sqlform.cpp.

References QMap< Key, T >::begin(), d, QMap< Key, T >::end(), Q3SqlFormPrivate::map, and readFields().

Referenced by Q3SqlFormManager::clearValues().

00214 {
00215     QMap< QWidget *, QSqlField * >::Iterator it;
00216     for(it = d->map.begin(); it != d->map.end(); ++it){
00217         QSqlField* f = (*it);
00218         if (f)
00219             f->clear();
00220     }
00221     readFields();
00222 }

void Q3SqlForm::insert ( QWidget *  widget,
QSqlField *  field 
) [protected, virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Inserts a widget, and the field it is to be mapped to, into the form.

Definition at line 194 of file q3sqlform.cpp.

References d, Q3SqlFormPrivate::map, and widget().

00195 {
00196     d->map[widget] = field;
00197 }

Here is the call graph for this function:

void Q3SqlForm::remove ( QWidget *  widget  )  [protected, virtual]

Removes a widget, and hence the field it's mapped to, from the form.

Definition at line 204 of file q3sqlform.cpp.

References d, Q3SqlFormPrivate::map, QMap< Key, T >::remove(), and widget().

00205 {
00206     d->map.remove(widget);
00207 }

Here is the call graph for this function:

void Q3SqlForm::clearMap (  )  [protected]

Definition at line 376 of file q3sqlform.cpp.

References QMap< Key, T >::clear(), d, and Q3SqlFormPrivate::map.

Referenced by clear(), and sync().

00377 {
00378     d->map.clear();
00379 }

Here is the call graph for this function:

void Q3SqlForm::sync (  )  [private, virtual]

Definition at line 357 of file q3sqlform.cpp.

References QList< T >::at(), Q3SqlFormPrivate::buf, clearMap(), QList< T >::count(), d, Q3SqlFormPrivate::dirty, Q3SqlFormPrivate::fld, i, insert(), QHash< Key, T >::value(), and Q3SqlFormPrivate::wgt.

Referenced by readField(), readFields(), writeField(), and writeFields().

00358 {
00359     if (d->dirty) {
00360         clearMap();
00361         if (d->buf) {
00362             for (int i = 0; i < d->fld.count(); ++i) {
00363                 const QSqlField *field = d->buf->fieldPtr(d->fld.at(i));
00364                 insert(d->wgt.value(d->fld.at(i)), const_cast<QSqlField *>(field));
00365             }
00366         }
00367     }
00368     d->dirty = false;
00369 }

Here is the call graph for this function:

Member Data Documentation

Q3SqlFormPrivate* Q3SqlForm::d [private]

Definition at line 80 of file q3sqlform.h.

Referenced by clear(), clearMap(), clearValues(), count(), fieldToWidget(), insert(), installPropertyMap(), Q3SqlForm(), readField(), readFields(), remove(), setRecord(), sync(), widget(), widgetToField(), writeField(), writeFields(), and ~Q3SqlForm().

The documentation for this class was generated from the following files:
Generated on Thu Mar 15 16:19:46 2007 for Qt 4.2 User's Guide by  doxygen 1.5.1