/****************************************************************************
** $Id:  qt/sql.doc   3.0.3   edited Oct 12 12:18 $
**
** Documentation for sql programming
**
** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be distributed under the terms of the Q Public License
** as defined by Trolltech AS of Norway and appearing in the file
** LICENSE.QPL included in the packaging of this file.
**
** This file may be distributed and/or modified under the terms of the
** GNU General Public License version 2 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.
**
** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
** licenses may use this file in accordance with the Qt Commercial License
** Agreement provided with the Software.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
**   information about Qt Commercial License Agreements.
** See http://www.trolltech.com/qpl/ for QPL licensing information.
** See http://www.trolltech.com/gpl/ for GPL licensing information.
**
** Contact info@trolltech.com if any conditions of this licensing are
** not clear to you.
**
**********************************************************************/
/*! \file sql/overview/connect1/main.cpp */
/*! \file sql/overview/create_connections/main.cpp  */
/*! \file sql/overview/basicbrowsing/main.cpp */
/*! \file sql/overview/basicbrowsing2/main.cpp */
/*! \file sql/overview/basicdatamanip/main.cpp */
/*! \file sql/overview/navigating/main.cpp */
/*! \file sql/overview/retrieve1/main.cpp */
/*! \file sql/overview/retrieve2/main.cpp */
/*! \file sql/overview/order1/main.cpp */
/*! \file sql/overview/order2/main.cpp */
/*! \file sql/overview/extract/main.cpp */
/*! \file sql/overview/insert/main.cpp */
/*! \file sql/overview/update/main.cpp */
/*! \file sql/overview/del/main.cpp */
/*! \file sql/overview/table1/main.cpp */
/*! \file sql/overview/table2/main.cpp */
/*! \file sql/overview/table3/main.h */
/*! \file sql/overview/table3/main.cpp */
/*! \file sql/overview/table4/main.h */
/*! \file sql/overview/table4/main.cpp */
/*! \file sql/overview/form1/main.cpp */
/*! \file sql/overview/form2/main.h */
/*! \file sql/overview/custom1/main.h */
/*! \file sql/overview/custom1/main.cpp */
/*! \file sql/overview/subclass1/main.cpp */
/*! \file sql/overview/subclass2/main.h */
/*! \file sql/overview/subclass2/main.cpp */
/*! \file sql/overview/subclass3/main.h */
/*! \file sql/overview/subclass3/main.cpp */
/*! \file sql/overview/subclass4/main.h */
/*! \file sql/overview/subclass4/main.cpp */
/*! \file sql/overview/subclass5/main.h */
/*! \file sql/overview/subclass5/main.cpp */

/*! \page sql.html
 
\title SQL Module

This module is part of the \link editions.html Qt Enterprise Edition \endlink.

\tableofcontents

\target Introduction
\section1 Introduction

Qt's SQL classes help you provide seamless database integration to
your Qt applications.

<blockquote>
This overview assumes that you have at least a basic knowledge of SQL.
You should be able to understand simple \c SELECT, \c INSERT, \c UPDATE
and \c DELETE commands. Although the \l QSqlCursor class provides an
interface to database browsing and editing that does not \e require a
knowledge of SQL, a basic understanding of SQL is highly recommended. A
standard text covering SQL databases is \e {An Introduction to Database
Systems (7th ed.)} by C. J. Date, ISBN 0201385902.
</blockquote>

Whilst this module overview presents the classes from a purely
programmatic point of view the \e {Qt Designer} manual's "Creating
Database Applications" chapter takes a higher-level approach
demonstrating how to set up master-detail relationships between widgets,
perform drilldown and handle foreign key lookups.

This document is divided into six sections:

\link #Architecture SQL Module Architecture \endlink. This describes the
how the classes fit together.

\link #Connecting_to_Databases Connecting to Databases \endlink. 
This section explains how to set up database connections using the \l
QSqlDatabase class.

\link #Executing_SQL_commands Executing SQL Commands \endlink. This
section demonstrates how to issue the standard data manipulation
commands, \c SELECT, \c INSERT, \c UPDATE and \c DELETE on tables in
the database (although any valid SQL statement can be sent to the
database). The focus is purely on database interaction using \l
QSqlQuery.

\link #Using_QSqlCursor Using Cursors \endlink. This section explains
how to use the QSqlCursor class which provides a more structured and
powerful API than the raw SQL used with \l QSqlQuery.

\link #Data-Aware_Widgets Data-Aware Widgets \endlink. This section shows
how to programmatically link your database to the user interface. In
this section we introduce the \l QDataTable, \l QSqlForm, \l
QSqlPropertyMap and QSqlEditorFactory classes and demonstrate how to use
custom data-aware widgets. \e {Qt Designer} provides an easy visual
way of achieving the same thing.  See the \e {Qt Designer} manual,
\l QDataBrowser and \l QDataView for more information.

\link #Subclassing_QSqlCursor Subclassing QSqlCursor \endlink. This
section gives examples of subclassing QSqlCursor. Subclassing can be
used to provide default and calculated values for fields (such as
auto-numbered primary index fields), and to display calculated data,
e.g. showing names rather than ids of foreign keys. 

\target Architecture
\section1 SQL Module Architecture

The SQL classes are divided into three layers:

\e {User Interface Layer.} These classes provide data-aware
widgets that can be connected to tables or views in the database (by
using a QSqlCursor as a data source). End users can interact directly
with these widgets to browse or edit data. \e {Qt Designer} is
fully integrated with the SQL classes and can be used to create
data-aware forms. The data-aware widgets can also be programmed
directly with your own C++ code. The classes that support this layer
include \l QSqlEditorFactory, \l QSqlForm, \l QSqlPropertyMap, \l
QDataTable, \l QDataBrowser and \l QDataView.

\e {SQL API Layer.} These classes provide access to databases.
Connections are made using the \l QSqlDatabase class. Database
interaction is achieved either by using the QSqlQuery class and
executing SQL commands directly or by using the higher level \l
QSqlCursor class which composes SQL commands automatically. In
addition to \l QSqlDatabase, \l QSqlCursor and \l QSqlQuery, the SQL
API layer is supported by QSqlError, QSqlField, QSqlIndex and
QSqlRecord.

\e {Driver Layer.} This comprises three classes, \l QSqlResult, \l
QSqlDriver and QSqlDriverFactoryInterface. This layer provides the
low level bridge between the database and the SQL classes. This layer
is \link sql-driver.html documented separately \endlink since it is
only relevant to driver writers, and is rarely used in standard
database application programming.  See \link sql-driver.html here
\endlink for more information on implementing a Qt SQL driver plugin.

\target Plugins
\section1 SQL Driver Plugins

The Qt SQL module can dynamically load new drivers at runtime using
the \link plugins-howto.html Plugins \endlink.

The \link sql-driver.html SQL driver documentation\endlink describes
how to build plugins for specific database management systems.

Once a plugin is built, Qt will automatically load it, and the driver
will be available for use by QSqlDatabase (see QSqlDatabase::drivers()
for more information).

\target Connecting_to_Databases
\section1 Connecting to Databases

At least one database connection must be created and opened before the
\l QSqlQuery or \l QSqlCursor classes can be used.

If the application only needs a single database connection, the \l
QSqlDatabase class can create a connection which is used by default
for all SQL operations. If multiple database connections are required
these can easily be set up.

\l QSqlDatabase requires the \c qsqldatabase.h header file.

\target Connecting_to_a_Single_Database
\section1 Connecting to a Single Database

Making a database connection is a simple three step process: activate
the driver, set up the connection information, and open the
connection.

\quotefile sql/overview/connect1/main.cpp
\skipto include
\printline include
\printuntil return 0
\printline
\caption From \l sql/overview/connect1/main.cpp

First we activate the driver by calling \l QSqlDatabase::addDatabase(),
passing the name of the driver we wish to use for this connection. At
the time of writing the available drivers are: QODBC3 (Open Database
Connectivity), QOCI8 (Oracle), QTDS7 (Sybase Adaptive Server and 
Microsoft SQL Server), QPSQL7 (PostgreSQL 6 and 7) and QMYSQL3 (MySQL).
Note that some of these drivers aren't included in the Qt Free Edition, 
look at the README files for details.

The connection which is created becomes the application's default 
database connection and will be used by the Qt SQL classes if no 
other database is specified. 

Second we call setDatabaseName(), setUserName(), setPassword() and
setHostName() to initialize the connection information. Note that
for the QOCI8 (Oracle) driver the TNS Service Name has to be passed
to setDatbaseName().

Third we call open() to open the database and give us access to the
data. If this call fails it will return FALSE; error information can
be determined using \l QSqlDatabase::lastError().

\target Connecting_to_Multiple_Databases
\section2 Connecting to Multiple Databases

Connecting to multiple databases is achieved using the two argument form
of \l QSqlDatabase::addDatabase() where the second argument is a unique
identifier distinguishing the connection.

\target create_connections
\quotefile sql/overview/create_connections/main.cpp
\skipto include
\printline include
\printuntil return TRUE 
\printline
\caption From \l sql/overview/create_connections/main.cpp

In the example above we have moved the connections into their own
function, createConnections(), and added some basic error handling. The
static function \l QSqlDatabase::database() can be called from anywhere
to provide a pointer to a database connection. If we call it without any
parameter it will return the default connection. If called with the
identifier we've used for a connection, e.g. "ORACLE", in the above
example, it will return a pointer to the specified connection.

If you create a \c main.cpp using \e{Qt Designer}, it will \e not
include our example createConnections() function. This means that
applications that preview correctly in \e{Qt Designer} will not run
unless you implement your own database connections function.

Note that in the code above the ODBC connection was not named and is
therefore used as the default connection.  \l QSqlDatabase maintains
ownership of the pointers returned by the addDatabase() static
function.  To remove a database from the list of maintained
connections, first close the database with QSqlDatabase::close(), and
then remove it using the static function
QSqlDatabase::removeDatabase().

\target Executing_SQL_commands
\section1 Executing SQL Commands Using QSqlQuery

The \l QSqlQuery class provides an interface for executing SQL commands.
It also has functions for navigating through the result sets of \c SELECT
queries and for retrieving individual records and field values.

The \l QSqlCursor class described in the next section inherits from \l
QSqlQuery and provides a higher level interface that composes SQL
commands for us. \l QSqlCursor is particularly easy to integrate with
on-screen widgets. Programmers unfamiliar with SQL can safely skip this
section and use the \l QSqlCursor class covered in 
\link #Using_QSqlCursor "Using QSqlCursor" \endlink.

\target Transactions
\section2 Transactions

If the underlying database engine supports transactions
QSqlDriver::hasFeature( QSqlDriver::Transactions ) will return TRUE. You can use
QSqlDatabase::transaction() to initiate a transaction, followed by the
SQL commands you want to execute within the context of the transaction,
and then either QSqlDatabase::commit() or \l{QSqlDatabase::rollback()}.

\target Basic_Browsing
\section2 Basic Browsing

\quotefile sql/overview/basicbrowsing/main.cpp
\skipto include
\printline include
\printuntil return 0 
\printline
\caption From \l sql/overview/basicbrowsing/main.cpp

In the example above we've added an additional header file, 
\c qsqlquery.h. The first query we create, \c target, uses the default
database and is initially empty. For the second query, \c q, we specify
the "ORACLE" database that we want to retrieve records from. Both the
database connections were set up in the createConnections() function we
wrote earlier.

After creating the initial \c SELECT statement, isActive() is checked
to see if the query executed successfully. The next() function is
used to iterate through the query results. The value() function
returns the contents of fields as QVariants. The insertions are
achieved by creating and executing queries against the default
database using the \c target QSqlQuery.

\quotefile sql/overview/basicbrowsing2/main.cpp
\skipto count
\printline 
\printuntil numRows 
\printline
\printline
\caption From \l sql/overview/basicbrowsing2/main.cpp

The above code introduces a count of how many records are successfully
inserted. Note that isActive() returns FALSE if the query, e.g. the
insertion, fails. numRowsAffected() returns -1 if the number of rows
cannot be determined, e.g. if the query fails.

\target Basic_Data_Manipulation
\section2 Basic Data Manipulation

\quotefile sql/overview/basicdatamanip/main.cpp
\skipto main
\printline main
\printuntil return ( rows 
\printline
\caption From \l sql/overview/basicdatamanip/main.cpp

This example demonstrates straightforward SQL DML (data manipulation
language) commands. Since we did not specify a database in the \l
QSqlQuery constructor the default database is used. \l QSqlQuery objects
can also be used to execute SQL DDL (data definition language) commands
such as \c CREATE TABLE and \c CREATE INDEX.

\target Navigating_Result_Sets
\section2 Navigating Result Sets

Once a \c SELECT query has been executed successfully we have access
to the result set of records that matched the query criteria. We have
already used one of the navigation functions, next(), which can be
used alone to step sequentially through the records. \l QSqlQuery also
provides first(), last(), next() and prev(). After any of these
commands we can check that we are on a valid record location by
calling isValid().

We can also navigate to any arbitrary record using seek(). The
first record in the dataset is zero. The number of the last record is
size() - 1. Note that not all databases provide the size of a
\c SELECT query and in such cases size() returns -1.

\quotefile sql/overview/navigating/main.cpp
\skipto if (
\printline if (
\printuntil i == 4 
\printline
\caption From \l sql/overview/navigating/main.cpp

The example above shows some of the navigation functions in use. 

Not all drivers support size(), but we can interrogate the driver to
find out:

\code
    QSqlDatabase* defaultDB = QSqlDatabase::database();
    if ( defaultDB->driver()->hasFeature( QSqlDriver::QuerySize ) ) {
	// QSqlQuery::size() supported
    }
    else {
	// QSqlQuery::size() cannot be relied upon
    }
\endcode


Once we have located the record we are interested in we may wish to
retrieve data from it. 

\quotefile sql/overview/retrieve1/main.cpp
\skipto if (
\printline if (
\printuntil qDebug 
\printline
\printline
\printline
\printline
\caption From \l sql/overview/retrieve1/main.cpp

Note that if you wish to iterate through the record set in order the
only navigation function you need is next().

Tip: The lastQuery() function returns the text of the last query
executed. This can be useful to check that the query you think is being
executed is the one actually being executed.

\target Using_QSqlCursor
\section1 Using QSqlCursor

The \l QSqlCursor class provides a high level interface to browsing and
editing records in SQL database tables or views without the need to
write your own SQL.

QSqlCursor can do almost everything that QSqlQuery can, with two
exceptions. Since cursors represent tables or views within the
database, by default, \l QSqlCursor objects retrieve all the fields of
each record in the table or view whenever navigating to a new
record. If only some fields are relevant simply confine your
processing to those and ignore the others. Or, manually disable the
generation of certain fields using QSqlRecord::setGenerated().
However, if you really don't want to retrieve all fields in the cursor
then you should use a \l QSqlQuery instead, and customize the query to
suit your needs.  You can edit records using a \l QSqlCursor providing
that the table or view has a primary index that uniquely distinguishes
each record. If this condition is not met then you'll need to use a \l
QSqlQuery for edits. (Note that not all databases support editable
views.)

QSqlCursor operates on a single record at a time.  Whenever performing
an insert, update or delete using QSqlCursor, only a single record in
the database is affected.  When navigating through records in the
cursor, only one record at a time is available in application code.
In addition, QSqlCursor maintains a separate 'edit buffer' which is
used to make changes to a single record in the database.  The edit
buffer is maintained in a separate memory area, and is unnaffected by
the 'navigation buffer' which changes as the cursor moves from record
to record.

Before we can use \l QSqlCursor objects we must first create and open
a database connection. Connecting is described in the \link
#Connecting_to_Databases Connecting to Databases \endlink section
above. For the examples that follow we will assume that the
connections have been created using the createConnections() function
defined in the \link #create_connections QSqlDatabase example \endlink
presented earlier.

In the \link #Data-Aware_Widgets data-aware widgets \endlink section that
follows this one we show how to link widgets to database cursors. Once
we have a knowledge of both cursors and data-aware widgets we can
discuss \link #Subclassing_QSqlCursor subclassing QSqlCursor \endlink.

The \l QSqlCursor class requires the \c qsqlcursor.h header file.

\target Retrieving_Records
\section2 Retrieving Records

\quotefile sql/overview/retrieve2/main.cpp
\skipto include
\printline include
\printuntil return 0 
\printline
\caption From \l sql/overview/retrieve2/main.cpp

We create the \l QSqlCursor object, specifying the table or view to use.
If we need to use a database other than the default we can specify it
in the QSqlCursor constructor.

The SQL executed by the cur.select() call is

\code
    SELECT staff.id, staff.forename, staff.surname, staff.salary, staff.statusid FROM staff
\endcode

Next, we iterate through the records returned by this select statement
using cur.next().  Field values are retrieved in in a similar way to
QSqlQuery, except that we pass field names rather than numeric indexes
to value() and setValue().

\target Sorting_Data
\section3 Sorting and Filtering Records

To specify a subset of records to retrieve we can pass filtering
criteria to the select() function.  Each record that is returned will
meet the criteria of the filter (the filter corresponds to the SQL
statement's WHERE clause).

\code
    cur.select( "id > 100" );
\endcode

This select() call will execute the SQL
\code
    SELECT staff.id, staff.forename, staff.surname, staff.salary, staff.statusid 
    FROM staff WHERE staff.id > 100
\endcode

This will retrieve only those staff whose \c id is greater than 100.

In addition to retrieving selected records we often want to specify a
sort order for the returned records. This is achieved by creating a \l
QSqlIndex object which contains the names of the field(s) we wish to
sort by and pass this object to the select() call.

\code
    QSqlCursor cur( "staff" );
    QSqlIndex nameIndex = cur.index( "surname" ); 
    cur.select( nameIndex );
\endcode

Here we create a \l QSqlIndex object with one field, "surname". When
we call the select() function we pass the index object, which
specifies that the records should be returned sorted by
staff.surname. Each field in the index object is used in the ORDER BY
clause of the select statement.  The SQL executed here is 
\code
    SELECT staff.id, staff.forename, staff.surname, staff.salary, staff.statusid 
    FROM staff ORDER BY staff.surname ASC
\endcode

Combining the retrieval of a subset of records and ordering the results
is straightforward.

\code
    cur.select( "surname LIKE 'A%'", nameIndex );
\endcode

We pass in a filter string (the WHERE clause), and the \l QSqlIndex
object to sort by (the ORDER BY clause). This produces

\code
    SELECT staff.id, staff.forename, staff.surname, staff.salary, staff.statusid
    FROM staff WHERE staff.surname LIKE 'A%' ORDER BY staff.surname ASC
\endcode

To sort by more than one field, an index can be created which contains
multiple fields.  Ascending and descending order can be set using
QSqlIndex::setDescending(); the default is ascending.

\quotefile sql/overview/order1/main.cpp
\skipto QSqlCursor
\printline QSqlCursor
\printuntil while 
\caption From \l sql/overview/order1/main.cpp

Here we create a string list containing the fields we wish to sort by,
in the order they are to be used. Then we create a \l QSqlIndex object
based on these fields, finally executing the select() call using this
index. This executes
\code
    SELECT staff.id, staff.forename, staff.surname, staff.salary, staff.statusid
    FROM staff ORDER BY staff.surname ASC, staff.forename ASC
\endcode

If we need to retrieve records with fields that match specific criteria we
can create a filter based on an index.

\quotefile sql/overview/order2/main.cpp
\skipto QSqlCursor
\printline QSqlCursor
\printuntil while 
\caption From \l sql/overview/order2/main.cpp

This executes
\code
    SELECT staff.id, staff.forename, staff.surname, staff.salary, staff.statusid 
    FROM staff WHERE staff.surname='Bloggs' ORDER BY staff.id ASC, staff.forename ASC
\endcode

The "order" \l QSqlIndex contains two fields, "id" and "forename"
which are used to order the results. The "filter" \l QSqlIndex
contains a single field, "surname". When an index is passed as a
filter to the select() function, for each field in the filter, a
\e fieldname=value subclause is created where the value
is taken from the current cursor's value for that field. We use
setValue() to ensure the value used is the one we want.

\target Extracting_Data
\section3 Extracting Data

\quotefile sql/overview/extract/main.cpp
\skipto QSqlCursor
\printline QSqlCursor
\printuntil qDebug
\printline
\caption From \l sql/overview/extract/main.cpp

In this example we begin by creating a cursor on the creditors table. We
create two \l QSqlIndex objects. The first, "order", is created from the
"orderFields" string list. The second, "filter", is created from the
"filterFields" string list. We set the values of the two fields used in
the filter, "surname" and "city", to the values we're interested in. Now
we call select() which generates and executes the following SQL:
\code
    SELECT creditors.city, creditors.surname, creditors.forename, creditors.id 
    FROM creditors 
    WHERE creditors.surname = 'Chirac' AND creditors.city = 'Paris' 
    ORDER BY creditors.surname ASC, creditors.forename ASC
\endcode
The filter fields are used in the WHERE clause. Their values are taken
from the cursor's current values for those fields; we set these values
ourselves with the setValue() calls. The order fields are used in the
ORDER BY clause. 

Now we iterate through each matching record (if any). We retrieve the
contents of the id, forename and surname fields and pass them on to some
processing function, in this example a simple qDebug() call.

\target Manipulating_Records
\section2 Manipulating Records

Records can be inserted, updated or deleted in a table or view using a
\l QSqlCursor providing that the table or view has a primary index
that uniquely distinguishes each record. If this is not the case a \l
QSqlQuery must be used instead. (Note that not all databases support
editable views.)

Each cursor has an internal 'edit buffer' which is used by all the edit
operations (insert, update and delete).  The editing process is the same
for each operation: acquire a pointer to the relevant buffer; call
setValue() to prime the buffer with the values you want; call insert()
or update() or del() to perform the desired operation. For example, when
inserting a record using a cursor, you call primeInsert() to get a
pointer to the edit buffer and then call setValue() on this buffer to
set each field's value. Then you call QSQlCursor::insert() to insert the
contents of the edit buffer into the database.  Similarly, when updating
(or deleting) a record, the values of the fields in the edit buffer are
used to update (or delete) the record in the database.  The 'edit
buffer' is unaffected by any \link #Navigating_Result_Sets cursor
navigation \endlink functions. Note that if you pass a string value to
setValue() any single quotes will be escaped (turned into a pair of
single quotes) since a single quote is a special character in SQL.

The primeInsert(), primeUpdate() and primeDelete() methods all return
a pointer to the internal edit buffer, however each method can
potentially perform different operations on the edit buffer before
returning it.  By default,  QSqlCursor::primeInsert() clears all the
field values in the edit buffer (see \l QSqlRecord::clearValues()).
Both \l QSqlCursor::primeUpdate() and QSqlCursor::primeDelete()
initialize the edit buffer with the current contents of the cursor
before returning it.  All three of these functions are virtual, so
you can redefine the behavior (for example, reimplementing
primeInsert() to auto-number fields in the edit buffer). Data-aware
user-interface controls emit signals, e.g. primeInsert(), that you
can connect to; these pass a pointer to the appropriate buffer so
subclassing may not be necessary. See \link #Subclassing_QSqlCursor
subclassing QSqlCursor \endlink for more information on subclassing;
see the \e {Qt Designer} manual for more on connecting to the
primeInsert() signal.

When insert(), update() or del() is called on a cursor, it will be
invalidated and will no longer be positioned on a valid record. If we
need to move to another record after performing an insert(), update()
or del() we must make a fresh select() call.  This ensures that
changes to the database are accurately reflected in the cursor.

\target Inserting_Records
\section3 Inserting Records

\quotefile sql/overview/insert/main.cpp
\skipto QSqlCursor
\printline QSqlCursor
\printuntil } 
\caption From \l sql/overview/insert/main.cpp

In this example we create a cursor on the "prices" table. Next we
create a list of product names which we iterate over. For each
iteration we call the cursor's primeInsert() method. This method
returns a pointer to a \l QSqlRecord buffer in which all the fields
are set to \c NULL. (Note that QSqlCursor::primeInsert() is virtual,
and can be customized by derived classes.  See \l QSqlCursor). Next we
call setValue() for each field that requires a value. Finally we call
insert() to insert the record. The insert() call returns the number of
rows inserted.

We obtained a pointer to a \l QSqlRecord object from the primeInsert()
call. QSqlRecord objects can hold the data for a single record plus some
meta-data about the record. In practice most interaction with a
QSqlRecord consists of simple value() and setValue() calls as shown in
this and the following example. 

\target Updating_Records
\section3 Updating Records

\quotefile sql/overview/update/main.cpp
\skipto QSqlCursor
\printline QSqlCursor
\printuntil update
\printline
\caption From \l sql/overview/update/main.cpp

This example begins with the creation of a cursor over the prices table.
We select the record we wish to update with the select() call and
move to it with the next() call. We call primeUpdate() to get a \l
QSqlRecord pointer to a buffer which is populated with the contents of
the current record. We retrieve the value of the price field, calculate
a new price, and set the the price field to the newly calculated value.
Finally we call update() to update the record. The update() call returns
the number of rows updated.

If many identical updates need to be performed, for example increasing
the price of every item in the price list, using a single SQL statement
with \l QSqlQuery is more efficient, e.g.

\code
    QSqlQuery query( "UPDATE prices SET price = price * 1.05"  );
\endcode

\target Deleting_Records
\section3 Deleting Records

\quotefile sql/overview/del/main.cpp
\skipto QSqlCursor
\printline QSqlCursor
\printuntil del
\caption From \l sql/overview/del/main.cpp

To delete records, select the record to be deleted and navigate to it.
Then call primeDelete() to populate the cursor with the primary key
of the selected record, (in this example, the \c prices.id field), and
then call QSqlCursor::del() to delete it. 

As with update(), if multiple deletions need to be made with some common
criteria it is more efficient to do so using a single SQL statement,
e.g.

\code
    QSqlQuery query( "DELETE FROM prices WHERE id >= 2450 AND id <= 2500" );
\endcode

\target Data-Aware_Widgets
\section1 Data-Aware Widgets

Data-Aware Widgets provide a simple yet powerful means of connecting
databases to Qt user interfaces. The easiest way of creating and
manipulating data-aware widgets is with \e {Qt Designer}. 
For those who prefer a purely programmatic approach the following
examples and explanations provide an introduction. Note that the
"Creating Database Applications" chapter of the \e {Qt Designer}
manual and its accompanying examples provides additional information.

\target Data-Aware_Tables
\section2 Data-Aware Tables

\quotefile sql/overview/table1/main.cpp
\skipto include
\printline include
\printuntil return 0
\printline
\caption From \l sql/overview/table1/main.cpp

Data-Aware tables require the \c qdatatable.h and \c qsqlcursor.h header
files. We create our application object, call createConnections() and
create the cursor. We create the \l QDataTable passing it a pointer to
the cursor, and set the autoPopulate flag to TRUE. Next we make our \l
QDataTable the main widget and call refresh() to populate it with data
and call show() to make it visible.

The autoPopulate flag tells the \l QDataTable whether or nor it should
create columns based on the cursor. autoPopulate does not affect the
loading of data into the table; that is achieved by the refresh()
function.

\quotefile sql/overview/table2/main.cpp
\skipto staffCursor
\printline staffCursor
\printuntil show 
\caption From \l sql/overview/table2/main.cpp

We create an empty \l QDataTable which we make into our main widget and
then we manually add the columns we want in the order we wish them to
appear. For each column we specify the field name and optionally a
display label. 

We have also opted to sort the rows in the table; this could also have
been achieved by applying the sort to the cursor itself.

Once everything is set up we call refresh() to load the data from the
database and show() to make the widget visible.

QDataTables only retrieve visible rows which (depending on the driver)
allows even large tables to be displayed very quickly with minimal
memory cost.

\target Creating_Forms
\section2 Creating Data-Aware Forms

Creating data-aware forms is more involved than using data-aware
tables because we must take care of each field individually.  Most of
the code below can be automatically generated by \e {Qt Designer}.
See the \e {Qt Designer} manual for more details.

\target Displaying_a_Record
\section3 Displaying a Record

\quotefile sql/overview/form1/main.cpp
\skipto include
\printline include
\printuntil app.exec
\printline
\caption From \l sql/overview/form1/main.cpp

We include the header files for the widgets that we need. We also
include \c qsqldatabase.h and \c qsqlcursor.h as usual, but we now add
\c qsqlform.h.

The form will be presented as a dialog so we subclass \l QDialog with
our own FormDialog class. We use a \l QLineEdit for the salary so that
the user can change it. All the widgets are laid out with a grid.

We create a cursor on the staff table, select all records and move to
the first record.

Now we create a \l QSqlForm object and set the QSqlForm's record buffer
to the cursor's update buffer. For each widget that we wish to make
data-aware we insert a pointer to the widget and the associated field
name into the \l QSqlForm. Finally we call readFields() to populate the
widgets with data from the database via the cursor's buffer.

\target Displaying_a_Record_in_a_DataForm
\section3 Displaying a Record in a Data Form

\l QDataView is a Widget that can hold a read-only \l QSqlForm. In
addition to \l QSqlForm it offers the slot refresh ( \l QSqlRecord * ) so it
can easily be linked together with a \l QDataTable to display a detailled
view of a record:

\code
    connect( myDataTable, SIGNAL( currentChanged( QSqlRecord* ) ), 
	     myDataView, SLOT( refresh( QSqlRecord* ) ) );
\endcode

\target Editing_a_Record
\section3 Editing a Record

This example is similar to the previous one so we will focus on the
differences.

\quotefile sql/overview/form2/main.h
\skipto class
\printline class
\printuntil };
\caption From \l sql/overview/form2/main.h

The save slot will be used for a button that the user can press to
confirm their update. We also hold pointers to the \l QSqlCursor and the
\l QSqlForm since they will need to be accessed outside the constructor.

\quotefile sql/overview/form2/main.cpp
\skipto setTrimmed
\printline setTrimmed
\printline

We call setTrimmed() on the text fields so that any spaces used to right
pad the fields are removed when the fields are retrieved.

Properties that we might wish to apply to fields, such as alignment and
validation are achieved in the conventional way, for example, by calling
QLineEdit::setAlignment and QLineEdit::setValidator.

\skipto forenameEdit
\printline forenameEdit

\skipto saveButton
\printline saveButton
\printline connect

The FormDialog constructor is similar to the one in the previous
example. We have changed the forename and surname widgets to QLineEdits
to make them editable and have added a \l QPushButton the user can click
to save their updates.

\skipto saveButton
\printline saveButton

We add an extra row to the grid containing the save button.

\skipto staffCursor
\printline staffCursor
\printuntil first

We create a \l QSqlIndex object and then execute a select() using the
index. We then move to the first record in the result set.

\skipto new QSqlForm
\printline 
\printline

We create a new QSqlForm object and set it's record buffer to the
cursor's update buffer.

\skipto insert
\printline insert
\printuntil readFields

Now we link the buffer's fields to the \l QLineEdit controls. (In the
previous example we linked the cursor's fields.) The edit controls are
populated by the readFields() call as before.

\skipto FormDialog::
\printline FormDialog::
\printuntil }

In the destructor we don't have to worry about the widgets or QSqlForm
since they are children of the form and will be deleted by Qt at the
right time.

\skipto save
\printline save
\printuntil }

Finally we add the save functionality for when the user presses the save
button. We write back the data from the widgets to the \l QSqlRecord
buffer with the writeFields() call. Then we update the database with the
updated version of the record with the cursor's update() function. At
this point the cursor is no longer positioned at a valid record so we
reissue the select() call using our \l QSqlIndex and move to the first
record.

QDataBrowser and QDataView are widgets which provide a great deal of
the above functionality.  \l QDataBrowser provides a data form which
allows editing of and navigation through records in a cursor.  \l
QDataView provides a read only form for data in a cursor or database
record.  See the class documentation or the \e {Qt Designer}
manual for more information on using these widgets.

Link to \l sql/overview/form2/main.cpp

\target Custom_Editor_Widgets
\section2 Custom Editor Widgets

QSqlForm uses QSqlPropertyMap to handle the transfer of data between
widgets and database fields. Custom widgets can also be used in a form
by installing a property map that contains information about the
properties of the custom widget which should be used to transfer the
data.

This example is based on the form2 example in the previous section so we
will only cover the differences here. The full source is in
\l sql/overview/custom1/main.h and \l sql/overview/custom1/main.cpp

\quotefile sql/overview/custom1/main.h
\skipto CustomEdit
\printline CustomEdit
\printuntil };

We've created a simple subclass of QLineEdit and added a property,
upperLineText, which will hold an uppercase version of the text. We also
created a slot, changed.

\skipto propMap
\printline propMap

We will be using a property map so we add a pointer to a property map to
our FormDialog's private data.

\quotefile sql/overview/custom1/main.cpp
\skipto CustomEdit
\printline CustomEdit
\printuntil }

In the CustomEdit constructor we use the QLineEdit constructor and add a
connection between the textChanged signal and our own changed slot.

\skipto changed
\printline changed
\printuntil }

The changed() slot calls our setUpperLine() function.

\skipto setUpperLine
\printline setUpperLine
\printuntil }

The setUpperLine() function places an uppercase copy of the text in the
upperLineText buffer and then sets the text of the widget to this text. 

Our CustomEdit class ensures that the text entered is always uppercase
and provides a property that can be used with a property map to link
CustomEdit instances directly to database fields.

\skipto FormDialog
\skipto CustomEdit
\printline CustomEdit

\skipto CustomEdit
\printline CustomEdit

We use the same FormDialog as we did before, but this time replace two
of the QLineEdit widgets with our own CustomEdit widgets. 

Laying out the grid and setting up the cursor is the same as before.

\skipto propMap
\printline propMap
\printline propMap

We create a new property map on the heap and register our CustomEdit
class and its upperLine property with the property map.

\skipto QSqlForm
\printline QSqlForm
\printline
\printline propMap

The final change is to install the property map into the QSqlForm once
the QSqlForm has been created. This passes responsibility for the
property map's memory to QSqlForm which itself is owned by the
FormDialog, so Qt will delete them at the right time.

The behaviour of this example is identical to the previous one except
that the forename and surname fields will be uppercase since they use
our CustomEdit widget.

\target Custom_Editor_Widgets_for_Tables
\section3 Custom Editor Widgets for QTables

We must reimpliment QSqlEditorFactory to use custom editor widgets in
tables. In the following example we will create a custom editor based on
QComboBox and a QSqlEditorFactory subclass to show how a QTable can use
a custom editor.

\quotefile sql/overview/table3/main.h
\skipto StatusPicker
\printline StatusPicker
\printuntil }; 
\caption From \l sql/overview/table3/main.h

We create a property, statusid, and define our READ and WRITE methods
for it. The statusid's in the status table will probably be different
from the combobox's indexes so we create a QMap to map combobox indexes
to/from the statusids that we will list in the combobox.

\skipto CustomSqlEditor
\printline CustomSqlEditor
\printuntil }; 

We also need to subclass QSqlEditorFactory declaring a createEditor()
function since that is the only function we need to reimplement. 

\quotefile sql/overview/table3/main.cpp
\skipto StatusPicker
\printline StatusPicker
\printuntil index2id
\printline
\printline
\caption From \l sql/overview/table3/main.cpp

In the StatusPicker's constructor we create a cursor over the status
table indexed by the name field. We then iterate over each record in the
status table inserting each name into the combobox. We store the
statusid for each name in the index2id QMap using the same QMap index as
the combobox index.

\skipto StatusPicker
\printline StatusPicker
\printuntil } 

The statusid property READ function simply involves looking up the
combobox's index for the currently selected item in the index2id QMap
which maps combobox indexes to statusids.

\skipto StatusPicker
\printline StatusPicker
\printuntil } 
\printline
\printline

The statusId() function implements the statusid property's WRITE
function. We create an iterator over a QMap and iterate over the
index2id QMap. We compare each index2id element's data (statusid) to the
id parameter's value. If we have a match we set the combobox's current
item to the index2id element's key (the combobox index), and leave the
loop.

When the user edits the status field in the QDataTable they will be
presented with a combobox of valid status names taken from the status
table. However the status displayed is still the raw statusid. To
display the status name when the field isn't being edited requires us to
subclass QDataTable and reimplement the paintField() function.

\quotefile sql/overview/table4/main.h
\skipto CustomTable
\printline CustomTable
\printuntil };
\caption From \l sql/overview/table4/main.h

We simply call the original QDataTable constructor without changing
anything. We also declare the paintField function.

\quotefile sql/overview/table4/main.cpp
\skipto CustomTable
\printline CustomTable
\printuntil QDataTable
\printline
\caption From \l sql/overview/table4/main.cpp

The paintField code is based on QDataTable's source code. We need to make
three changes. Firstly add an if clause \c {field->name() ==
"statusid"} and look up the textual value for the id with a
straighforward QSqlQuery. Secondly call the superclass to handle other
fields. The last change is in our main function where we change
staffTable from being a QDataTable to being a CustomTable. 

\target Subclassing_QSqlCursor
\section1 Subclassing QSqlCursor

\quotefile sql/overview/subclass1/main.cpp
\skipto include
\printline include
\printuntil return 1
\printline
\caption From \l sql/overview/subclass1/main.cpp

This example is very similar to the table1 example presented earlier. We
create a cursor, add the fields and their display labels to a QDataTable,
call refresh() to load the data and call show() to show the widget.

Unfortunately this example is unsatisfactory. It is tedious to set the
table name and any custom characteristics for the fields every time we
need a cursor over this table. And it would be far better if we
displayed the name of the product rather than its pricesid. Since we
know the price of the product and the quantity we could also show the
product cost and the cost of each invoiceitem. Finally it would be
useful (or even essential for primary keys) if we could default some of
the values when the user adds a new record. 

\quotefile sql/overview/subclass2/main.h
\skipto InvoiceItem
\printline InvoiceItem
\printuntil };
\printline
\caption From \l sql/overview/subclass2/main.h

We have created a separate header file and subclassed QSqlCursor.

\quotefile sql/overview/subclass2/main.cpp
\skipto InvoiceItem
\printline InvoiceItem
\printuntil }
\caption From \l sql/overview/subclass2/main.cpp

In our class's constructor we call the QSqlCursor constructor with the
name of the table. We don't have any other characteristics to add at this
stage.

\skipto InvoiceItemCursor
\printline InvoiceItemCursor

Whenever we require a cursor over the invoiceitem table we can create an
InvoiceItemCursor instead of a generic QSqlCursor. 

We still need to show the product name rather than the pricesid.

\quotefile sql/overview/subclass3/main.h
\skipto protected
\printline protected
\printline
\caption From \l sql/overview/subclass3/main.h

The change in the header file is minimal: we simply add the signature of
the calculateField() function since we will be reimplementing it.

\quotefile sql/overview/subclass3/main.cpp
\skipto InvoiceItem
\printline InvoiceItem
\printuntil return QVariant
\printline
\caption From \l sql/overview/subclass3/main.cpp

We have changed the InvoiceItemCursor constructor. We now create a new
QSqlField called productname and append this to the InvoiceItemCursor's
set of fields. We call setCalculated() on productname to identify it as
a calculated field. The first argument to setCalculated() is the field
name, the second a bool which if TRUE signifies that calculateField()
must be called to get the field's value.

\skipto addColumn
\printline addColumn

We add our new fields with addColumn() which adds them to the form and
sets their display names.

We have to define our own calculateField() function. In our example
database the pricesid in the invoiceitem table is a foreign key into the
prices table. We find the name of the product by executing a query on
the prices table using the pricesid. This returns the product's name.

We are now able to extend the example to include calculated fields which
perform real calculations.

The header file, \l sql/overview/subclass4/main.h, remains unchanged
from the previous example, but the constructor and calculateField()
function require some simple expansion. We'll look at each in turn.

\quotefile sql/overview/subclass4/main.cpp
\skipto InvoiceItem
\printline InvoiceItem
\printuntil }
\caption From \l sql/overview/subclass4/main.cpp

We create two extra fields, price and cost, and append them to the
cursor's set of fields. Both are registered as calculated fields with
calls to setCalculated().

\skipto InvoiceItem
\printline InvoiceItem
\printuntil QString::null
\printline
\caption From \l sql/overview/subclass4/main.cpp

The calculateField() function has expanded slightly because now we must
calculate the value of three different fields. The productname and price
fields are produced by looking up the corresponding values in the prices
table keyed by pricesid. The cost field is calculated simply by
multiplying the price by the quantity. Note that we cast the cost to a
QVariant since that is the type that calculateField() must return.

We've written three separate queries rather than one to make the example
more like a real application where it is more likely that each
calculated field would be a lookup against a different table or view.

The last feature that we need to add is defaulting values when the user
attempts to insert a new record. 

\quotefile sql/overview/subclass5/main.h
\skipto primeInsert
\printline primeInsert
\caption From \l sql/overview/subclass5/main.h

We declare our own primeInsert() function since we will need to
reimplement this.

The constructor and the calculateField() function remain unchanged.

\quotefile sql/overview/subclass5/main.cpp
\skipto primeInsert
\printline primeInsert
\printuntil }
\caption From \l sql/overview/subclass5/main.cpp

We get a pointer to the internal edit buffer that the cursor uses for
inserts and updates. The id field is a unique integer that we generate
using the invoiceitem_seq. We default the value of the paiddate field to
today's date and default the quantity to 1. Finally we return a pointer
to the buffer. The rest of the code is unchanged from the previous
version.

\target Example_Tables
\section1 The Example Tables

The example tables used can be recreated with the following standard SQL.
You may need to modify the SQL to match that used by your particular
database. 

\code
create table people (id integer primary key, name char(40))

create table staff (id integer primary key, forename char(40),
		    surname char(40), salary float, statusid integer)

create table status (id integer primary key, name char(30))

create table creditors (id integer primary key, forename char(40),
			surname char(40), city char(30))

create table prices (id integer primary key, name char(40), price float)

create table invoiceitem (id integer primary key, 
			  pricesid integer, quantity integer,
			  paiddate date)
\endcode 

A sequence was used in the calculateField() example above.  Note that
sequences are not supported in all databases.

\code
create sequence invoiceitem_seq
\endcode

*/