Add Qt3 development HEAD version

1 files changed, 1351 insertions, 0 deletions

diff --git a/doc/sql.doc b/doc/sql.doc
new file mode 100644
index 0000000..5aa8266
--- /dev/null
+++ b/doc/sql.doc
@@ -0,0 +1,1351 @@
+/****************************************************************************
+**
+** Documentation for sql programming
+**
+** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be used under the terms of the GNU General
+** Public License versions 2.0 or 3.0 as published by the Free
+** Software Foundation and appearing in the files LICENSE.GPL2
+** and LICENSE.GPL3 included in the packaging of this file.
+** Alternatively you may (at your option) use any later version
+** of the GNU General Public License if such license has been
+** publicly approved by Trolltech ASA (or its successors, if any)
+** and the KDE Free Qt Foundation.
+**
+** Please review the following information to ensure GNU General
+** Public Licensing requirements will be met:
+** http://trolltech.com/products/qt/licenses/licensing/opensource/.
+** If you are unsure which license is appropriate for your use, please
+** review the following information:
+** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
+** or contact the sales department at [email protected].
+**
+** This file may be used under the terms of the Q Public License as
+** defined by Trolltech ASA and appearing in the file LICENSE.QPL
+** included in the packaging of this file.  Licensees holding valid Qt
+** Commercial 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 WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
+** herein.
+**
+**********************************************************************/
+/*! \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/delete/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
+
+\if defined(commercial)
+This module is part of the \link commercialeditions.html Qt Enterprise Edition
+\endlink.
+\endif
+
+\table
+\row
+\i \l QSql
+\i \l QSqlCursor
+\i \l QSqlDatabase
+\i \l QSqlDriver
+\i \l QSqlDriverPlugin
+\row
+\i \l QSqlEditorFactory
+\i \l QSqlError
+\i \l QSqlField
+\i \l QSqlFieldInfo
+\i \l QSqlForm
+\row
+\i \l QSqlIndex
+\i \l QSqlPropertyMap
+\i \l QSqlQuery
+\i \l QSqlRecord
+\i \l QSqlRecordInfo
+\row
+\i \l QSqlResult
+\i \l QSqlSelectCursor
+\i31 See also: \link sql-driver.html Supported Drivers\endlink
+\endtable
+
+\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 \link designer-manual.book Qt
+Designer\endlink 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
+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 simpler 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. \link designer-manual.book Qt
+Designer\endlink provides an easy visual way of achieving the same
+thing. See the \link designer-manual.book Qt Designer\endlink 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. 
+
+All the examples in this document use the tables defined in the
+\link #Example_Tables Example Tables\endlink section.
+
+\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. \link designer-manual.book Qt
+Designer\endlink 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, QSqlFieldInfo,
+QSqlIndex, QSqlRecord and QSqlRecordInfo.
+
+\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, includes Microsoft SQL Server support), QOCI8 (Oracle 8 and 9),
+QTDS7 (Sybase Adaptive Server), QPSQL7 (PostgreSQL 6 and 7),
+QMYSQL3 (MySQL), QDB2 (IBM DB2), QSQLITE (SQLite) and QIBASE (Interbase).
+Note that some of these drivers aren't included in the Qt Open Source Edition; see
+the \c 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 8 and 9) driver the TNS Service Name must be passed
+to setDatbaseName(). When connecting to ODBC data sources the Data
+Source Name (DSN) should be used in the setDatabaseName() call.
+
+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 obtained from \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.
+
+In the example below we have moved the connections into their own
+function, \c createConnections(), and added some basic error handling. 
+
+\code
+#define DB_SALES_DRIVER	    "QPSQL7"
+#define DB_SALES_DBNAME	    "sales"
+#define DB_SALES_USER	    "salesperson"
+#define DB_SALES_PASSWD	    "salesperson"
+#define DB_SALES_HOST	    "database.domain.no"
+
+#define DB_ORDERS_DRIVER    "QOCI8"
+#define DB_ORDERS_DBNAME    "orders"
+#define DB_ORDERS_USER	    "orderperson"
+#define DB_ORDERS_PASSWD    "orderperson"
+#define DB_ORDERS_HOST	    "database.domain.no"
+
+bool createConnections();
+\endcode
+
+We set up some constants and also declare the \c createConnections()
+function in \c connection.h.
+
+\quotefile sql/overview/connection.cpp
+\skipto #include
+\printuntil return TRUE
+\printuntil }
+\caption From \l sql/overview/connection.cpp
+
+We've chosen to isolate database connection in our \c
+createConnections() function.cpp.
+
+\target create_connections
+\quotefile sql/overview/create_connections/main.cpp
+\skipto include
+\printline include
+\printuntil return 0 
+\printline
+\caption From \l sql/overview/create_connections/main.cpp
+
+The static function \l QSqlDatabase::database() can be called from
+anywhere to provide a pointer to a database connection. If we call it
+without a 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 \link designer-manual.book Qt
+Designer\endlink, it will \e not include our example
+createConnections() function. This means that applications that
+preview correctly in \link designer-manual.book Qt Designer\endlink
+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.
+
+Note that this example and all the other examples in this document use
+the tables defined in the \link #Example_Tables Example Tables\endlink
+section.
+
+\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() and prev(). After any of these commands we
+can check that we are on a valid record 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(). Another
+approach is to create a \c VIEW which only presents the fields you're
+interested in; but note that some databases do not support editable
+views. So if you really don't want to retrieve all the 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.
+
+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 \c 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( "staff.surname LIKE 'A%'", nameIndex );
+\endcode
+
+We pass in a filter string (the \c WHERE clause), and the \l QSqlIndex
+object to sort by (the \c{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 that 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 \c 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 \c{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. 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 \link designer-manual.book Qt
+Designer\endlink 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 you
+need to move to another record after performing an insert(), update()
+or del() you 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/delete/main.cpp
+\skipto QSqlCursor
+\printline QSqlCursor
+\printuntil del
+\caption From \l sql/overview/delete/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 \link designer-manual.book Qt
+Designer\endlink. 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 \link
+designer-manual.book Qt Designer\endlink 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 \link
+designer-manual.book Qt Designer\endlink. See the \link
+designer-manual.book Qt Designer\endlink 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 using 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 detailed
+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
+\l{QLineEdit}s 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 a cursor's records. \l
+QDataView provides a read only form for data in a cursor or database
+record. See the class documentation or the \link designer-manual.book
+Qt Designer\endlink 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 Tables
+
+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 QDataTable
+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 };
+\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
+
+*/