199 lines
8.6 KiB
Plaintext
199 lines
8.6 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2016 The Qt Company Ltd.
|
|
** Contact: https://www.qt.io/licensing/
|
|
**
|
|
** This file is part of the documentation of the Qt Toolkit.
|
|
**
|
|
** $QT_BEGIN_LICENSE:FDL$
|
|
** Commercial License Usage
|
|
** Licensees holding valid commercial Qt licenses may use this file in
|
|
** accordance with the commercial license agreement provided with the
|
|
** Software or, alternatively, in accordance with the terms contained in
|
|
** a written agreement between you and The Qt Company. For licensing terms
|
|
** and conditions see https://www.qt.io/terms-conditions. For further
|
|
** information use the contact form at https://www.qt.io/contact-us.
|
|
**
|
|
** GNU Free Documentation License Usage
|
|
** Alternatively, this file may be used under the terms of the GNU Free
|
|
** Documentation License version 1.3 as published by the Free Software
|
|
** Foundation and appearing in the file included in the packaging of
|
|
** this file. Please review the following information to ensure
|
|
** the GNU Free Documentation License version 1.3 requirements
|
|
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\example cachedtable
|
|
\title Cached Table Example
|
|
\ingroup sql_examples
|
|
|
|
\brief 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.
|
|
|
|
\borderedimage 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 QWidget making the table editor
|
|
widget a top-level dialog window.
|
|
|
|
\snippet cachedtable/tableeditor.h 0
|
|
|
|
The \c TableEditor constructor takes two arguments: The first is a
|
|
reference to the database table the \c TableEditor object will operate
|
|
on. The other is a pointer to the parent widget and is passed on to the
|
|
base class constructor.
|
|
|
|
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 \li Connecting to a Database
|
|
\row
|
|
\li
|
|
|
|
Before we can use the \c TableEditor class, we must create a
|
|
connection to the database containing the table we want to edit:
|
|
|
|
\snippet 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 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 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 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 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. \uicontrol OK, \uicontrol Cancel, \uicontrol Save) that you can
|
|
use. They exist as flags so you can OR them together in the
|
|
constructor.
|
|
|
|
\snippet cachedtable/tableeditor.cpp 3
|
|
|
|
We connect the \uicontrol Quit button to the table editor's \l
|
|
{QWidget::close()}{close()} slot, and the \uicontrol Submit button to
|
|
our private \c submit() slot. The latter slot will take care of
|
|
the data transactions. Finally, we connect the \uicontrol Revert button
|
|
to our model's \l {QSqlTableModel::revertAll()}{revertAll()} slot,
|
|
reverting all pending changes (i.e., restoring the original data).
|
|
|
|
\snippet 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 cachedtable/tableeditor.cpp 5
|
|
|
|
The \c submit() slot is called whenever the users hit the \uicontrol
|
|
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
|
|
\li
|
|
\b {See also:}
|
|
|
|
A complete list of Qt's SQL \l {Database Classes}, and the \l
|
|
{Model/View Programming} documentation.
|
|
|
|
\endtable
|
|
*/
|