1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page porting4-overview.html
\title Moving from Qt 3 to Qt 4
\ingroup porting
\brief Porting advice for authors of new and existing Qt 3 applications.
This document describes which parts of Qt should be used when
writing an application with Qt 3, so that it can be upgraded to
use Qt 4 later with a minimum of effort. However, the advice may
also be useful to developers who are porting existing applications
from Qt 3 to Qt 4.
For a detailed overview
of the porting process for existing Qt 3 applications, see the
\l{Porting to Qt 4} document.
\tableofcontents
Since Qt 4 provides important new functionality at the cost of
some compatibility with Qt 3, it is useful for developers of
Qt 3-based applications to learn how to take advantage of
Qt 3's API now while preparing for future changes that will be
needed when upgrading to Qt 4.
Certain advanced Qt 3 features were moved to the Qt 3 support
library (\l{Qt3Support}) in Qt 4.0, and have been gradually
replaced in subsequent releases of Qt 4.
Making Qt 3 applications as portable to Qt 4 as possible
enables a smooth transition between versions of Qt in the
long term, and allows for a stable development process
throughout.
\section1 Qt 3 Features to Avoid
Although we are proud of the level of stability we have achieved
with Qt, it is important to realise that, for Qt 4 to be a
substantial improvement over Qt 3, certain features have
been revised to make the framework more maintainable for us
and more usable for developers. It is therefore useful to
know which features of Qt 3 should be avoided to help save
time during a later porting effort to Qt 4. Note that it is
still possible to use many of the following classes and
features through the use of the \l{Qt3Support} module.
\section2 Painting Outside Paint Events
In Qt 3, under certain circumstances, it was possible to use
QPainter to draw on a given custom widget outside its
\l{QWidget::}{paintEvent()} reimplementation. In Qt 4, in most
situations, painting must occur within a widget's paint event
handler.
On X11, it is possible to set the \l{Qt::WA_PaintOutsidePaintEvent}
attribute on widgets to keep existing code, but we recommend
restricting the use of painting code to within paint event handlers
where possible.
More information about this change can be found in the
\l{Porting to Qt 4#Painting and Redrawing Widgets}{Painting and Redrawing Widgets}
section of the \l{Porting to Qt 4} document.
\section2 Qt Designer
The version of Qt Designer supplied with Qt 3 provided
extensive code editing and project management features
(control over \c{.ui.h} and \c{.pro} files), and encouraged
users to design main window applications from within the
Qt Designer environment.
The version of Qt Designer supplied with Qt 4 is intended
to be integrated with other software development tools (such
as integrated development environments), and does not
support these project-level features.
We recommend using one of the
\l{Using a Designer UI File in Your Application}{form subclassing approaches}
with forms created using Qt Designer. This avoids the need
to use \c{.ui.h} files and special purpose code editors.
Existing Qt 3 forms created using Qt Designer can be gradually
ported to Qt 4 by following the advice in the
\l{Porting UI Files to Qt 4} guide. However, some extra effort
will be required to move application logic from \c{.ui.h} files
into the main body of a Qt 4 application.
\section2 Menu Items (QMenuItem)
The old-style construction of menus by creating individual
menu items has been superseded in Qt 4 by the use of
generic actions which can be used in menus, toolbars, and
as keyboard shortcuts.
Qt 3 also supports this action-based approach, so, by using
QAction throughout your application, less work will be
required to adapt your application to Qt 4.
\section2 Pointer-Based Classes (QPtr*)
Qt 3 provides a group of pointer-based classes (\c QPtrList,
\c QPtrDict, \c QPtrVector, etc.) that help manage collections
of pointers to objects (usually QObject subclasses) in an
application. In addition, the value-based collection classes
(\c QValueList, \c QValueDict, \c QValueVector, etc.) provide
a way to store standard value types which cannot be easily stored
in pointer-based collections.
Qt 4 introduces a single set of collection classes which
does not require developers to pay as much attention to
memory allocation and object ownership issues. As a result,
Qt 3's pointer-based classes have no direct equivalent
classes in Qt 4.
To ease migration, use Qt 3's value-based classes to store
most objects, including pointers; for example, use
\c QValueVector<QWidget *> rather than
\c QPtrVector<QWidget *>. These can be replaced by
Qt 4's QVector, QLinkedList, and QList later.
\section2 Other Collection Classes (QStrList, Q*Dict)
Some collection classes in Qt 3 have been deprecated in
favor of easier to use, higher level alternatives. These
include the dictionary classes (\c QAsciiDict, \c QDict,
\c QIntDict, \c QPtrDict) and \c QStrList.
\c QStrList can usually replaced by the higher level QStringList
class in Qt 3; this is also available in Qt 4. It is
recommended that you use the QMap class instead of the \c QDict
classes. In Qt 4, QMap is also complemented by the QHash
class.
\section2 Memory Arrays (QMemArray)
In Qt 3, the \c QMemArray class is used as a simple array
container for simple data types. This class is deprecated in
Qt 4 in favor of the QVector and QVarLengthVector classes
which provide more powerful and consistent array objects.
Qt 3's closest equivalent class to Qt 4's QVector is the
\c QValueVector class. For many purposes, this can be used
instead of \c QMemArray.
\section2 URL Operations (QUrlOperator)
The URL operator in Qt 3 provides an abstract way to
handle files via HTTP, FTP, and on the local file system.
However, Qt 4 only provides this functionality through the
use of the Q3UrlOperator.
From Qt 4.4, the Network Access API provides a subset of the features
provided by \c QUrlOperator that are mostly intended for use with
applications that use the HTTP and FTP protocols. See the
QNetworkRequest, QNetworkReply, and QNetworkAccessManager documentation
for further details.
It is also possible to perform operations on remote files through
the QNetworkAccessManager and QFtp classes, and on local files
with the QFile class.
\section2 SQL Cursors (QSqlCursor)
In Qt 3, one of the preferred methods of working with SQL
is to use a cursor to manipulate the contents of a database.
In Qt 4, the preferred method of working with SQL is to use
the model/view architecture (QSqlQueryModel and QSqlTableModel)
and, as a result, the cursor interface is only supplied in the
Q3SqlCursor class.
The easiest way to ensure continuity between Qt 3 and Qt 4
is to use QSqlQuery rather than \c QSqlCursor,
and migrate to QSqlQueryModel later.
\section2 Domain Name Service (QDns)
The QDns class in Qt 4 provides a much simpler interface
than the QDns class in Qt 3, and is mainly used for host
name resolution.
As a result, many of the more complex features of Qt 3's
QDns class are only available through Qt 4's Q3Dns
compatibility class.
To resolve host names with Qt 3, it is recommended that you
use the higher level interface of QSocket rather than QDns.
The equivalent functionality is available in Qt 4 in the
QAbstractSocket and QHostInfo classes.
\section2 Wizard Dialogs (QWizard)
Qt 3 provides support for "wizard" dialogs in the form of
the \c QWizard class. Prior to Qt 4.3, this class was made
available as Q3Wizard, and provides the same interface for
creating relatively complex wizards.
In Qt 4.3 and later, a revised QWizard class can be used to
create this kind of dialog, but existing Qt 3 wizard
implementations may need to be redesigned to work with the
new QWizard API.
\section2 Abstract Grid Views (QGridView)
Before the introduction of the Qt 3 \c QTable class,
\c QGridView was the recommended way to create tables of
custom items.
With the introduction of \c QTable, the \c QGridView class was
effectively obsoleted, and the \c QTable class should now be
used to display tabular information in your Qt 3 application.
This approach allows you to use QTableWidget as a replacement
when later porting your application to Qt 4.
\section2 Specialized Scrolling Views
In Qt 3, the \c QScrollView class provides a viewport that can
be used to display part of a larger widget, and will
optionally provide scroll bars for navigation purposes.
In Qt 4, this functionality is superseded by classes such as
QScrollArea, which provides a more intuitive interface for
developers to use.
\c QScrollView is available in Qt 4 as the Q3ScrollView class.
In Qt 3, it is recommended that \c QScrollView should be
used with child widgets rather than subclassed. However, it
should be noted that this approach may not be appropriate if
you need to use extremely large scrolling areas in your
application, since Qt 3 widgets cannot be wider or taller
than 32767 pixels.
\section1 Significantly Changed Features
Some Qt 3 features have changed significantly for Qt 4.
and the recommended way of using them has therefore changed
significantly, too. This is most notably true for the drag
and drop API.
Additionally, some of the more specialized features in Qt 3 are
often used to help customize widgets and add extra polish to an
application.
Although these improvements make applications more presentable to
users, many of them are unnecessary with Qt 4, and may create
additional porting work.
\section2 Drag and Drop
Qt 4 introduces a simpler and more intuitive implementation
of drag and drop between widgets, and with other applications.
As a result, there is no simple approach that can be used to
make drag and drop in a Qt 3 application easier to port to
Qt 4.
\section2 Extensive Customization of Item Views
Each of the classes that are used to display list, tree,
and table items in Qt 3 can be subclassed for the purposes
of customizing their appearance. The item view framework
in Qt 4 is implemented according to a different paradigm
(model/view) which does not allow items to be customized
using this method.
Although Qt 4 provides compatibility classes (Q3ListBoxItem,
Q3ListViewItem, and Q3TableItem) that can be used in the same
way as their Qt 3 counterparts, these cannot be used within
the standard model/view framework. It is recommended that,
to minimize porting effort, extensive customization of item
classes should be avoided in Qt 3, if at all possible.
\section2 Double Buffering
Qt 3 applications often use double buffering for reducing
flicker when painting custom widgets. This approach is
unnecessary with Qt 4 because double buffering is
automatically performed by the paint engine.
\section2 Data-Aware Forms
The \c QDataTable, \c QDataBrowser, and \c QDataView classes
in Qt 3 allow integration between widgets and SQL-based
databases.
In Qt 4.1 and earlier, the preferred way to create a data-aware
widget is to connect an generic item view (such as a table view)
to a SQL model. In Qt 4.2 and later, the QDataWidgetMapper class
can be used to map data to widgets in a form-based user interface.
New applications written with Qt 3 should use QSqlQuery in
preference to an approach based on the old-style data-aware
widgets.
This offers a choice of porting strategies when later migrating
the application to Qt 4: You can either continue to use
QSqlQuery or take the opportunity to use the model/view
classes to handle database integration.
\section2 Dock Windows and Areas
In Qt 4, the way that dock windows are constructed and used
in main window applications differs significantly to the
pattern of use provided by Qt 3. As a result, the introduction
of a simpler and cleaner API means that Qt 3 applications that
make extensive use of dock window areas will require careful
examination when they are ported to Qt 4.
We recommend that the QMainWindow class be used in preference
to the Q3MainWindow compatibility class when an existing Qt 3
main window application is ported to Qt 4. Therefore, we
recommend that specialized use of dock window areas should
be avoided when writing a Qt 3 application with Qt 4 in mind.
\section2 Custom Styles
The style system used to provide consistent themes for Qt's
standard widgets has been revised for Qt 4. As a result,
custom styles for Qt 3 require some porting work to be done
before they can be used with Qt 4. To ease the porting process,
we recommend that you avoid implementing custom widget styles
for Qt 3 applications unless it is absolutely necessary for
your users.
In Qt 4.2 and later, \l{Qt Style Sheets} can be used to
implement many common modifications to existing styles, and
this may be sufficient for Qt 3 applications.
\section2 Events
In Qt 3, QCloseEvents were not accepted by default. In Qt 4,
the event handler QWidget::closeEvent() receives QCloseEvents,
and accepts them by default closing the application. To avoid
this, please reimplement QWidget::closeEvent().
*/
|