--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/cachedtable.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,211 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+ \example sql/cachedtable
+ \title Cached Table Example
+
+ The Cached Table example shows how a table view can be used to access a database,
+ caching any changes to the data until the user explicitly submits them using a
+ push button.
+
+ \image cachedtable-example.png
+
+ The example consists of a single class, \c TableEditor, which is a
+ custom dialog widget that allows the user to modify data stored in
+ a database. We will first review the class definiton and how to
+ use the class, then we will take a look at the implementation.
+
+ \section1 TableEditor Class Definition
+
+ The \c TableEditor class inherits QDialog making the table editor
+ widget a top-level dialog window.
+
+ \snippet examples/sql/cachedtable/tableeditor.h 0
+
+ The \c TableEditor constructor takes two arguments: The first is a
+ pointer to the parent widget and is passed on to the base class
+ constructor. The other is a reference to the database table the \c
+ TableEditor object will operate on.
+
+ Note the QSqlTableModel variable declaration: As we will see in
+ this example, the QSqlTableModel class can be used to provide data
+ to view classes such as QTableView. The QSqlTableModel class
+ provides an editable data model making it possible to read and
+ write database records from a single table. It is build on top of
+ the lower-level QSqlQuery class which provides means of executing
+ and manipulating SQL statements.
+
+ We are also going to show how a table view can be used to cache
+ any changes to the data until the user explicitly requests to
+ submit them. For that reason we need to declare a \c submit() slot
+ in additon to the model and the editor's buttons.
+
+ \table 100%
+ \header \o Connecting to a Database
+ \row
+ \o
+
+ Before we can use the \c TableEditor class, we must create a
+ connection to the database containing the table we want to edit:
+
+ \snippet examples/sql/cachedtable/main.cpp 0
+
+ The \c createConnection() function is a helper function provided
+ for convenience. It is defined in the \c connection.h file which
+ is located in the \c sql example directory (all the examples in
+ the \c sql directory use this function to connect to a database).
+
+ \snippet examples/sql/connection.h 0
+
+ The \c createConnection function opens a connection to an
+ in-memory SQLITE database and creates a test table. If you want
+ to use another database, simply modify this function's code.
+ \endtable
+
+ \section1 TableEditor Class Implementation
+
+ The class implementation consists of only two functions, the
+ constructor and the \c submit() slot. In the constructor we create
+ and customize the data model and the various window elements:
+
+ \snippet examples/sql/cachedtable/tableeditor.cpp 0
+
+ First we create the data model and set the SQL database table we
+ want the model to operate on. Note that the
+ QSqlTableModel::setTable() function does not select data from the
+ table; it only fetches its field information. For that reason we
+ call the QSqlTableModel::select() function later on, populating
+ the model with data from the table. The selection can be
+ customized by specifying filters and sort conditions (see the
+ QSqlTableModel class documentation for more details).
+
+ We also set the model's edit strategy. The edit strategy dictates
+ when the changes done by the user in the view, are actually
+ applied to the database. Since we want to cache the changes in the
+ table view (i.e. in the model) until the user explicitly submits
+ them, we choose the QSqlTableModel::OnManualSubmit strategy. The
+ alternatives are QSqlTableModel::OnFieldChange and
+ QSqlTableModel::OnRowChange.
+
+ Finally, we set up the labels displayed in the view header using
+ the \l {QSqlQueryModel::setHeaderData()}{setHeaderData()} function
+ that the model inherits from the QSqlQueryModel class.
+
+ \snippet examples/sql/cachedtable/tableeditor.cpp 1
+
+ Then we create a table view. The QTableView class provides a
+ default model/view implementation of a table view, i.e. it
+ implements a table view that displays items from a model. It also
+ allows the user to edit the items, storing the changes in the
+ model. To create a read only view, set the proper flag using the
+ \l {QAbstractItemView::editTriggers}{editTriggers} property the
+ view inherits from the QAbstractItemView class.
+
+ To make the view present our data, we pass our model to the view
+ using the \l {QAbstractItemView::setModel()}{setModel()} function.
+
+ \snippet examples/sql/cachedtable/tableeditor.cpp 2
+
+ The \c {TableEditor}'s buttons are regular QPushButton objects. We
+ add them to a button box to ensure that the buttons are presented
+ in a layout that is appropriate to the current widget style. The
+ rationale for this is that dialogs and message boxes typically
+ present buttons in a layout that conforms to the interface
+ guidelines for that platform. Invariably, different platforms have
+ different layouts for their dialogs. QDialogButtonBox allows a
+ developer to add buttons to it and will automatically use the
+ appropriate layout for the user's desktop environment.
+
+ Most buttons for a dialog follow certain roles. When adding a
+ button to a button box using the \l
+ {QDialogButtonBox}{addButton()} function, the button's role must
+ be specified using the QDialogButtonBox::ButtonRole
+ enum. Alternatively, QDialogButtonBox provides several standard
+ buttons (e.g. \gui OK, \gui Cancel, \gui Save) that you can
+ use. They exist as flags so you can OR them together in the
+ constructor.
+
+ \snippet examples/sql/cachedtable/tableeditor.cpp 3
+
+ We connect the \gui Quit button to the table editor's \l
+ {QWidget::close()}{close()} slot, and the \gui Submit button to
+ our private \c submit() slot. The latter slot will take care of
+ the data transactions. Finally, we connect the \gui Revert button
+ to our model's \l {QSqlTableModel::revertAll()}{revertAll()} slot,
+ reverting all pending changes (i.e., restoring the original data).
+
+ \snippet examples/sql/cachedtable/tableeditor.cpp 4
+
+ In the end we add the button box and the table view to a layout,
+ install the layout on the table editor widget, and set the
+ editor's window title.
+
+ \snippet examples/sql/cachedtable/tableeditor.cpp 5
+
+ The \c submit() slot is called whenever the users hit the \gui
+ Submit button to save their changes.
+
+ First, we begin a transaction on the database using the
+ QSqlDatabase::transaction() function. A database transaction is a
+ unit of interaction with a database management system or similar
+ system that is treated in a coherent and reliable way independent
+ of other transactions. A pointer to the used database can be
+ obtained using the QSqlTableModel::database() function.
+
+ Then, we try to submit all the pending changes, i.e. the model's
+ modified items. If no error occurs, we commit the transaction to
+ the database using the QSqlDatabase::commit() function (note that
+ on some databases, this function will not work if there is an
+ active QSqlQuery on the database). Otherwise we perform a rollback
+ of the transaction using the QSqlDatabase::rollback() function and
+ post a warning to the user.
+
+ \table 100%
+ \row
+ \o
+ \bold {See also:}
+
+ A complete list of Qt's SQL \l {Database Classes}, and the \l
+ {Model/View Programming} documentation.
+
+ \endtable
+*/