doc/src/examples/cachedtable.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example sql/cachedtable
  30     \title Cached Table Example
  31
  32     \brief The Cached Table example shows how a table view can be used to access a database,
  33     caching any changes to the data until the user explicitly submits them using a
  34     push button.
  35
  36     \image cachedtable-example.png
  37
  38     The example consists of a single class, \c TableEditor, which is a
  39     custom dialog widget that allows the user to modify data stored in
  40     a database. We will first review the class definiton and how to
  41     use the class, then we will take a look at the implementation.
  42
  43     \section1 TableEditor Class Definition
  44
  45     The \c TableEditor class inherits QDialog making the table editor
  46     widget a top-level dialog window.
  47
  48     \snippet examples/sql/cachedtable/tableeditor.h 0
  49
  50     The \c TableEditor constructor takes two arguments: The first is a
  51     pointer to the parent widget and is passed on to the base class
  52     constructor. The other is a reference to the database table the \c
  53     TableEditor object will operate on.
  54
  55     Note the QSqlTableModel variable declaration: As we will see in
  56     this example, the QSqlTableModel class can be used to provide data
  57     to view classes such as QTableView. The QSqlTableModel class
  58     provides an editable data model making it possible to read and
  59     write database records from a single table. It is build on top of
  60     the lower-level QSqlQuery class which provides means of executing
  61     and manipulating SQL statements.
  62
  63     We are also going to show how a table view can be used to cache
  64     any changes to the data until the user explicitly requests to
  65     submit them. For that reason we need to declare a \c submit() slot
  66     in additon to the model and the editor's buttons.
  67
  68     \table 100%
  69     \header \o Connecting to a Database
  70     \row
  71     \o
  72
  73     Before we can use the \c TableEditor class, we must create a
  74     connection to the database containing the table we want to edit:
  75
  76     \snippet examples/sql/cachedtable/main.cpp 0
  77
  78     The \c createConnection() function is a helper function provided
  79     for convenience. It is defined in the \c connection.h file which
  80     is located in the \c sql example directory (all the examples in
  81     the \c sql directory use this function to connect to a database).
  82
  83     \snippet examples/sql/connection.h 0
  84
  85     The \c createConnection function opens a connection to an
  86     in-memory SQLITE database and creates a test table.  If you want
  87     to use another database, simply modify this function's code.
  88     \endtable
  89
  90     \section1 TableEditor Class Implementation
  91
  92     The class implementation consists of only two functions, the
  93     constructor and the \c submit() slot. In the constructor we create
  94     and customize the data model and the various window elements:
  95
  96     \snippet examples/sql/cachedtable/tableeditor.cpp 0
  97
  98     First we create the data model and set the SQL database table we
  99     want the model to operate on. Note that the
 100     QSqlTableModel::setTable() function does not select data from the
 101     table; it only fetches its field information. For that reason we
 102     call the QSqlTableModel::select() function later on, populating
 103     the model with data from the table. The selection can be
 104     customized by specifying filters and sort conditions (see the
 105     QSqlTableModel class documentation for more details).
 106
 107     We also set the model's edit strategy. The edit strategy dictates
 108     when the changes done by the user in the view, are actually
 109     applied to the database. Since we want to cache the changes in the
 110     table view (i.e. in the model) until the user explicitly submits
 111     them, we choose the QSqlTableModel::OnManualSubmit strategy. The
 112     alternatives are QSqlTableModel::OnFieldChange and
 113     QSqlTableModel::OnRowChange.
 114
 115     Finally, we set up the labels displayed in the view header using
 116     the \l {QSqlQueryModel::setHeaderData()}{setHeaderData()} function
 117     that the model inherits from the QSqlQueryModel class.
 118
 119     \snippet examples/sql/cachedtable/tableeditor.cpp 1
 120
 121     Then we create a table view. The QTableView class provides a
 122     default model/view implementation of a table view, i.e. it
 123     implements a table view that displays items from a model. It also
 124     allows the user to edit the items, storing the changes in the
 125     model. To create a read only view, set the proper flag using the
 126     \l {QAbstractItemView::editTriggers}{editTriggers} property the
 127     view inherits from the QAbstractItemView class.
 128
 129     To make the view present our data, we pass our model to the view
 130     using the \l {QAbstractItemView::setModel()}{setModel()} function.
 131
 132     \snippet examples/sql/cachedtable/tableeditor.cpp 2
 133
 134     The \c {TableEditor}'s buttons are regular QPushButton objects. We
 135     add them to a button box to ensure that the buttons are presented
 136     in a layout that is appropriate to the current widget style. The
 137     rationale for this is that dialogs and message boxes typically
 138     present buttons in a layout that conforms to the interface
 139     guidelines for that platform. Invariably, different platforms have
 140     different layouts for their dialogs. QDialogButtonBox allows a
 141     developer to add buttons to it and will automatically use the
 142     appropriate layout for the user's desktop environment.
 143
 144     Most buttons for a dialog follow certain roles. When adding a
 145     button to a button box using the \l
 146     {QDialogButtonBox}{addButton()} function, the button's role must
 147     be specified using the QDialogButtonBox::ButtonRole
 148     enum. Alternatively, QDialogButtonBox provides several standard
 149     buttons (e.g. \gui OK, \gui Cancel, \gui Save) that you can
 150     use. They exist as flags so you can OR them together in the
 151     constructor.
 152
 153     \snippet examples/sql/cachedtable/tableeditor.cpp 3
 154
 155     We connect the \gui Quit button to the table editor's \l
 156     {QWidget::close()}{close()} slot, and the \gui Submit button to
 157     our private \c submit() slot. The latter slot will take care of
 158     the data transactions. Finally, we connect the \gui Revert button
 159     to our model's \l {QSqlTableModel::revertAll()}{revertAll()} slot,
 160     reverting all pending changes (i.e., restoring the original data).
 161
 162     \snippet examples/sql/cachedtable/tableeditor.cpp 4
 163
 164     In the end we add the button box and the table view to a layout,
 165     install the layout on the table editor widget, and set the
 166     editor's window title.
 167
 168     \snippet examples/sql/cachedtable/tableeditor.cpp 5
 169
 170     The \c submit() slot is called whenever the users hit the \gui
 171     Submit button to save their changes.
 172
 173     First, we begin a transaction on the database using the
 174     QSqlDatabase::transaction() function. A database transaction is a
 175     unit of interaction with a database management system or similar
 176     system that is treated in a coherent and reliable way independent
 177     of other transactions. A pointer to the used database can be
 178     obtained using the QSqlTableModel::database() function.
 179
 180     Then, we try to submit all the pending changes, i.e. the model's
 181     modified items. If no error occurs, we commit the transaction to
 182     the database using the QSqlDatabase::commit() function (note that
 183     on some databases, this function will not work if there is an
 184     active QSqlQuery on the database). Otherwise we perform a rollback
 185     of the transaction using the QSqlDatabase::rollback() function and
 186     post a warning to the user.
 187
 188     \table 100%
 189     \row
 190     \o
 191     \bold {See also:}
 192
 193     A complete list of Qt's SQL \l {Database Classes}, and the \l
 194     {Model/View Programming} documentation.
 195
 196     \endtable
 197 */