source: trunk/doc/src/porting/qt4-sql.qdoc@ 846

Last change on this file since 846 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

  • Property svn:eol-style set to native
File size: 6.3 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
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.qdoc 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.qdoc 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*/
Note: See TracBrowser for help on using the repository browser.