Update copyright headers
[qt:qt.git] / doc / src / porting / qt4-sql.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     \page qt4-sql.html
30     \title The Qt 4 Database GUI Layer
31
32     \contentspage {What's New in Qt 4}{Home}
33     \previouspage Cross-Platform Accessibility Support in Qt 4
34     \nextpage The Network Module in Qt 4
35
36     The GUI layer of the SQL module in Qt 4 has been entirely
37     redesigned to work with \l{qt4-interview.html}{Interview} (Qt's
38     new model/view classes). It consists of three model classes
39     (QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel)
40     that can be used with Qt's view classes, notably QTableView.
41
42     \section1 General Overview
43
44     The Qt 4 SQL classes are divided into three layers:
45
46     \list
47     \o The database drivers
48     \o The core SQL classes
49     \o The GUI classes
50     \endlist
51
52     The database drivers and the core SQL classes are mostly the same
53     as in Qt 3. The database item models are new with Qt 4; they
54     inherit from QAbstractItemModel and make it easy to present data
55     from a database in a view class such as QListView, QTableView,
56     and QTreeView.
57
58     The philosophy behind the Qt 4 SQL module is that it should be
59     possible to use database models for rendering and editing data
60     just like any other item models. By changing the model at
61     run-time, you can decide whether you want to store your data in
62     an SQL database or in, say, an XML file. This generic approach
63     has the additional benefit that you don't need to know anything
64     about SQL to display and edit data.
65
66     The Qt 4 SQL module includes three item models:
67
68     \list
69     \o QSqlQueryModel is a read-only model based on an arbitrary
70        SQL query.
71     \o QSqlTableModel is a read-write model that works on a single
72        table.
73     \o QSqlRelationalTableModel is a QSqlTableModel subclass with
74        foreign key support.
75     \endlist
76
77     Combined with Qt's view classes and Qt's default delegate class
78     (QItemDelegate), the models offer a very powerful mechanism for
79     accessing databases. For finer control on the rendering of the
80     fields, you can subclass one of the predefined models, or even
81     QAbstractItemDelegate or QItemDelegate if you need finer control.
82
83     You can also perform some customizations without subclassing. For
84     example, you can sort a table using QSqlTableModel::sort(), and
85     you can initialize new rows by connecting to the
86     QSqlTableModel::primeInsert() signal.
87
88     One nice feature supported by the read-write models is the
89     possibility to perform changes to the item model without
90     affecting the database until QSqlTableModel::submitAll() is
91     called. Changes can be dropped using QSqlTableModel::revertAll().
92
93     The new classes perform advantageously compared to the SQL
94     module's GUI layer in Qt 3. Speed and memory improvements in the
95     tool classes (especially QVariant, QString, and QMap) and in the
96     SQL drivers contribute to making Qt 4 database applications more
97     snappy.
98
99     See the \l QtSql module overview for a more complete introduction
100     to Qt's SQL classes.
101
102     \section1 Example Code
103
104     The simplest way to present data from a database is to simply
105     combine a QSqlQueryModel with a QTableView:
106
107     \snippet doc/src/snippets/code/doc_src_qt4-sql.cpp 0
108
109     To present the contents of a single table, we can use
110     QSqlTableModel instead:
111
112     \snippet doc/src/snippets/code/doc_src_qt4-sql.cpp 1
113
114     In practice, it's common that we need to customize the rendering
115     of a field in the database. In that case, we can create our own
116     model based on QSqlQueryModel. The next code snippet shows a
117     custom model that prepends '#' to the value in field 0 and
118     converts the value in field 2 to uppercase:
119
120     \snippet examples/sql/querymodel/customsqlmodel.h 0
121     \codeline
122     \snippet examples/sql/querymodel/customsqlmodel.cpp 0
123
124     It is also possible to subclass QSqlQueryModel to add support for
125     editing. This is done by reimplementing
126     QAbstractItemModel::flags() to specify which database fields are
127     editable and QAbstractItemModel::setData() to modify the
128     database. Here's an example of a setData() reimplementation that
129     changes the first or last name of a person:
130
131     \snippet examples/sql/querymodel/editablesqlmodel.cpp 1
132
133     It relies on helper functions called \c setFirstName() and
134     \c setLastName(), which execute an \c{update}. Here's
135     \c setFirstName():
136
137     \snippet examples/sql/querymodel/editablesqlmodel.cpp 2
138
139     See Qt's \c examples/sql directory for more examples.
140
141     \section1 Comparison with Qt 3
142
143     The core SQL database classes haven't changed so much since Qt 3.
144     Here's a list of the main changes:
145
146     \list
147     \o QSqlDatabase is now value-based instead of pointer-based.
148     \o QSqlFieldInfo and QSqlRecordInfo has been merged into
149        QSqlField and QSqlRecord.
150     \o The SQL query generation has been moved into the drivers. This
151        makes it possible to use non-standard SQL extensions. It also
152        opens the door to non-SQL databases.
153     \endlist
154
155     The GUI-related database classes have been entirely redesigned.
156     The QSqlCursor abstraction has been replaced with QSqlQueryModel
157     and QSqlTableModel; QSqlEditorFactory is replaced by
158     QAbstractItemDelegate; QDataTable is replaced by QTableView. The
159     old classes are part of the \l{Qt3Support} library to aid
160     porting to Qt 4.
161 */