--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/porting/qt4-sql.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,175 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page qt4-sql.html
+ \title The Qt 4 Database GUI Layer
+
+ \contentspage {What's New in Qt 4}{Home}
+ \previouspage Cross-Platform Accessibility Support in Qt 4
+ \nextpage The Network Module in Qt 4
+
+ The GUI layer of the SQL module in Qt 4 has been entirely
+ redesigned to work with \l{qt4-interview.html}{Interview} (Qt's
+ new model/view classes). It consists of three model classes
+ (QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel)
+ that can be used with Qt's view classes, notably QTableView.
+
+ \section1 General Overview
+
+ The Qt 4 SQL classes are divided into three layers:
+
+ \list
+ \o The database drivers
+ \o The core SQL classes
+ \o The GUI classes
+ \endlist
+
+ The database drivers and the core SQL classes are mostly the same
+ as in Qt 3. The database item models are new with Qt 4; they
+ inherit from QAbstractItemModel and make it easy to present data
+ from a database in a view class such as QListView, QTableView,
+ and QTreeView.
+
+ The philosophy behind the Qt 4 SQL module is that it should be
+ possible to use database models for rendering and editing data
+ just like any other item models. By changing the model at
+ run-time, you can decide whether you want to store your data in
+ an SQL database or in, say, an XML file. This generic approach
+ has the additional benefit that you don't need to know anything
+ about SQL to display and edit data.
+
+ The Qt 4 SQL module includes three item models:
+
+ \list
+ \o QSqlQueryModel is a read-only model based on an arbitrary
+ SQL query.
+ \o QSqlTableModel is a read-write model that works on a single
+ table.
+ \o QSqlRelationalTableModel is a QSqlTableModel subclass with
+ foreign key support.
+ \endlist
+
+ Combined with Qt's view classes and Qt's default delegate class
+ (QItemDelegate), the models offer a very powerful mechanism for
+ accessing databases. For finer control on the rendering of the
+ fields, you can subclass one of the predefined models, or even
+ QAbstractItemDelegate or QItemDelegate if you need finer control.
+
+ You can also perform some customizations without subclassing. For
+ example, you can sort a table using QSqlTableModel::sort(), and
+ you can initialize new rows by connecting to the
+ QSqlTableModel::primeInsert() signal.
+
+ One nice feature supported by the read-write models is the
+ possibility to perform changes to the item model without
+ affecting the database until QSqlTableModel::submitAll() is
+ called. Changes can be dropped using QSqlTableModel::revertAll().
+
+ The new classes perform advantageously compared to the SQL
+ module's GUI layer in Qt 3. Speed and memory improvements in the
+ tool classes (especially QVariant, QString, and QMap) and in the
+ SQL drivers contribute to making Qt 4 database applications more
+ snappy.
+
+ See the \l QtSql module overview for a more complete introduction
+ to Qt's SQL classes.
+
+ \section1 Example Code
+
+ The simplest way to present data from a database is to simply
+ combine a QSqlQueryModel with a QTableView:
+
+ \snippet doc/src/snippets/code/doc_src_qt4-sql.qdoc 0
+
+ To present the contents of a single table, we can use
+ QSqlTableModel instead:
+
+ \snippet doc/src/snippets/code/doc_src_qt4-sql.qdoc 1
+
+ In practice, it's common that we need to customize the rendering
+ of a field in the database. In that case, we can create our own
+ model based on QSqlQueryModel. The next code snippet shows a
+ custom model that prepends '#' to the value in field 0 and
+ converts the value in field 2 to uppercase:
+
+ \snippet examples/sql/querymodel/customsqlmodel.h 0
+ \codeline
+ \snippet examples/sql/querymodel/customsqlmodel.cpp 0
+
+ It is also possible to subclass QSqlQueryModel to add support for
+ editing. This is done by reimplementing
+ QAbstractItemModel::flags() to specify which database fields are
+ editable and QAbstractItemModel::setData() to modify the
+ database. Here's an example of a setData() reimplementation that
+ changes the first or last name of a person:
+
+ \snippet examples/sql/querymodel/editablesqlmodel.cpp 1
+
+ It relies on helper functions called \c setFirstName() and
+ \c setLastName(), which execute an \c{update}. Here's
+ \c setFirstName():
+
+ \snippet examples/sql/querymodel/editablesqlmodel.cpp 2
+
+ See Qt's \c examples/sql directory for more examples.
+
+ \section1 Comparison with Qt 3
+
+ The core SQL database classes haven't changed so much since Qt 3.
+ Here's a list of the main changes:
+
+ \list
+ \o QSqlDatabase is now value-based instead of pointer-based.
+ \o QSqlFieldInfo and QSqlRecordInfo has been merged into
+ QSqlField and QSqlRecord.
+ \o The SQL query generation has been moved into the drivers. This
+ makes it possible to use non-standard SQL extensions. It also
+ opens the door to non-SQL databases.
+ \endlist
+
+ The GUI-related database classes have been entirely redesigned.
+ The QSqlCursor abstraction has been replaced with QSqlQueryModel
+ and QSqlTableModel; QSqlEditorFactory is replaced by
+ QAbstractItemDelegate; QDataTable is replaced by QTableView. The
+ old classes are part of the \l{Qt3Support} library to aid
+ porting to Qt 4.
+*/