Long live Qt for S60!

1 files changed, 175 insertions, 0 deletions

diff --git a/doc/src/qt4-sql.qdoc b/doc/src/qt4-sql.qdoc
new file mode 100644
index 0000000..cb94f54
--- /dev/null
+++ b/doc/src/qt4-sql.qdoc
@@ -0,0 +1,175 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@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.
+*/