source: trunk/doc/src/porting/porting4.qdoc

Last change on this file 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: 165.2 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation (qt-info@nokia.com)
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 qt-info@nokia.com.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \group porting
30 \title Porting Guides
31 \brief Guides related to porting Qt applications and libraries.
32 \ingroup best-practices
33
34 A number of guides and documents are available that cover porting issues,
35 from detailed coverage of API differences between Qt 3 and Qt 4 to
36 platform and tool-specific documentation.
37
38 \generatelist{related}
39*/
40
41/*!
42 \page porting4.html
43 \title Porting to Qt 4
44 \contentspage {Porting Guides}{Contents}
45 \previouspage Porting Guides
46 \nextpage Porting to Qt 4 - Virtual Functions
47 \ingroup porting
48 \brief An overview of issues and techniques to consider when porting from Qt 3 to Qt 4.
49
50\omit
51 ### QFileInfo::PermissionSpec -> QFile::Permission(s?)
52 ### refer to porting4-renamedfunctions.qdoc
53 ### QApplication library mutex is gone
54 ### no integral conversion for containers? strings?
55 ### QVector etc. are initialized to 0 by default?
56 ### How to port from Qt 2.3 to Qt 4.
57 ### missing sort() functions?
58 ### QToolTipGroup
59 ### QServerSocket -> Q3ServerSocket
60
61 ### remove these when the classes are re-ported
62
63 ### QApplication::eventLoop()
64
65 \row \o void QCheckListItem::paintCell(QPainter *, const QColorGroup &, int, int, int)\row \o void Q3CheckListItem::paintCell(QPainter *, const QPalette &, int, int, int)
66 \row \o void QCheckListItem::paintFocus(QPainter *, const QColorGroup &, const QRect &) \o void Q3CheckListItem::paintFocus(QPainter *, const QPalette &, const QRect &)
67 \row \o QDataTable: a whole bunch of virtual functions have a different signature
68
69 < Function: void QIconViewItem::paintFocus(QPainter *, const QColorGroup &)
70 > Function: void QIconViewItem::paintFocus(QPainter *, const QPalette &)
71
72 < Function: void QIconViewItem::paintItem(QPainter *, const QColorGroup &)
73 > Function: void QIconViewItem::paintItem(QPainter *, const QPalette &)
74
75 < Function: bool QUrlOperator::checkValid()
76
77 < Function: void QWSInputMethod::setFont(const QFont &)
78
79 ### OpenMode or OpenMode
80
81 ### QWSDecoration
82\endomit
83
84 This document describes the process of porting applications from
85 Qt 3 to Qt 4.
86 If you haven't yet made the decision about porting, or are unsure
87 about whether it is worth it, take a look at the \l{What's New in
88 Qt 4}{key features} offered by Qt 4. See also
89 \l{Moving from Qt 3 to Qt 4} for tips on how to write Qt 3 code
90 that is easy to port to Qt 4.
91
92 \bold{Other porting guides:}
93
94 \list
95 \o \l{Moving from Qt 3 to Qt 4} \mdash covers some high level topics relevant
96 to developers porting from Qt 3 to Qt 4.
97 \o \l{Porting to Qt 4 - Drag and Drop} \mdash covers differences in the
98 way drag and drop is handled between Qt 3 and Qt 4.
99 \o \l{Porting UI Files to Qt 4} \mdash describes the new format used to
100 describe forms created with \QD.
101 \o \l{Porting to Graphics View} \mdash provides a class-by-class overview
102 of the differences between Qt 3's canvas API and Qt 4's Graphics
103 View framework.
104 \o \l{qt3to4 - The Qt 3 to 4 Porting Tool} \mdash provides an overview
105 of a tool aimed at helping developers start the process of porting an
106 application to Qt 4.
107 \endlist
108
109 The Qt 4 series is not binary compatible with the 3 series. This
110 means programs compiled for Qt 3 must be recompiled to work with
111 Qt 4. Qt 4 is also not completely \e source compatible with 3,
112 however nearly all points of incompatibility cause compiler
113 errors or run-time messages (rather than mysterious results). Qt
114 4 includes many additional features and discards obsolete
115 functionality. Porting from Qt 3 to Qt 4 requires some effort,
116 but once completed the considerable additional power and
117 flexibility of Qt 4 is available for use in your applications.
118
119 To port code from Qt 3 to Qt 4:
120
121 \list 1
122
123 \o Briefly read the porting notes below to get an idea of what to expect.
124
125 \o Be sure that your code compiles and runs well on all your target
126 platforms with Qt 3.
127
128 \o Add the line \c{QT += qt3support} to your \c .pro file if you use
129 \c qmake; otherwise, edit your makefile or project file to
130 link against the Qt3Support library and add \c -DQT3_SUPPORT to your
131 compiler flags. (You might also need to specify other
132 libraries. See \l{What's New in Qt 4} for details.)
133
134 \o Run the \l qt3to4 porting tool. The tool will go through your
135 source code and adapt it to Qt 4.
136
137 \o Follow the instructions in the \l{Porting UI Files to Qt 4}
138 page to port Qt Designer files.
139
140 \o Recompile with Qt 4. For each error, search below for related
141 identifiers (e.g., function names, class names). This document
142 mentions all relevant identifiers to help you get the information
143 you need at the cost of being a little verbose.
144
145 \endlist
146
147 The \l qt3to4 porting tool replaces occurrences of Qt 3 classes
148 that don't exist anymore in Qt 4 with the corresponding Qt 3
149 support class; for example, \c QListBox is turned into \c
150 Q3ListBox.
151
152 At some point, you might want to stop linking against the Qt 3
153 support library (\l{Qt3Support}) and take advantage of Qt 4's
154 new features. The instructions below explain how to do that for
155 each compatibility class.
156
157 In addition to the Qt3Support classes (such as \c Q3Action, \c
158 Q3ListBox, and \c Q3ValueList), Qt 4 provides compatibility
159 functions when it's possible for an old API to cohabit with the
160 new one. For example, QString provides a
161 QString::simplifyWhiteSpace() compatibility function that's
162 implemented inline and that simply calls QString::simplified().
163 \bold{The compatibility functions are not documented here; instead,
164 they are documented for each class.}
165
166 If you have the line \c{QT += qt3support} in your \c .pro file, \c
167 qmake will automatically define the \c QT3_SUPPORT symbol, turning
168 on compatibility function support. You can also define the symbol
169 manually (e.g., if you don't want to link against the \c
170 Qt3Support library), or you can define \c QT3_SUPPORT_WARNINGS
171 instead, telling the compiler to emit a warning when a
172 compatibility function is called. (This works only with GCC 3.2+
173 and MSVC 7.)
174
175 If you get stuck, ask on the
176 \l{http://qt.nokia.com/lists/qt-interest/}{qt-interest}
177 mailing list. If you are a licensed customer, you can also contact
178 Qt's technical support team.
179
180\omit
181 ### what to do with slots that aren't slots anymore
182 ### what to do with virtual functions that aren't virtual anymore
183 ### what to do with virtual functions that changed signature
184\endomit
185
186\omit
187 ### <qtl.h> -- stuff that vanished?
188 ### implicit sharing
189 ### uint -> int indexes
190\endomit
191
192 Table of contents:
193
194 \tableofcontents{4}
195
196\omit
197 \section1 Header Files
198
199 ### New style of headers
200
201 \table
202 \header \o Old header \o New header
203 \row \o \c{<qtl.h>} \o \c{<qalgorithms.h>} or \c{<QtAlgorithms>}
204 \endtable
205
206 ### Some headers don't include each other anymore...
207\endomit
208
209 \section1 Casting and Object Types
210
211 In Qt 3, it was possible to use the \c qt_cast() function to determine
212 whether instances of QObject subclasses could be safely cast to derived
213 types of those subclasses. For example, if a QFrame instance is passed
214 to a function whose signature specifies a QWidget pointer as its argument,
215 \c qt_cast() could be used to obtain a QFrame pointer so that the
216 instance's functions can be accessed.
217
218 In Qt 4, much of this functionality is provided by the qobject_cast()
219 function, and additional functions also provide similar functionality for
220 certain non-QObject types:
221
222 \table
223 \header \o Qt 3 function \o Qt 4 function
224 \row \o T *qt_cast<T *>(QObject *) \o \l{qobject_cast()}{T *qobject_cast<T *>(QObject *)}
225 \row \o \o \l{qgraphicsitem_cast()}{T qgraphicsitem_cast<T>(QGraphicsItem *)}
226 \row \o \o \l{qstyleoption_cast()}{T qstyleoption_cast<T>(QStyleOption *)}
227 \row \o \o \l{qvariant_cast()}{T qvariant_cast<T>(const QVariant &)}
228 \row \o \o \l{qdbus_cast()}{T qdbus_cast(const QDBusArgument &)}
229 \endtable
230
231\omit
232 \section1 Global Functions
233
234 \table
235 \header \o Qt 3 function \o Qt 4 function
236 \row \o cstrcmp() \o strcmp()
237 \row \o cstrcpy() \o strcpy()
238 \row \o cstrlen() \o strlen()
239 \row \o cstrncmp() \o strncmp()
240 \row \o qmemmove() \o memmove()
241 \endtable
242
243 qGLVersion() ###
244
245 copyBlt() ###
246 bitBlt()
247
248 #ifdef compat classes:
249 * QLayoutIterator
250 * QColorGroup
251 * QMenuItem
252
253 QWidget visibleRect property compat
254 QWidget::BackgroundOrigin compat
255\endomit
256
257 \section1 Type Names
258
259 The table below lists the classes that have been renamed in Qt 4.
260 If you compile your applications with \c QT3_SUPPORT defined, the
261 old names will be available.
262
263 Whenever you see an occurrence of the name on the left, you can
264 safely replace it with the Qt 4 equivalent in your program. The
265 \l qt3to4 tool performs the conversion automatically.
266
267 \table
268 \header \o Qt 3 class name \o Qt 4 class name
269 \input porting/porting4-renamedclasses.qdocinc
270 \endtable
271
272 The table below lists the enums and typedefs that have been
273 renamed in Qt 4. If you compile your applications with \c
274 QT3_SUPPORT defined, the old names will be available.
275
276 Whenever you see an occurrence of the name on the left, you can
277 safely replace it with the Qt 4 equivalent in your program. The
278 \l qt3to4 tool performs the conversion
279 automatically.
280
281 \table
282 \header \o Qt 3 type name \o Qt 4 type name
283 \input porting/porting4-renamedtypes.qdocinc
284 \endtable
285
286 \omit
287 ###
288 \row \o QButton::ToggleState \o Use QCheckBox::ToggleState instead.
289 \endomit
290
291 \section1 Enum Values
292
293 The table below lists the enum values that have been renamed in
294 Qt 4. If you compile your applications with \c QT3_SUPPORT defined,
295 the old names will be available.
296
297 Whenever you see an occurrence of the name on the left, you can
298 safely replace it with the Qt 4 equivalent in your program. The
299 \l qt3to4 tool performs the conversion automatically.
300
301 \table
302 \header \o Qt 3 enum value name \o Qt 4 enum value name
303 \input porting/porting4-renamedenumvalues.qdocinc
304 \endtable
305
306 In addition, the following \l{Qt::WindowFlags}{window flags} have
307 been either replaced with \l{Qt::WidgetAttribute}{widget
308 attributes} or have been deprecated:
309
310 \table
311 \header \o Qt 3 type \o Qt 4 equivalent
312 \row \o Qt::WDestructiveClose \o Use QWidget::setAttribute(Qt::WA_DeleteOnClose) instead.
313 \row \o Qt::WStaticContents \o{1,2} Use QWidget::setAttribute(Qt::WA_StaticContents) instead.
314 \row \o Qt::WNorthWestGravity
315 \row \o Qt::WNoAutoErase \o{1,3} Use QWidget::setAttribute(Qt::WA_NoBackground) instead.
316 \row \o Qt::WResizeNoErase
317 \row \o Qt::WRepaintNoErase
318 \row \o Qt::WPaintClever \o Unnecessary in Qt 4.
319 \omit ### Check with Matthias \endomit
320 \row \o Qt::WMacNoSheet \o Unnecessary in Qt 4.
321 \omit ### Check with Sam \endomit
322 \endtable
323
324 In Qt 4.1, the widget flags used to determine window modality were
325 replaced by a single enum that can be used to specify the modal
326 behavior of top-level widgets:
327
328 \table
329 \header \o Qt 3 type \o Qt 4 equivalent
330 \row \o Qt::WShowModal \o Use QWidget::setWindowModality(Qt::ApplicationModal) instead.
331 \row \o Qt::WGroupLeader \o Use QWidget::setWindowModality(Qt::WindowModal)
332 for each child dialog of the group leader, but do not change the modality
333 of the group leader itself.
334 \endtable
335
336 \target properties
337 \section1 Properties
338
339 Some properties have been renamed in Qt 4, to make Qt's API more
340 consistent and more intuitive. For example, QWidget's \c caption
341 property has been renamed \c windowTitle to make it clear that it
342 refers to the title shown in the window's title bar.
343
344 In addition, the property system has been extended to allow
345 properties to be redefined in subclasses with the \l Q_PROPERTY()
346 macro, removing the need for a \c Q_OVERRIDE() macro.
347
348 The table below lists the Qt properties that have been renamed in
349 Qt 4. Occurrences of these in \e{Qt Designer} UI files are
350 automatically converted to the new name by \c uic.
351
352 \table
353 \header \o Qt 3 name \o Qt 4 name
354 \row \o QButton::accel \o QButton::shortcut
355 \row \o QButton::on \o QButton::checked
356 \row \o QButton::toggleButton \o QAbstractButton::checkable
357 \row \o QDial::lineStep \o QDial::singleStep
358 \row \o QDial::maxValue \o QDial::maximum
359 \row \o QDial::minValue \o QDial::minimum
360 \row \o QDialog::modal \o QDialog::isModal
361 \row \o QLineEdit::edited \o QLineEdit::modified
362 \row \o QLineEdit::hasMarkedText \o QLineEdit::hasSelectedText
363 \row \o QLineEdit::markedText \o QLineEdit::selectedText
364 \row \o QObject::name \o QObject::objectName
365 \row \o QProgressDialog::progress \o QProgressDialog::value
366 \row \o QProgressDialog::totalSteps \o QProgressDialog::maximum
367 \row \o QProgressDialog::wasCancelled \o QProgressDialog::wasCanceled
368 \row \o QPushButton::iconSet \o QPushButton::icon
369 \row \o QScrollBar::draggingSlider \o QScrollBar::sliderDown
370 \row \o QScrollBar::lineStep \o QScrollBar::singleStep
371 \row \o QScrollBar::maxValue \o QScrollBar::maximum
372 \row \o QScrollBar::minValue \o QScrollBar::minimum
373 \row \o QSlider::lineStep \o QSlider::singleStep
374 \row \o QSlider::maxValue \o QSlider::maximum
375 \row \o QSlider::minValue \o QSlider::minimum
376 \row \o QSpinBox::lineStep \o QSpinBox::singleStep
377 \row \o QSpinBox::maxValue \o QSpinBox::maximum
378 \row \o QSpinBox::minValue \o QSpinBox::minimum
379 \row \o QTabBar::currentTab \o QTabBar::currentIndex
380 \row \o QTabWidget::currentPage \o QTabWidget::currentWidget
381 \row \o QToolButton::iconSet \o QToolButton::icon
382 \row \o QToolButton::textLabel \o QToolButton::text
383 \row \o QWidget::caption \o QWidget::windowTitle
384 \row \o QWidget::icon \o QWidget::windowIcon
385 \row \o QWidget::iconText \o QWidget::windowIconText
386 \endtable
387
388 A handful of properties in Qt 3 are no longer properties in Qt 4,
389 but the access functions still exist as part of the Qt 4 API.
390 These are not used by \e{Qt Designer}; the only case where you
391 need to worry about them is in highly dynamic applications that
392 use Qt's meta-object system to access properties. Here's the list
393 of these properties with the read and write functions that you
394 can use instead:
395
396 \table
397 \header \o Qt 3 property \o Qt 4 read function \o Qt 4 write function
398 \row \o QSqlDatabase::connectOptions \o QSqlDatabase::connectOptions() \o QSqlDatabase::setConnectOptions()
399 \row \o QSqlDatabase::databaseName \o QSqlDatabase::databaseName() \o QSqlDatabase::setDatabaseName()
400 \row \o QSqlDatabase::hostName \o QSqlDatabase::hostName() \o QSqlDatabase::setHostName()
401 \row \o QSqlDatabase::password \o QSqlDatabase::password() \o QSqlDatabase::setPassword()
402 \row \o QSqlDatabase::port \o QSqlDatabase::port() \o QSqlDatabase::setPort()
403 \row \o QSqlDatabase::userName \o QSqlDatabase::userName() \o QSqlDatabase::setUserName()
404 \endtable
405
406 Some properties have been removed from Qt 4, but the associated
407 access functions are provided if \c QT3_SUPPORT is defined to help
408 porting to Qt 4. When converting Qt 3 UI files to Qt 4, \c uic
409 generates calls to the Qt 3 compatibility functions. Note that
410 this only applies to the properties of the Qt3Support library,
411 i.e. \c QT3_SUPPORT properties of the other libraries must be
412 ported manually when converting Qt 3 UI files to Qt 4.
413
414 The table below lists these properties with the read and write
415 functions that you can use instead. The documentation for the
416 individual functions explains how to replace them with
417 non-compatibility Qt 4 functions.
418
419 \table
420 \header \o Qt 3 property \o Qt 4 read function (\c QT3_SUPPORT)\o Qt 4 write function (\c QT3_SUPPORT)
421 \row \o QMenuBar::separator \o QMenuBar::separator() \o QMenuBar::setSeparator()
422 \row \o QPushButton::menuButton \o QPushButton::isMenuButton() \o N/A
423 \row \o QTabWidget::margin \o QTabWidget::margin() \o QTabWidget::setMargin()
424 \row \o QTextEdit::textFormat \o QTextEdit::textFormat() \o QTextEdit::setTextFormat()
425 \row \o QWidget::backgroundBrush \o QWidget::backgroundBrush() \o N/A
426 \row \o QWidget::backgroundMode \o QWidget::backgroundMode() \o QWidget::setBackgroundMode()
427 \row \o QWidget::backgroundOrigin \o QWidget::backgroundOrigin() \o QWidget::setBackgroundOrigin()
428 \row \o QWidget::colorGroup \o QWidget::colorGroup() \o QWidget::setColorGroup()
429 \row \o QWidget::customWhatsThis \o QWidget::customWhatsThis() \o QWidget::setCustomWhatsThis()
430 \row \o QWidget::inputMethodEnabled \o QWidget::inputMethodEnabled() \o QWidget::setInputMethodEnabled()
431 \row \o QWidget::ownCursor \o QWidget::ownCursor() \o N/A
432 \row \o QWidget::ownFont \o QWidget::ownFont() \o N/A
433 \row \o QWidget::ownPalette \o QWidget::ownPalette() \o N/A
434 \row \o QWidget::paletteBackgroundColor \o QWidget::paletteBackgroundColor() \o QWidget::setPaletteBackgroundColor()
435 \row \o QWidget::paletteBackgroundPixmap \o QWidget::paletteBackgroundPixmap() \o QWidget::setPaletteBackgroundPixmap()
436 \row \o QWidget::paletteForegroundColor \o QWidget::paletteForegroundColor() \o QWidget::setPaletteForegroundColor()
437 \row \o QWidget::underMouse \o QWidget::underMouse() \o N/A
438 \endtable
439
440 The following Qt 3 properties and their access functions are no
441 longer available in Qt 4. In most cases, Qt 4 provides similar
442 functionality.
443
444 \table
445 \header \o Qt 3 property \o Qt 4 equivalent
446 \row \o QButton::autoRepeat \o N/A
447 \row \o QButton::autoResize \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents.
448 \row \o QButton::exclusiveToggle \o See \l QAbstractButton::autoExclusive.
449 \row \o QButton::pixmap \o Use QAbstractButton::icon instead.
450 \row \o QButton::toggleState \o Use QCheckBox::setState() and QCheckBox::state() instead.
451 \row \o QButton::toggleType \o Use QCheckBox::setTristate() instead.
452 \row \o QComboBox::autoResize \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents.
453 \row \o QFrame::contentsRect \o Use Q3Frame::contentsRect() instead.
454 \row \o QFrame::margin \o Use QWidget::setContentsMargins() instead.
455 \row \o QTabBar::keyboardFocusTab \o N/A
456 \row \o QToolButton::offIconSet \o Use the \l{QIcon::Off}{off component} of QAbstractButton::icon instead.
457 \row \o QToolButton::onIconSet \o Use the \l{QIcon::On}{on component} of QAbstractButton::icon instead.
458 \row \o QWidget::microFocusHint \o N/A
459 \row \o QMimeSource::serialNumber () \o N/A
460 \endtable
461
462\omit
463 \section1 Inheritance Chain
464
465 ### QMenuBar, etc.
466
467 \section1 Null vs. Empty
468
469 ###
470\endomit
471
472 \section1 Explicit Sharing
473
474 Qt 4 is the first version of Qt that contains no \link
475 http://doc.qt.nokia.com/3.3/shclass.html explicitly shared
476 \endlink classes. All classes that were explicitly shared in Qt 3
477 are \e implicitly shared in Qt 4:
478
479 \list
480 \o QImage
481 \o QBitArray
482 \o QByteArray
483 \o Q3PointArray
484 \endlist
485
486 This means that if you took a copy of an instance of the class
487 (using operator=() or the class's copy constructor), any
488 modification to the copy would affect the original and vice
489 versa. Needless to say, this behavior is rarely desirable.
490
491 Fortunately, nearly all Qt 3 applications don't rely on explicit
492 sharing. When porting, you typically only need to remove calls to
493 detach() and/or copy(), which aren't necessary anymore.
494
495 If you deliberately rely on explicit sharing in your application,
496 you can use pointers or references to achieve the same result in
497 Qt 4.
498
499 \oldcode
500 void asciify(QByteArray array)
501 {
502 for (int i = 0; i < (int)array.size(); ++i) {
503 if ((uchar)array[i] >= 128)
504 array[i] = '?';
505 }
506 }
507 \newcode
508 void asciify(QByteArray &array)
509 {
510 for (int i = 0; i < array.size(); ++i) {
511 if ((uchar)array[i] >= 128)
512 array[i] = '?';
513 }
514 }
515 \endcode
516
517 (Notice the \c & in the parameter declaration.)
518
519\omit
520 \section1 Qt Designer UI Files
521
522 ###
523\endomit
524
525 \section1 Painting and Redrawing Widgets
526
527 When implementing custom widgets in Qt 3, it was possible to use
528 QPainter to draw on a widget outside paint events. This made it
529 possible to integrate Qt applications with third party libraries
530 and tools that impose their own rendering models. For example,
531 a widget might be repainted in a slot using data obtained from
532 an external source.
533
534 In Qt 4, it is only possible to paint on a widget from within its
535 \l{QWidget::}{paintEvent()} handler function. This restriction simplifies
536 Qt's interaction with native window systems, improves the performance
537 of applications by reducing the number of redraw operations, and
538 also enables features to be implemented to improve the appearance of
539 widgets, such as a backing store.
540
541 Generally, we recommend redesigning applications to perform all
542 painting operations in \l{QWidget::}{paintEvent()} functions, deferring
543 actual painting until the next time this function is called.
544 Applications can post paint events to trigger repaints, and it may be
545 possible to examine your widget's internal state to determine which
546 part of the widget needs to be repainted.
547
548 If asynchronous repaints are used extensively by your application,
549 and it is not practical to redesign the rendering model to perform
550 all painting operations from within a widget's \l{QWidget::}{paintEvent()}
551 function, it may be necessary to consider using an intermediate painting
552 step. In this approach, one or more images can be updated asynchronously
553 and painted on the widget in the paint event. To avoid excessive
554 buffering, it may be worthwhile disabling the backing store by setting
555 the widget's Qt::WA_PaintOnScreen widget attribute.
556
557 On certain platforms, the Qt::WA_PaintOutsidePaintEvent widget attribute
558 can be set to allow a widget to be painted from outside paint events.
559
560 \note Setting widget attributes to disable key features of Qt's widget
561 rendering model may also cause other features to be disabled.
562
563 \section1 Compatibility Signals and Slots
564
565 When \c QT3_SUPPORT is defined, the default connection type for signals
566 and slots is the Qt::AutoCompatConnection type. This allows so-called
567 \e compatibility signals and slots (defined in Qt 3 support mode to provide
568 Qt 3 compatibility features) to be connected to other signals and
569 slots.
570
571 However, if Qt is compiled with debugging output enabled, and the
572 developer uses other connection types to connect to compatibility
573 signals and slots (perhaps by building their application without Qt 3
574 support enabled), then Qt will output warnings to the console to
575 indicate that compatibility connections are being made. This is intended
576 to be used as an aid in the process of porting a Qt 3 application to Qt 4.
577
578 \section1 QAccel
579
580 The \c QAccel class has been renamed Q3Accel and moved to the
581 Qt3Support module. In new applications, you have three options:
582
583 \list 1
584 \o You can use QAction and set a key sequence using QAction::setShortcut().
585 \o You can use QShortcut, a class that provides similar
586 functionality to Q3Accel.
587 \o You can use QWidget::grabShortcut() and process "shortcut"
588 events by reimplementing QWidget::event().
589 \endlist
590
591 The Q3Accel class also supports multiple accelerators using the
592 same object, by calling Q3Accel::insertItem() multiple times. In
593 Qt 4, the solution is to create multiple QShortcut objects.
594
595 \section1 QAccessibleInterface
596
597 The QAccessibleInterface class has undergone some API changes in
598 Qt 4, to make it more consistent with the rest of the Qt API.
599
600 If you have classes that inherit QAccessibleInterface or one of
601 its subclasses (QAccessibleObject, QAccessibleWidget, etc.), you
602 must port them the new QAccessibleInterface API.
603
604 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions}
605 for a list of QAccessibleInterface virtual member functions in
606 Qt 3 that are no longer virtual in Qt 4.
607
608 \section1 QAccessibleTitleBar
609
610 The \c QAccessibleTitleBar has been renamed Q3AccessibleTitleBar
611 and moved to the Qt3Support library.
612
613 \target qaction.section
614 \section1 QAction
615
616 The QAction class has been redesigned in Qt 4 to integrate better
617 with the rest of the menu system. It unifies the old \c QMenuItem
618 class and the old \c QAction class into one class, avoiding
619 unnecessary data duplication and the need to learn two different
620 APIs.
621
622 The old \c QAction and \c QActionGroup classes have been renamed
623 Q3Action and Q3ActionGroup and moved to Qt3Support. In addition,
624 the new QAction class has compatibility functions to ease
625 transition to Qt 4. Note that when using Q3ToolBar and
626 Q3PopupMenu, their actions must be \l {Q3Action}s.
627
628 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions}
629 for a list of QAction virtual member functions in Qt 3 that are
630 no longer virtual in Qt 4.
631
632 \section1 QActionGroup
633
634 The QAction class has been completely redesigned in Qt 4 to
635 integrate better with the rest of the menu system. See the
636 \l{#qaction.section}{section on QAction} for details.
637
638 \section1 QApplication
639
640 The QApplication class has been split into two classes:
641 QCoreApplication and QApplication. The new QApplication class
642 inherits QCoreApplication and adds GUI-related functionality. In
643 practice, this has no consequences for existing Qt applications.
644
645 In addition, the following API changes were made:
646
647 \list 1
648 \o QApplication::allWidgets() and QApplication::topLevelWidgets()
649 used to return a pointer to a QWidgetList. Now they return a
650 QWidgetList.
651
652 Also, QWidgetList has changed from being a typedef for
653 QPtrList<QWidget> to being a typedef for QList<QWidget *>.
654 See the \l{#qwidgetlist.section}{section on QWidgetList} below
655 for details.
656
657 \oldcode
658 QWidgetList *list = QApplication::topLevelWidgets();
659 QWidgetListIt it(*list);
660 QWidget *widget;
661 while ((widget = it.current())) {
662 if (widget->inherits("MainWindow"))
663 ((MainWindow *)widget)->updateRecentFileItems();
664 ++it;
665 }
666 delete list;
667 \newcode
668 QWidgetList list = QApplication::topLevelWidgets();
669 for (int i = 0; i < list.size(); ++i) {
670 if (MainWindow *mainWin = qobject_cast<MainWindow *>(list.at(i)))
671 mainWin->updateRecentFileItems();
672 }
673 \endcode
674 \o QApplication::setMainWidget() is no longer used. When all an application's
675 windows are closed, the application will exit normally.
676 \endlist
677
678 \section1 QAquaStyle
679
680 The \c QAquaStyle class first appeared in Qt 3.0, when the Qt for
681 Mac OS X port was first released. It emulated Apple's "Aqua" theme.
682 In Qt 3.1, QAquaStyle was obsoleted by QMacStyle, which uses Appearance
683 Manager to perform its drawing.
684
685 The \c QAquaStyle class is no longer provided in Qt 4. Use
686 QMacStyle instead.
687
688 \target qasciidict.section
689 \section1 QAsciiCache<T>
690
691 \c QAsciiCache<T> has been renamed Q3AsciiCache<T> and moved to
692 the Qt3Support library. It has been replaced by
693 QCache<QByteArray, T>.
694
695 For details, read the \l{#qcache.section}{section on QCache<T>},
696 mentally substituting QByteArray for QString.
697
698 \section1 QAsciiDict<T>
699
700 QAsciiDict<T> and QAsciiDictIterator<T> have been renamed
701 Q3AsciiDict<T> and Q3AsciiDictIterator<T> and moved to the
702 Qt3Support library. They have been replaced by the
703 more modern QHash<Key, T> and QMultiHash<Key, T> classes and
704 their associated iterator classes.
705
706 When porting old code that uses Q3AsciiDict<T> to Qt 4, there are
707 four classes that you can use:
708
709 \list
710 \o QMultiHash<QByteArray, T *>
711 \o QMultiHash<QByteArray, T>
712 \o QHash<QByteArray, T *>
713 \o QHash<QByteArray, T>
714 \endlist
715
716 For details, read the \l{#qdict.section}{section on QDict<T>},
717 mentally substituting QByteArray for QString.
718
719 \section1 QAsyncIO
720
721 The \c QAsyncIO class was used internally in Qt 2.x in
722 conjunction with QImageConsumer. It was obsoleted in Qt 3.0.
723
724 \input porting/porting4-obsoletedmechanism.qdocinc
725
726 \section1 QBackInsertIterator
727
728 The undocumented \c QBackInsertIterator class has been removed
729 from the Qt library. If you need it in your application, feel
730 free to copy the source code from the Qt 3 \c <qtl.h> header
731 file.
732
733 \section1 QBitArray
734
735 In Qt 3, QBitArray inherited from QByteArray. In Qt 4, QBitArray
736 is a totally independent class. This makes very little difference
737 to the user, except that the new QBitArray doesn't provide any of
738 QByteArray's byte-based API anymore. These calls will result in a
739 compile-time error, except calls to QBitArray::truncate(), whose
740 parameter was a number of \e bytes in Qt 3 and a number of bits
741 in Qt 4.
742
743 QBitArray was an explicitly shared class in Qt 3. See \l{Explicit
744 Sharing} for more information.
745
746 The \c QBitVal class has been renamed QBitRef.
747
748 \section1 QButton
749
750 The \c QButton class has been replaced by QAbstractButton in Qt
751 4. Classes like QPushButton and QRadioButton inherit from
752 QAbstractButton. As a help when porting older Qt applications,
753 the Qt3Support library contains a Q3Button class
754 implemented in terms of the new QAbstractButton.
755
756 If you used the \c QButton class as a base class for your own
757 button type and want to port your code to the newer
758 QAbstractButton, you need to be aware that QAbstractButton has no
759 equivalent for the Q3Button::drawButton(QPainter *) virtual
760 function. The solution is to reimplement QWidget::paintEvent() in
761 your QAbstractButton subclass as follows:
762
763 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 0
764
765 \table
766 \header \o Q3Button function \o QAbstractButton equivalent
767 \row \o Q3Button::autoResize() \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents.
768 \row \o Q3Button::isExclusiveToggle() \o Use QAbstractButton::group() or QAbstractButton::autoExclusive() instead.
769 \row \o Q3Button::pixmap() const \o QAbstractButton::icon()
770 \row \o Q3Button::setAutoResize() \o N/A
771 \row \o Q3Button::setPixmap(const QPixmap &) \o QAbstractButton::setIcon(const QIcon &)
772 \row \o Q3Button::setState(ToggleState) \o See remark below
773 \row \o Q3Button::setToggleType(ToggleType) \o See remark below
774 \row \o Q3Button::state() \o See remark below
775 \row \o Q3Button::stateChanged(int) \o See remark below
776 \row \o Q3Button::toggleType() \o See remark below
777 \endtable
778
779 Remarks:
780
781 \list 1
782 \o In Qt 3, \c QButton had a "toggle type", which could be
783 QButton::SingleShot, QButton::Toggle, or QButton::Tristate.
784 The new QAbstractButton class doesn't support "tristate"
785 directly; this feature is implemented in QCheckBox instead.
786 The two other "toggle types" (\c QButton::SingleShot and \c
787 QButton::Toggle) are replaced by a QAbstractButton::checkable
788 property.
789 \o In Qt 3, QButton had a "toggle state", which could be \c
790 QButton::Off, \c QButton::NoChange, or \c QButton::On. In Qt
791 4, this mechanism has been moved to QCheckBox.
792 \endlist
793
794 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
795 a list of \c QButton virtual member functions in Qt 3 that aren't
796 virtual in Qt 4.
797
798 See \l{#properties}{Properties} for a list of \c QButton properties
799 in Qt 3 that have changed in Qt 4.
800
801 \section1 QButtonGroup
802
803 The \c QButtonGroup class has been completely redesigned in Qt 4.
804 For compatibility, the old \c QButtonGroup class has been renamed
805 Q3ButtonGroup and has been moved to Qt3Support.
806 Likewise, the \c QHButtonGroup and \c QVButtonGroup convenience
807 subclasses have been renamed \c Q3HButtonGroup and \c Q3VButtonGroup and
808 moved to the Qt3Support library.
809
810 The old \c QButtonGroup, as well as Q3ButtonGroup, can be used in two ways:
811
812 \list 1
813 \o The button group is the parent widget of a number of buttons,
814 i.e. the button group is the parent argument in the button
815 constructor. The buttons are assigned identifiers 0, 1, 2, etc.,
816 in the order they are created. A Q3ButtonGroup can display a frame
817 and a title because it inherits Q3GroupBox.
818 \o The button group is an invisible widget and the contained
819 buttons have some other parent widget. In this usage, each
820 button must be manually inserted, using
821 Q3ButtonGroup::insert(), into the button group and given an
822 ID number.
823 \endlist
824
825 Unlike Q3ButtonGroup, the new QButtonGroup doesn't inherit
826 QWidget. It is very similar to a "hidden Q3ButtonGroup".
827
828 If you use a Q3ButtonGroup, Q3HButtonGroup, or Q3VButtonGroup as
829 a widget and want to port to Qt 4, you can replace it with
830 QGroupBox. In Qt 4, radio buttons with the same parent are
831 automatically part of an exclusive group, so you normally don't
832 need to do anything else. See also the
833 \l{#qgroupbox.section}{section on QGroupBox} below.
834
835 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
836 a list of QButtonGroup virtual member functions in Qt 3 that are no
837 longer virtual in Qt 4.
838
839 \target qbytearray.section
840 \section1 QByteArray
841
842 In Qt 3, QByteArray was simply a typedef for QMemArray<char>. In
843 Qt 4, QByteArray is a class in its own right, with a higher-level
844 API in the style of QString.
845
846 Here are the main issues to be aware of when porting to Qt 4:
847
848 \list 1
849 \o The QMemArray(int size) constructor has been replaced with
850 QByteArray(int size, char ch). The second argument specifies
851 which character should be used for initializing the array;
852 pass '\\0' if you have no specific needs.
853
854 \oldcode
855 QByteArray ba(64);
856 \newcode
857 QByteArray ba(64, '\0');
858 \endcode
859
860 \o QMemArray::at() returned a non-const reference, whereas the
861 new QByteArray::at() returns a const value. Code like
862
863 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 1
864
865 will no longer compile. Instead, use QByteArray::operator[]:
866
867 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 2
868
869 \o The QMemArray::contains(char) function has been renamed
870 QByteArray::count(char). In addition, there now exists a
871 QByteArray::contains(char) function that returns a boolean
872 value. Replace old calls to contains() with either count() or
873 contains(), depending on whether you care about the specific
874 number of occurrences of a character in the byte array or
875 only care about whether the array contains that character or
876 not.
877
878 \o The new QByteArray has no assign() function. Calls to
879 QMemArray::assign(const QMemArray &) can be replaced by calls
880 to QByteArray::operator=(). Calls to QMemArray::assign(const
881 T *, uint) have no equivalent in Qt 4; if you use it, the
882 solution is either to use QByteArray::fromRawData() and to
883 call free() yourself to avoid a memory leak, or to use the
884 QByteArray(const char *, int) constructor, which will take a
885 deep copy of the data.
886
887 \o QMemArray::bsearch() and QMemArray::sort() have no equivalent
888 in the new QByteArray class. Use \l qBinaryFind() and \l qSort()
889 if you need that functionality.
890 \endlist
891
892 QByteArray was an explicitly shared class in Qt 3. See
893 \l{Explicit Sharing} for more information.
894
895 \target qcache.section
896 \section1 QCache<T>
897
898 QCache<T> has been renamed Q3Cache<T> and moved to Qt3Support.
899 The new QCache class has a different API, and takes different
900 template parameters: QCache<Key, T>.
901
902 When porting to Qt 4, QCache<QString, T> is the obvious
903 substitute for Q3Cache<T>. The following table summarizes the API
904 differences.
905
906 \table
907 \header \o Q3Cache<T> function \o QCache<QString, T> equivalent
908 \row \o Q3Cache::Q3Cache(int maxCost, int size, bool caseSensitive) \o See remark below
909 \row \o Q3Cache::autoDelete() \o N/A
910 \row \o Q3Cache::count() \o QCache::count() or QCache::size() (equivalent)
911 \row \o Q3Cache::setAutoDelete() \o See remark below
912 \row \o Q3Cache::size() \o N/A
913 \row \o Q3Cache::statistics() \o N/A
914 \row \o Q3Cache::operator=() \o See remark below
915 \endtable
916
917 Remarks:
918
919 \list 1
920 \o Q3Cache requires the user to allocate a specific number of
921 buckets by passing a prime number (17 by default) to the
922 constructor. In contrast, the new QCache's hash table
923 automatically grows and shrinks as needed, and the
924 constructor doesn't take a prime number.
925
926 \o Q3Cache supportes case-insensitive lookups by passing false as
927 second argument to the constructor. This feature has no
928 equivalent in QMultiHash. Instead, call QString::toLower()
929 before you insert or lookup a key in the hash.
930
931 \o The Q3Cache::insert() function returns a \c bool value that
932 indicates whether or not the item actually was inserted in
933 the cache. If the item wasn't inserted, it was the caller's
934 responsibility to delete the item. The new QCache::insert()
935 function returns \c void and either adds it to the cache or
936 deletes it right away. Old code like
937
938 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 3
939
940 becomes
941
942 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 4
943
944 \o The new QCache class \e always takes ownership of the items
945 it stores (i.e. auto-delete is always on). If you use Q3Cache
946 with auto-delete turned off (the rarely useful default), you
947 cannot use QCache as a direct substitute. One unelegant trick
948 that works well in practice is to use QCache<QString, T *>
949 instead of QCache<QString, T>. In that case, QCache owns the
950 pointers, not the objects that the pointers refer to. For
951 example,
952
953 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 5
954
955 becomes
956
957 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 6
958
959 An alternative is to stick to using Q3Cache.
960 \endlist
961
962 QCacheIterator<T> has been renamed Q3CacheIterator<T> and moved
963 to the Qt3Support library. The new QCache class
964 doesn't offer any iterator types.
965
966 \section1 QCanvas
967
968 The canvas module classes have been
969 renamed and moved to the Qt3Support library.
970
971 \table
972 \header \o Qt 3 class name \o Compatibility class in Qt 4
973 \row \o \c QCanvas \o Q3Canvas
974 \row \o \c QCanvasEllipse \o Q3CanvasEllipse
975 \row \o \c QCanvasItem \o Q3CanvasItem
976 \row \o \c QCanvasItemList \o Q3CanvasItemList
977 \row \o \c QCanvasLine \o Q3CanvasLine
978 \row \o \c QCanvasPixmap \o Q3CanvasPixmap
979 \row \o \c QCanvasPixmapArray \o Q3CanvasPixmapArray
980 \row \o \c QCanvasPolygon \o Q3CanvasPolygon
981 \row \o \c QCanvasPolygonalItem \o Q3CanvasPolygonalItem
982 \row \o \c QCanvasRectangle \o Q3CanvasRectangle
983 \row \o \c QCanvasSpline \o Q3CanvasSpline
984 \row \o \c QCanvasSprite \o Q3CanvasSprite
985 \row \o \c QCanvasText \o Q3CanvasText
986 \row \o \c QCanvasView \o Q3CanvasView
987 \endtable
988
989 The \l{Graphics View Framework} replaces QCanvas. For more on
990 porting to Graphics View, see \l{Porting to Graphics View}.
991
992 \section1 QColor
993
994 In Qt 4, QColor is a value type like QPoint or QRect. Graphics
995 system-specific code has been implemented in QColormap.
996
997 The \c QColor::maxColors() function has been replaced
998 by QColormap::size().
999
1000 The \c QColor::numBitPlanes() function has been replaced
1001 by QColormap::depth().
1002
1003 The \c QColor::setNamedColor() function no longer supports
1004 the named color in the same way as Qt 3. Qt 4's
1005 \l{QColor::}{setNamedColor()} uses the new W3C convention
1006 as stated
1007 \l{http://www.w3.org/TR/SVG/types.html#ColorKeywords}{here}.
1008
1009 \table
1010 \header \o{4,1} Predefined Qt Colors
1011 \row \o Qt::color0 \o Qt::color1 \o Qt::black \o Qt::white
1012 \row \o Qt::darkGray \o Qt::gray \o Qt::lightGray \o Qt::red
1013 \row \o Qt::green \o Qt::blue \o Qt::cyan \o Qt::magenta
1014 \row \o Qt::yellow \o Qt::darkRed \o Qt::darkGreen \o Qt::darkBlue
1015 \row \o Qt::darkCyan \o Qt::darkMagenta \o Qt::darkYellow \o Qt::transparent
1016 \endtable
1017
1018 The predefined colors listed in the table above were static
1019 QColor objects in Qt 3. In Qt 4, they are enum values of type
1020 Qt::GlobalColor. Thanks to the implicit QColor(Qt::GlobalColor)
1021 constructor, the enum values are automatically converted to
1022 \l{QColor}s in most contexts. Occasionally, you might need a
1023 cast.
1024
1025 \oldcode
1026 QColor lightCyan = Qt::cyan.light(180);
1027 \newcode
1028 QColor lightCyan = QColor(Qt::cyan).light(180);
1029 \endcode
1030
1031 \section1 QColorGroup
1032
1033 In Qt 3, a QPalette consisted of three QColorGroup objects. In Qt
1034 4, the (rarely used) QColorGroup abstraction has been eliminated.
1035 For source compatibility, a QColorGroup class is available when
1036 \c QT3_SUPPORT is defined.
1037
1038 The new QPalette still works in terms of color groups, specified
1039 through enum values (QPalette::Active, QPalette::Disabled, and
1040 QPalette::Inactive). It also has the concept of a \e current
1041 color group, which you can set using
1042 QPalette::setCurrentColorGroup().
1043
1044 The QPalette object returned by QWidget::palette() returns a
1045 QPalette initialized with the correct current color group for the
1046 widget. This means that if you had code like
1047
1048 \badcode
1049 painter.setBrush(colorGroup().brush(QColorGroup::Text));
1050 \endcode
1051
1052 you can simply replace colorGroup() with palette():
1053
1054 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 7
1055
1056 \section1 QColorDrag
1057
1058 The \c QColorDrag class has been renamed Q3ColorDrag and moved to
1059 the Qt3Support library. In Qt 4, use QMimeData
1060 instead and call QMimeData::setColor() to set the color.
1061
1062 \section1 QComboBox
1063
1064 In Qt 3, the list box used to display the contents of a \c QComboBox
1065 widget could be accessed by using the \c listBox() function. In Qt 4,
1066 the standard list box is provided by a QListView widget, and can be
1067 accessed with the \l{QComboBox::view()}{view()} function.
1068
1069 \omit ### \endomit
1070
1071 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1072 a list of QComboBox virtual member functions in Qt 3 that are no longer
1073 virtual in Qt 4.
1074
1075 \section1 QCString
1076
1077 In Qt 3, QCString inherited from QByteArray. The main drawback
1078 of this approach is that the user had the responsibility of
1079 ensuring that the string is '\\0'-terminated. Another important
1080 issue was that conversions between \c QCString and QByteArray often
1081 gave confusing results. (See the
1082 \l{http://doc.qt.nokia.com/qq/qq05-achtung.html#qcstringisastringofchars}{Achtung!
1083 Binary and Character Data} article in \e{Qt Quarterly} for an
1084 overview of the pitfalls.)
1085
1086 Qt 4 solves that problem by merging the QByteArray and \c QCString
1087 classes into one class called QByteArray. Most functions that
1088 were in \c QCString previously have been moved to QByteArray. The
1089 '\\0' issue is handled by having QByteArray allocate one extra
1090 byte that it always sets to '\\0'. For example:
1091
1092 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 8
1093
1094 The Qt3Support library contains a class called
1095 Q3CString that inherits from the new QByteArray class and that
1096 extends it to provide an API that is as close to the old \c QCString
1097 class as possible. Note that the following functions aren't
1098 provided by Q3CString:
1099
1100 \list
1101 \o QCString::find(const QRegExp &, int)
1102 \o QCString::findRev(const QRegExp &, int)
1103 \o QCString::contains(const QRegExp &)
1104 \o QCString::replace(const QRegExp &, const char *)
1105 \endlist
1106
1107 The following functions have lost their last parameter, which
1108 specified whether the search was case sensitive or not:
1109
1110 \list
1111 \o QByteArray::find(char, int)
1112 \o QByteArray::find(const char *, int)
1113 \o QByteArray::findRev(char, int)
1114 \o QByteArray::findRev(const char *, int)
1115 \o QByteArray::contains(char)
1116 \o QByteArray::contains(const char *)
1117 \endlist
1118
1119 In both cases, the solution is to convert the \c QCString to a
1120 QString and use the corresponding QString functions instead.
1121
1122 Also be aware that \c QCString::size() (inherited from
1123 QByteArray) used to return the size of the character data \e
1124 including the '\\0'-terminator, whereas the new
1125 QByteArray::size() is just a synonym for QByteArray::length().
1126 This brings QByteArray in line with QString.
1127
1128 When porting to Qt 4, occurrences of \c QCString should be
1129 replaced with QByteArray or QString. The following table
1130 summarizes the API differences between the Q3CString
1131 class and the Qt 4 QByteArray and QString classes:
1132
1133 \table
1134 \header \o Q3CString function \o Qt 4 equivalent
1135 \row \o Q3CString::Q3CString(const char *, uint) \o See remark below
1136 \row \o Q3CString::Q3CString(int) \o QByteArray::QByteArray(int, char)
1137 \row \o Q3CString::leftJustify() \o QString::leftJustified()
1138 \row \o Q3CString::length() \o QByteArray::length() or QByteArray::size() (equivalent)
1139 \row \o Q3CString::lower() \o QByteArray::toLower()
1140 \row \o Q3CString::rightJustify() \o QString::rightJustified()
1141 \row \o Q3CString::setExpand() \o See remark below
1142 \row \o Q3CString::simplifyWhiteSpace() \o QByteArray::simplified()
1143 \row \o Q3CString::sprintf() \o QString::sprintf()
1144 \row \o Q3CString::stripWhiteSpace() \o QByteArray::trimmed()
1145 \row \o Q3CString::toDouble() \o QString::toDouble()
1146 \row \o Q3CString::toFloat() \o QString::toFloat()
1147 \row \o Q3CString::toInt() \o QString::toInt()
1148 \row \o Q3CString::toLong() \o QString::toLong()
1149 \row \o Q3CString::toShort() \o QString::toShort()
1150 \row \o Q3CString::toUInt() \o QString::toUInt()
1151 \row \o Q3CString::toULong() \o QString::toULong()
1152 \row \o Q3CString::toUShort() \o QString::toUShort()
1153 \row \o Q3CString::upper() \o QByteArray::toUpper()
1154 \endtable
1155
1156 Remarks:
1157
1158 \list 1
1159 \o Q3CString(const char *str, uint max) constructs a string of
1160 length strlen(str) or \e max - 1, whichever is shorter.
1161 QByteArray(const char *data, int size) constructs a byte
1162 array containing exactly \e size bytes.
1163
1164 \oldcode
1165 QCString str1("Hello", 4); // "Hel"
1166 QCString str2("Hello world!", n);
1167 \newcode
1168 QByteArray str1("Hello", 3);
1169 QByteArray str2("Hello world!");
1170 str2.truncate(n - 1);
1171 \endcode
1172
1173 \o Q3CString::setExpand(uint index, char ch) has no equivalent in
1174 Qt 4.
1175
1176 \oldcode
1177 QCString str("Hello world");
1178 str.setExpand(16, '\n'); // "Hello world \n"
1179 \newcode
1180 QByteArray str("Hello world");
1181 while (str.size() < 16)
1182 str += ' ';
1183 str += '\n';
1184 \endcode
1185 \endlist
1186
1187 Since the old \c QCString class inherited from QByteArray,
1188 everything that is said in the \l{#qbytearray.section}{QByteArray
1189 section} applies for \c QCString as well.
1190
1191 \section1 QCustomEvent
1192
1193 In Qt 3, developers could create a custom event by constructing
1194 a new QCustomEvent, and send relevant data to other components in
1195 the application by passing a void pointer, either on construction or
1196 using the setData() function. Objects could receive custom events
1197 by reimplementing the \l{QObject::customEvent()}{customEvent()}
1198 function, and access the stored data using the event's data()
1199 function.
1200
1201 In Qt 4, custom events are created by subclassing
1202 QEvent. Event-specific data can be stored in a way that is
1203 appropriate for your application. Custom events are still
1204 delivered to each object's
1205 \l{QObject::customEvent()}{customEvent()} handler function, but as
1206 QEvent objects rather than as deprecated QCustomEvent objects.
1207
1208 \section1 QDataBrowser
1209
1210 The \c QDataBrowser class has been renamed Q3DataBrowser and
1211 moved to the Qt3Support library. In Qt 4.2, you should use the
1212 QDataWidgetMapper class to create data-aware forms.
1213
1214 See \l{QtSql Module} for an overview of the new SQL
1215 classes.
1216
1217 \section1 QDataPump
1218
1219 The \c QDataPump class was used internally in Qt 2.x in
1220 conjunction with QImageConsumer. It was obsoleted in Qt 3.0.
1221
1222 \input porting/porting4-obsoletedmechanism.qdocinc
1223
1224 \section1 QDataSink
1225
1226 The \c QDataSink class was used internally in Qt 2.x in conjunction
1227 with QImageConsumer. It was obsoleted in Qt 3.0.
1228
1229 \input porting/porting4-obsoletedmechanism.qdocinc
1230
1231 \section1 QDataSource
1232
1233 The \c QDataSource class was used internally in Qt 2.x in
1234 conjunction with QImageConsumer. It was obsoleted in Qt 3.0.
1235 \input porting/porting4-obsoletedmechanism.qdocinc
1236
1237 \section1 QDataTable
1238
1239 The \c QDataTable class has been renamed Q3DataTable and moved to
1240 the Qt3Support library. In Qt 4.2, you should use the
1241 QDataWidgetMapper class to create data-aware forms.
1242
1243 See \l{QtSql Module} for an overview of the new SQL classes.
1244
1245 \section1 QDataView
1246
1247 The \c QDataView class has been renamed Q3DataView and moved to
1248 the Qt3Support library. In Qt 4.2, you should use the
1249 QDataWidgetMapper class to create data-aware forms.
1250
1251 See \l{QtSql Module} for an overview of the new SQL classes.
1252
1253 \section1 QDateEdit
1254
1255 The QDateEdit class in Qt 4 is a convenience class based on
1256 QDateTimeEdit. The old class has been renamed Q3DateEdit and moved
1257 to the Qt3Support library.
1258
1259 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1260 a list of \c QDateEdit virtual member functions in Qt 3 that are
1261 no longer virtual in Qt 4.
1262
1263 \section1 QDateTimeEditBase
1264
1265 The \c QDateTimeEditBase class has been renamed
1266 Q3DateTimeEditBase and moved to Qt3Support. Use QDateTimeEdit or
1267 QAbstractSpinBox instead.
1268
1269 \section1 QDateTimeEdit
1270
1271 The old \c QDateTimeEdit class has been renamed
1272 Q3DateTimeEditBase and moved to Qt3Support. The new QDateTimeEdit
1273 in Qt 4 has been rewritten from scratch to provide a more
1274 flexible and powerful API.
1275
1276 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1277 a list of QDateTimeEdit virtual member functions in Qt 3 that are no
1278 longer virtual in Qt 4.
1279
1280 \section1 QDeepCopy<T>
1281
1282 The \c QDeepCopy<T> class in Qt 3 provided a means of ensuring that
1283 implicitly shared and explicitly shared classes referenced unique
1284 data. This was necessary because the reference counting in Qt's
1285 container classes was done in a thread-unsafe manner.
1286
1287 With Qt 4, \c QDeepCopy<T> has been renamed Q3DeepCopy<T> and
1288 moved to the Qt3Support library. Removing it from
1289 existing code is straightforward.
1290
1291 \oldcode
1292 QString str1 = "I am a string";
1293 QDeepCopy<QString> str2 = str1;
1294 QString str3 = QDeepCopy<QString>(str2);
1295 \newcode
1296 QString str1 = "I am a string";
1297 QString str2 = str1;
1298 QString str3 = str2;
1299 \endcode
1300
1301 \section1 QDial
1302
1303 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1304 a list of QDial virtual member functions in Qt 3 that are no longer
1305 virtual in Qt 4.
1306
1307 See \l{#properties}{Properties} for a list of QDial properties in
1308 Qt 3 that have changed in Qt 4.
1309
1310 \target qdict.section
1311 \section1 QDict<T>
1312
1313 \c QDict<T> has been renamed Q3Dict<T> and moved to Qt3Support.
1314 It has been replaced by the more modern QHash<Key, T> and
1315 QMultiHash<Key, T> classes.
1316
1317 When porting old code that uses QDict<T> to Qt 4, there are four
1318 classes that you can use:
1319
1320 \table
1321 \header \o Qt 4 class \o When to use it
1322 \row \o QMultiHash<QString, T *>
1323
1324 \o Since Q3Dict<T> is pointer-based and allows duplicate
1325 keys, this is usually the most straightforward conversion.
1326
1327 \row \o QMultiHash<QString, T>
1328
1329 \o If type \c T is an \l{assignable data type}, you can use
1330 \c T as the value type rather than \c{T *}. This often
1331 leads to nicer code.
1332
1333 \row \o QHash<QString, T *>
1334
1335 \o{1,2} If you don't use duplicate keys, you can use QHash
1336 instead of QMultiHash. QMultiHash inherits from QHash.
1337
1338 \row \o QHash<QString, T>
1339 \endtable
1340
1341 The APIs of Q3Dict<T> and QMultiHash<QString, T *> are quite
1342 similar. The main issue is that Q3Dict supports auto-delete
1343 whereas QMultiHash doesn't.
1344
1345 \omit
1346 (See \l{What's Wrong with
1347 Auto-Delete} for an explanation of why the Qt 4 containers don't
1348 offer that feature.)
1349 \endomit
1350
1351 The following table summarizes the API differences between the
1352 two classes:
1353
1354 \table
1355 \header \o Q3Dict function \o QMultiHash equivalent
1356 \row \o Q3Dict::Q3Dict(int size, bool caseSensitive) \o See remarks below
1357 \row \o Q3Dict::autoDelete() \o N/A
1358 \row \o Q3Dict::count() \o QMultiHash::count() or QMultiHash::size() (equivalent)
1359 \row \o Q3Dict::find(const QString &) \o QMultiHash::value(const QString &)
1360 \row \o Q3Dict::remove(const QString &) \o QMultiHash::take(const QString &)
1361 \row \o Q3Dict::resize(uint) \o QMultiHash::reserve(int)
1362 \row \o Q3Dict::setAutoDelete() \o See discussion below
1363 \row \o Q3Dict::size() \o QMultiHash::capacity()
1364 \row \o Q3Dict::statistics() \o N/A
1365 \row \o Q3Dict::operator[](const QString &) \o See remark below
1366 \endtable
1367
1368 Remarks:
1369
1370 \list 1
1371 \o Q3Dict requires the user to allocate a specific number of
1372 buckets by passing a prime number (17 by default) to the
1373 constructor and/or calling Q3Dict::resize() later on. In
1374 contrast, QMultiHash's hash table automatically grows and
1375 shrinks as needed, and the constructor doesn't take a prime
1376 number.
1377
1378 \o Q3Dict supportes case-insensitive lookups by passing false as
1379 second argument to the constructor. This feature has no
1380 equivalent in QMultiHash. Instead, call QString::toLower()
1381 before you insert or lookup a key in the hash.
1382
1383 \o Q3Dict::size() and QMultiHash::size() have different semantics.
1384 The former returns the number of buckets in the container, whereas
1385 the latter returns the number of \e items in the container.
1386
1387 \o If there are multiple items with the same key,
1388 Q3Dict::remove() removes only the most recently inserted item,
1389 whereas QMultiHash::remove() removes all items that share a
1390 particular key. To remove only the most recently inserted item,
1391 call QMultiHash::take().
1392
1393 \o Q3Dict has only one [] operator (Q3Dict::operator[]()),
1394 providing const access to an item's value. QMultiHash also
1395 has a non-const overload that can be used on the left side of
1396 the assignment operator. If you use the [] operator on a
1397 non-const QHash with an unexisting item, QHash will created
1398 an element and initialize it to be a null pointer. For that
1399 reason, Q3Dict::operator[] should be converted to
1400 QMultiHash::value(), not QMultiHash::operator[].
1401
1402 \endlist
1403
1404 If you use Q3Dict's auto-delete feature (by calling
1405 Q3Dict::setAutoDelete(true)), you need to do some more work. You
1406 have two options: Either you call \c delete yourself whenever you
1407 remove an item from the container, or you use
1408 QMultiHash<QString, T> instead of QMultiHash<QString, T *> (i.e.
1409 store values directly instead of pointers to values). Here, we'll
1410 see when to call \c delete.
1411
1412 The following table summarizes the idioms that you need to watch
1413 out for if you want to call \c delete yourself.
1414
1415 \table
1416 \header \o Q3Dict idiom \o QMultiHash idiom
1417 \row
1418 \o
1419 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 9
1420 \o
1421 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 10
1422 \row
1423 \o
1424 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 11
1425 \o
1426 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 12
1427 \row
1428 \o
1429 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 13
1430
1431 (also called from Q3Dict's destructor)
1432
1433 \o
1434 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 14
1435
1436 In 99% of cases, the following idiom also works:
1437
1438 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 15
1439
1440 However, it may lead to crashes if \c hash is referenced from
1441 the value type's destructor, because \c hash contains
1442 dangling pointers until clear() is called.
1443 \endtable
1444
1445 Be aware that Q3Dict's destructor automatically calls clear(). If
1446 you have a Q3Dict data member in a custom class and use the
1447 auto-delete feature, you will need to call \c delete on all the
1448 items in the container from your class destructor to avoid a
1449 memory leak.
1450
1451 Finally, \c QDictIterator<T> (renamed Q3DictIterator<T>) must
1452 also be ported. There are no fewer than four iterator classes
1453 that can be used as a replacement: QHash::const_iterator,
1454 QHash::iterator, QHashIterator, and QMutableHashIterator. The
1455 most straightforward class to use when porting is
1456 QHashIterator<QString, T *>. The following table summarizes the
1457 API differences:
1458
1459 \table
1460 \header \o Q3DictIterator functions \o Qt 4 equivalent
1461 \row \o Q3DictIterator::count() \o QHash::count() or QHash::size()
1462 \row \o Q3DictIterator::current() \o QHashIterator::value()
1463 \row \o Q3DictIterator::currentKey() \o QHashIterator::key()
1464 \row \o Q3DictIterator::isEmpty() \o QHash::isEmpty()
1465 \row \o Q3DictIterator::toFirst() \o QHashIterator::toFront()
1466 \row \o Q3DictIterator::operator()() \o QHashIterator::value()
1467 \row \o Q3DictIterator::operator*() \o QHashIterator::value()
1468 \row \o Q3DictIterator::operator++() \o See remark below
1469 \endtable
1470
1471 Be aware that QHashIterator has a different way of iterating than
1472 Q3DictIterator. A typical loop with Q3DictIterator looks like this:
1473
1474 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 16
1475
1476 Here's the equivalent QHashIterator loop:
1477
1478 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 17
1479
1480 See \l{Java-style iterators} for details.
1481
1482 \section1 QDir
1483
1484 The following functions used to have a boolean \c{acceptAbsPath}
1485 parameter that defaulted to true:
1486
1487 \list
1488 \i QDir::filePath()
1489 \i QDir::absFilePath()
1490 \i QDir::cd()
1491 \i QDir::mkdir()
1492 \i QDir::rmdir()
1493 \i QDir::remove()
1494 \i QDir::rename()
1495 \i QDir::exists()
1496 \endlist
1497
1498 In Qt 3, if \c acceptAbsPath is true, a file name starting with
1499 '/' is be returned without change; if \c acceptAbsPath is false,
1500 an absolute path is prepended to the file name. For example:
1501
1502 \table
1503 \header \i Current directory \i File name \i \c acceptAbsPath \i File path
1504 \row \i{1,2} /home/tsmith \i{1,2} index.html \i true \i /home/tsmith/index.html
1505 \row \i false \i /home/tsmith/index.html
1506 \row \i{1,2} /home/tsmith \i{1,2} /index.html \i true \i /index.html
1507 \row \i false \i /home/tsmith/index.html
1508 \endtable
1509
1510 In Qt 4, this parameter is no longer available. If you use it
1511 in your code, you can check that QDir::isRelativePath() returns
1512 false instead.
1513
1514 \oldcode
1515 QDir dir("/home/tsmith");
1516 QString path = dir.filePath(fileName, false);
1517 \newcode
1518 QDir dir("/home/tsmith");
1519 QString path;
1520 if (dir.isRelativePath(fileName))
1521 path = dir.filePath(fileName);
1522 else
1523 path = fileName;
1524 \endcode
1525
1526 QDir::encodedEntryList() has been removed.
1527
1528 fileInfoList(), entryInfoList(), and drives() now return a QList<QFileInfo>
1529 and not a QPtrList<QFileInfo> *. Code using these methods will not work with
1530 the Qt3Support library and must be adapted instead.
1531
1532 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1533 a list of QDir virtual member functions in Qt 3 that are no longer
1534 virtual in Qt 4.
1535
1536 QDir::match() now always matches case insensitively.
1537
1538 QDir::homeDirPath() has been removed. Use QDir::home() instead, and
1539 extract the path separately.
1540
1541 \section1 QDns
1542
1543 Qt 3 used its own implementation of the DNS protocol and provided
1544 a low-level \c QDns class. Qt 4's QHostInfo class uses the system's \c
1545 gethostbyname() function from a thread instead.
1546
1547 The old \c QDns class has been renamed Q3Dns and moved to the
1548 Qt3Support library. The new QHostInfo class has a
1549 radically different API: It consists mainly of two static
1550 functions, one of which is blocking (QHostInfo::fromName()), the
1551 other non-blocking (QHostInfo::lookupHost()). See the QHostInfo
1552 class documentation for details.
1553
1554 \section1 QDockArea
1555
1556 The \c QDockArea class has been renamed Q3DockArea and moved to
1557 the Qt3Support library. In Qt 4, QMainWindow handles
1558 the dock and toolbar areas itself. See the QMainWindow
1559 documentation for details.
1560
1561 \section1 QDockWindow
1562
1563 The old \c QDockWindow class has been renamed Q3DockWindow and
1564 moved to the Qt3Support library. In Qt 4, there is a
1565 new QDockWidget class with a different API. See the class
1566 documentation for details.
1567
1568 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1569 a list of QDockWidget virtual member functions in Qt 3 that are no
1570 longer virtual in Qt 4.
1571
1572 \note \l{Q3DockWindow}'s
1573 \l{Q3DockWindow::setHorizontallyStretchable()}{horizontallyStretchable}
1574 property can be achieved in QDockWidget with
1575 \l{QWidget#Size Hints and Size Policies}{size policies}.
1576
1577 \section1 QDragObject
1578
1579 The \c QDragObject class has been renamed Q3DragObject and
1580 moved to the Qt3Support library. In Qt 4, it has been
1581 replaced by the QMimeData class. See the class documentation for
1582 details.
1583
1584 Note that the Q3DragObject::DragCopyOrMove drag and drop mode is
1585 interpreted differently to Qt 3's QDragObject::DragCopyOrMove mode.
1586 In Qt 3, a move operation was performed by default, and the user had
1587 to hold down the \key{Ctrl} key to perform a copy operation.
1588 In Qt 4, a copy operation is performed by default; the user has to
1589 hold down the \key{Shift} key to perform a move operation.
1590
1591 See \l{Porting to Qt 4 - Drag and Drop} for a comparison between
1592 the drag and drop APIs in Qt 3 and Qt 4.
1593
1594 \section1 QDropSite
1595
1596 The \c QDropSite class has been renamed Q3DropSite and moved to
1597 the Qt3Support library.
1598
1599 The QDropSite class has been obsolete ever since Qt 2.0. The only
1600 thing it does is call QWidget::setAcceptDrops(true).
1601
1602 \oldcode
1603 class MyWidget : public QWidget, public QDropSite
1604 {
1605 public:
1606 MyWidget(const QWidget *parent)
1607 : QWidget(parent), QDropSite(this)
1608 {
1609 }
1610 ...
1611 }
1612 \newcode
1613 class MyWidget : public QWidget
1614 {
1615 public:
1616 MyWidget(const QWidget *parent)
1617 : QWidget(parent)
1618 {
1619 setAcceptDrops(true);
1620 }
1621 ...
1622 }
1623 \endcode
1624
1625 See \l{Porting to Qt 4 - Drag and Drop} for a comparison between
1626 the drag and drop APIs in Qt 3 and Qt 4.
1627
1628 \section1 QEditorFactory
1629
1630 The \c QEditorFactory class has been renamed Q3EditorFactory and
1631 moved to the Qt3Support library.
1632
1633 See \l{QtSql Module} for an overview of the new SQL classes.
1634
1635 \section1 QEventLoop
1636
1637 In Qt 3, \c QEventLoop combined the Qt event loop and the event
1638 dispatching. In Qt 4, these tasks are now assigned to two
1639 distinct classes: QEventLoop and QAbstractEventDispatcher.
1640
1641 If you subclassed QEventLoop to integrate with another library's
1642 event loop, you must subclass QAbstractEventDispatcher instead. See
1643 the class documentation for details.
1644
1645 Developers using \c{QEventLoop::loopLevel()} in Qt 3 should use
1646 QCoreApplication::loopLevel() instead. Note that this function is
1647 marked as obsolete, but it is expected to be available for the
1648 lifetime of Qt 4.
1649 \omit ### mention virtual functions that aren't virtual anymore \endomit
1650
1651 \omit
1652 \section1 QFile
1653
1654 The QFile::readLine(QString&, Q_ULONG) method from qt3 has been removed
1655 in qt4, but this change in the QFile interface is not documented in the
1656 porting documentation as of qt-4.0.0-b1.
1657 \endomit
1658
1659 \section1 QFileDialog
1660
1661 The QFileDialog class in Qt 4 has been totally rewritten. It
1662 provides most of the functionality of the old \c QFileDialog
1663 class, but with a different API. Some functionality, such as the
1664 ability to preview files, is expected to be added in a later Qt 4
1665 release.
1666
1667 The old \c QFileDialog, \c QFileIconProvider, and \c QFilePreview
1668 classes has been renamed Q3FileDialog, Q3FileIconProvider, and
1669 Q3FilePreview and have been moved to Qt3Support. You can use them
1670 if you need some functionality not provided yet by the new
1671 QFileDialog class.
1672
1673 The following table lists which functions have been renamed or
1674 removed in Qt 4.
1675
1676 \table
1677 \header \o Old function \o Qt 4 equivalent
1678 \row \o Q3FileDialog::addFilter(const QString &) \o See remark below
1679 \row \o Q3FileDialog::addLeftWidget(QWidget *) \o N/A
1680 \row \o Q3FileDialog::addRightWidget(QWidget *) \o N/A
1681 \row \o Q3FileDialog::addToolButton(QAbstractButton *, bool separator) \o N/A
1682 \row \o Q3FileDialog::addWidgets(QLabel *, QWidget *, QPushButton *) \o N/A
1683 \row \o Q3FileDialog::dir() \o QFileDialog::directory()
1684 \row \o Q3FileDialog::dirPath() \o QFileDialog::directory().path()
1685 \row \o Q3FileDialog::iconProvider() \o N/A
1686 \row \o Q3FileDialog::isContentsPreviewEnabled() \o N/A
1687 \row \o Q3FileDialog::isInfoPreviewEnabled() \o N/A
1688 \row \o Q3FileDialog::previewMode() \o N/A
1689 \row \o Q3FileDialog::rereadDir() \o N/A
1690 \row \o Q3FileDialog::resortDir() \o N/A
1691 \row \o Q3FileDialog::selectAll(bool) \o N/A
1692 \row \o Q3FileDialog::setContentsPreview(QWidget *, Q3FilePreview *) \o N/A
1693 \row \o Q3FileDialog::setContentsPreviewEnabled(bool) \o N/A
1694 \row \o Q3FileDialog::setDir(const QString &) \o QFileDialog::setDirectory(const QString &)
1695 \row \o Q3FileDialog::setFilters(const char **) \o Q3FileDialog::setFilters(const QStringList &)
1696 \row \o Q3FileDialog::setIconProvider(Q3FileIconProvider *) \o N/A
1697 \row \o Q3FileDialog::setInfoPreview(QWidget *, Q3FilePreview *) \o N/A
1698 \row \o Q3FileDialog::setInfoPreviewEnabled(bool) \o N/A
1699 \row \o Q3FileDialog::setPreviewMode(PreviewMode) \o N/A
1700 \row \o Q3FileDialog::setSelectedFilter(const QString &) \o QFileDialog::selectFilter(const QString &)
1701 \row \o Q3FileDialog::setSelectedFilter(int) \o See remark below
1702 \row \o Q3FileDialog::setSelection(const QString &) \o QFileDialog::selectFile(const QString &)
1703 \row \o Q3FileDialog::setShowHiddenFiles(bool) \o showHidden()
1704 \row \o Q3FileDialog::setUrl(const QUrlOperator &) \o N/A
1705 \row \o Q3FileDialog::showHiddenFiles() \o N/A
1706 \row \o Q3FileDialog::url() \o QUrl::fromLocalFile(QFileDialog::directory())
1707 \header \o Old signals \o Qt 4 equivalent
1708 \row \o Q3FileDialog::fileHighlighted(const QString &) \o N/A
1709 \row \o Q3FileDialog::fileSelected(const QString &) \o QFileDialog::filesSelected(const QStringList &)
1710 \row \o Q3FileDialog::dirEntered(const QString &) \o N/A
1711 \row \o Q3FileDialog::filterSelected(const QString &) \o N/A
1712 \endtable
1713
1714 Remarks:
1715
1716 \list 1
1717 \o The Q3FileDialog::addFilter(const QString &) function has no
1718 direct equivalent in the new QFileDialog. Use
1719 QFileDialog::setFilters() instead.
1720
1721 \oldcode
1722 fileDialog->addFilter(tr("JPEG files (*.jpg *.jpeg)"));
1723 \newcode
1724 QStringList filters = fileDialog->filters();
1725 filters << tr("JPEG files (*.jpg *.jpeg)");
1726 fileDialog->setFilters(filters);
1727 \endcode
1728
1729 \o The Q3FileDialog::setSelectedFilter(int) overload has no direct
1730 equivalent in the new QFileDialog. Use
1731 QFileDialog::selectFilter(const QString &) instead.
1732
1733 \oldcode
1734 fileDialog->setSelectedFilter(3);
1735 \newcode
1736 fileDialog->selectFilter(fileDialog->filters().at(3));
1737 \endcode
1738 \endlist
1739
1740 There are no equivalent virtual functions to the two
1741 Q3FileDialog::setSelectedFilter() virtual functions in the QFileDialog
1742 API. In addition, these functions have been renamed or removed, as
1743 described above.
1744
1745 \section1 QFocusData
1746
1747 The QFocusData class is not available in Qt 4. Some of its
1748 functionality is available via the QWidget::nextInFocusChain()
1749 and QWidget::focusNextPrevChild() functions.
1750
1751 \section1 QFocusEvent
1752
1753 The setReason() function is no longer present in Qt 4. It is
1754 necessary to define the reason when constructing a focus event.
1755
1756 \section1 QFont
1757
1758 \c QFont::Script has been moved to QFontDatabase::WritingSystem.
1759
1760 \section1 QFrame
1761
1762 The QFrame class has been made more lightweight in Qt 4, by
1763 reducing the number of properties and virtual functions. The
1764 reduction in the number of virtual functions is significant
1765 because QFrame is the base class of many Qt classes.
1766
1767 Here's an overview of the changes:
1768
1769 \list
1770 \o QFrame no longer has a \c margin property (which wasn't
1771 honored by Qt's layout managers anyway).
1772
1773 \o QFrame no longer has a frameChanged() function, reimplement
1774 QFrame::resizeEvent() instead.
1775
1776 \o QFrame used to have drawFrame(QPainter *) and
1777 drawContents(QPainter *) virtual functions. These are now
1778 gone. In Qt 4, the frame is drawn by the QFrame::paintEvent()
1779 function. If you want to change the way QFrame paints itself,
1780 reimplement this function. To draw the contents of the frame,
1781 reimplement QFrame:paintEvent() and call the base class
1782 implementation of the function before you use the
1783 \l {QWidget::}{contentsRect()} function inherited from QWidget,
1784 to retrieve the rectangle to paint on.
1785
1786 \endlist
1787
1788 To help with porting, the Qt3Support library contains a Q3Frame
1789 class that inherits QFrame and provides a similar API to the old
1790 QFrame class. If you derived from QFrame in your application, you
1791 might want to use Q3Frame as a base class as a first step in the
1792 porting process, and later move on to the new QFrame class.
1793
1794 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1795 a list of QFrame virtual member functions in Qt 3 that are no longer
1796 virtual in Qt 4.
1797
1798 \section1 QFtp
1799
1800 QFtp no longer inherits from QNetworkProtocol. See the
1801 \l{#qnetworkprotocol.section}{section on QNetworkProtocol} for
1802 details.
1803
1804 The old \c QFtp class has been renamed Q3Ftp and moved to the
1805 Qt3Support library.
1806
1807 \target qglayoutiterator.section
1808 \section1 QGLayoutIterator
1809
1810 The QGLayoutIterator class no longer exists in Qt 4. This makes
1811 only a difference if you implemented custom layout managers
1812 (i.e., QLayout subclasses).
1813
1814 The new approach is much simpler: It consists in reimplementing
1815 QLayout::itemAt() and QLayout::takeAt(). These functions operate
1816 on indexes, eliminating the need for a layout iterator class.
1817
1818 \section1 QGrid
1819
1820 The \c QGrid class is now only available as Q3Grid in Qt 4. You
1821 can achieve the same result as \c QGrid by creating a QWidget
1822 with a grid layout:
1823
1824 \oldcode
1825 QGrid *grid = new QGrid(2, Qt::Horizontal);
1826 QPushButton *child1 = new QPushButton(grid);
1827 QPushButton *child2 = new QPushButton(grid);
1828 QPushButton *child3 = new QPushButton(grid);
1829 QPushButton *child4 = new QPushButton(grid);
1830 \newcode
1831 QWidget *grid = new QWidget;
1832 QPushButton *child1 = new QPushButton(grid);
1833 QPushButton *child2 = new QPushButton(grid);
1834 QPushButton *child3 = new QPushButton(grid);
1835 QPushButton *child4 = new QPushButton(grid);
1836
1837 QVBoxLayout *layout = new QVBoxLayout;
1838 layout->addWidget(child1, 0, 0);
1839 layout->addWidget(child2, 0, 1);
1840 layout->addWidget(child3, 1, 0);
1841 layout->addWidget(child4, 1, 1);
1842 grid->setLayout(layout);
1843 \endcode
1844
1845 \section1 QGridLayout
1846
1847 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1848 a list of QGridLayout virtual member functions in Qt 3 that are no
1849 longer virtual in Qt 4.
1850
1851 \section1 QGridView
1852
1853 The \c QGridView class has been renamed Q3GridView and moved to
1854 the Qt3Support library. In Qt 4, we recommend that
1855 you use QTableView or QAbstractItemView for presenting tabular
1856 data.
1857
1858 See \l{Model/View Programming} for an overview of the new item
1859 view classes.
1860
1861 \target qgroupbox.section
1862 \section1 QGroupBox
1863
1864 The QGroupBox class has been redesigned in Qt 4. Many of the
1865 features of the old \c QGroupBox class can be obtained by using
1866 the Q3GroupBox class from the Qt3Support library.
1867
1868 The new QGroupBox is more lightweight. It doesn't attempt to
1869 duplicate functionality already provided by QGridLayout, and it
1870 does not inherit from QFrame. As a result, the following members
1871 have been removed:
1872
1873 \list
1874 \o Q3GroupBox::setColumns(), Q3GroupBox::columns()
1875 \o Q3GroupBox::setOrientation(), Q3GroupBox::orientation()
1876 \o Q3GroupBox::setInsideMargin(), Q3GroupBox::insideMargin()
1877 \o Q3GroupBox::addSpace()
1878 \endlist
1879
1880 Naturally, the \c columns and \c orientation properties have also
1881 been removed.
1882
1883 If you rely on some of the missing functionality in your
1884 application, you can use Q3GroupBox instead of QGroupBox as a
1885 help to porting.
1886
1887 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
1888 a list of QGroupBox virtual member functions in Qt 3 that are no
1889 longer virtual in Qt 4.
1890
1891 \section1 QHBox
1892
1893 The \c QHBox class is now only available as Q3HBox in Qt 4. You
1894 can achieve the same result as \c QHBox by creating a QWidget
1895 with an horizontal layout:
1896
1897 \oldcode
1898 QHBox *hbox = new QHBox;
1899 QPushButton *child1 = new QPushButton(hbox);
1900 QPushButton *child2 = new QPushButton(hbox);
1901 \newcode
1902 QWidget *hbox = new QWidget;
1903 QPushButton *child1 = new QPushButton;
1904 QPushButton *child2 = new QPushButton;
1905
1906 QHBoxLayout *layout = new QHBoxLayout;
1907 layout->addWidget(child1);
1908 layout->addWidget(child2);
1909 hbox->setLayout(layout);
1910 \endcode
1911
1912 Note that child widgets are not automatically placed into the widget's
1913 layout; you will need to manually add each widget to the QHBoxLayout.
1914
1915 \section1 QHeader
1916
1917 The \c QHeader class has been renamed Q3Header and moved to
1918 the Qt3Support library. In Qt 4, it is replaced
1919 by the QHeaderView class.
1920
1921 See \l{Model/View Programming} for an overview of the new item
1922 view classes.
1923
1924 \section1 QHGroupBox
1925
1926 The \c QHGroupBox class has been renamed Q3HGroupBox and moved to
1927 the Qt3Support library.
1928 Qt 4 does not provide a specific replacement class for \c QHGroupBox
1929 since QGroupBox is designed to be a generic container widget. As a
1930 result, you need to supply your own layout for any child widgets.
1931
1932 See \l{#QGroupBox} for more information about porting code that uses
1933 group boxes.
1934
1935 \section1 QHttp
1936
1937 QHttp no longer inherits from QNetworkProtocol. See the See the
1938 \l{#qnetworkprotocol.section}{section on QNetworkProtocol} for
1939 details.
1940
1941 The old \c QHttp, \c QHttpHeader, \c QHttpRequestHeader, and \c
1942 QHttpResponseHeader classes have been renamed Q3Http,
1943 Q3HttpHeader, Q3HttpRequestHeader, and Q3HttpResponseHeader and
1944 have been moved to the Qt3Support library.
1945
1946 \section1 QIconFactory
1947
1948 The QIconFactory class is no longer part of Qt. It has been replaced by
1949 the QIconEngine class.
1950
1951 \section1 QIconSet
1952
1953 The QIconSet class is no longer part of Qt. It has been replaced by
1954 the QIcon class.
1955
1956 \section1 QIconView
1957
1958 The \c QIconView, \c QIconViewItem, \c QIconDrag, and \c
1959 QIconDragItem classes has been renamed Q3IconView,
1960 Q3IconViewItem, Q3IconDrag, and Q3IconDragItem and moved to the
1961 Qt3Support library. New Qt applications should use
1962 QListWidget or its base class QListView instead, and call
1963 QListView::setViewMode(QListView::IconMode) to obtain an "icon
1964 view" look.
1965
1966 See \l{Model/View Programming} for an overview of the new item
1967 view classes.
1968
1969 \omit
1970 ###
1971
1972 \section1 QImage
1973
1974 QImage::fromMimeSource(const QString &) -> qImageFromMimeSource(const QString &)
1975 \endomit
1976
1977 \section1 QImageDrag
1978
1979 The \c QImageDrag class has been renamed Q3ImageDrag and moved to
1980 the Qt3Support library. In Qt 4, use QMimeData
1981 instead and call QMimeData::setImage() to set the image.
1982
1983 See \l{Porting to Qt 4 - Drag and Drop} for a comparison between
1984 the drag and drop APIs in Qt 3 and Qt 4.
1985
1986 \section1 QImageIO
1987
1988 The \c QImageIO class has been split into two classes:
1989 QImageReader and QImageWriter. The table below shows the
1990 correspondance between the two APIs:
1991
1992 \table
1993 \header \o Qt 3 function \o Qt 4 equivalents
1994 \row \o QImageIO::description() \o QImageWriter::text()
1995 \row \o QImageIO::fileName() \o QImageReader::fileName() and QImageWriter::fileName()
1996 \row \o QImageIO::format() \o QImageReader::format() and QImageWriter::format()
1997 \row \o QImageIO::gamma() \o QImageWriter::gamma()
1998 \row \o QImageIO::image() \o Return value of QImageReader::read()
1999 \row \o QImageIO::inputFormats() \o QImageReader::supportedImageFormats()
2000 \row \o QImageIO::ioDevice() \o QImageReader::device() and QImageWriter::device()
2001 \row \o QImageIO::outputFormats() \o QImageWriter::supportedImageFormats()
2002 \row \o QImageIO::parameters() \o N/A
2003 \row \o QImageIO::quality() \o QImageWriter::quality()
2004 \row \o QImageIO::read() \o QImageReader::read()
2005 \row \o QImageIO::setDescription() \o QImageWriter::setText()
2006 \row \o QImageIO::setFileName() \o QImageReader::setFileName() and QImageWriter::setFileName()
2007 \row \o QImageIO::setFormat() \o QImageReader::setFormat() and QImageWriter::setFormat()
2008 \row \o QImageIO::setGamma() \o QImageWriter::setGamma()
2009 \row \o QImageIO::setIODevice() \o QImageReader::setDevice() and QImageWriter::setDevice()
2010 \row \o QImageIO::setImage() \o Argument to QImageWriter::write()
2011 \row \o QImageIO::setParameters() \o N/A
2012 \row \o QImageIO::setQuality() \o QImageWriter::setQuality()
2013 \row \o QImageIO::setStatus() \o N/A
2014 \row \o QImageIO::status() \o QImageReader::error() and QImageWriter::error()
2015 \row \o QImageIO::write() \o QImageWriter::write()
2016 \endtable
2017
2018 \section1 QIntCache<T>
2019
2020 QIntCache<T> has been moved to Qt3Support. It has been replaced
2021 by QCache<int, T>.
2022
2023 For details, read the \l{#qcache.section}{section on QCache<T>},
2024 mentally substituting \c int for QString.
2025
2026 \section1 QIntDict<T>
2027
2028 QIntDict<T> and QIntDictIterator<T> have been moved to
2029 Qt3Support. They have been replaced by the more modern QHash<Key,
2030 T> and QMultiHash<Key, T> classes and their associated iterator
2031 classes.
2032
2033 When porting old code that uses QIntDict<T> to Qt 4, there are
2034 four classes that you can use:
2035
2036 \list
2037 \o QMultiHash<int, T *>
2038 \o QMultiHash<int, T>
2039 \o QHash<int, T *>
2040 \o QHash<int, T>
2041 \endlist
2042
2043 For details, read the \l{#qdict.section}{section on QDict<T>},
2044 mentally substituting \c int for QString.
2045
2046 \target qiodevice.section
2047 \section1 QIODevice
2048
2049 The QIODevice class's API has been simplified to make it easier
2050 to subclass and to make it work more smoothly with asynchronous
2051 devices such as QTcpSocket and QProcess.
2052
2053 The following virtual functions have changed name or signature:
2054
2055 \table
2056 \header \o Qt 3 function \o Comment
2057 \row \o QIODevice::at() const \o Renamed QIODevice::pos().
2058 \row \o QIODevice::at(Offset) \o Renamed QIODevice::seek().
2059 \row \o QIODevice::open(int) \o The parameter is now of type QIODevice::OpenMode.
2060 \row \o QIODevice::readBlock(char *, Q_ULONG) \o QIODevice::read(char *, qint64)
2061 \row \o QIODevice::writeBlock(const char *, Q_ULONG) \o QIODevice::write(const char *, qint64)
2062 \endtable
2063
2064 \note QIODevice::open(QIODevice::OpenMode) is no longer pure virtual.
2065
2066 The following functions are no longer virtual or don't exist anymore:
2067
2068 \table
2069 \row \o QIODevice::getch() \o Renamed QIODevice::getChar() and implemented in terms of QIODevice::readData().
2070 \row \o QIODevice::putch(int) \o Renamed QIODevice::putChar() and implemented in terms of QIODevice::writeData().
2071 \row \o QIODevice::readAll() \o Implemented in terms of QIODevice::readData().
2072 \row \o QIODevice::readLine(char *, Q_ULONG) \o Implemented in terms of QIODevice::readData()
2073 \row \o QIODevice::ungetch(int) \o Renamed QIODevice::ungetChar() and simulated using an internal unget buffer.
2074 \endtable
2075
2076 The \c IO_xxx flags have been revised, and the protected setFlags()
2077 function removed. Most of the flags have been
2078 eliminated because errors are best handled by implementing certain
2079 functions in QIODevice subclasses rather than through the base classes.
2080 The file access flags, such as \c IO_ReadOnly and \c IO_WriteOnly, have
2081 been moved to the QIODevice class to avoid polluting the global
2082 namespace. The table below shows the correspondence between the
2083 Qt 3 \c IO_xxx flags and the Qt 4 API:
2084
2085 \table
2086 \header \o Qt 3 constant \o Qt 4 equivalent
2087 \row \o IO_Direct \o Use !QIODevice::isSequential() instead (notice the \e not).
2088 \row \o IO_Sequential \o Use QIODevice::isSequential() instead.
2089 \row \o IO_Combined \o N/A
2090 \row \o IO_TypeMask \o N/A
2091 \row \o IO_Raw \o QIODevice::Unbuffered
2092 \row \o IO_Async \o N/A
2093 \row \o IO_ReadOnly \o QIODevice::ReadOnly
2094 \row \o IO_WriteOnly \o QIODevice::WriteOnly
2095 \row \o IO_ReadWrite \o QIODevice::ReadWrite
2096 \row \o IO_Append \o QIODevice::Append
2097 \row \o IO_Truncate \o QIODevice::Truncate
2098 \row \o IO_Translate \o QIODevice::Text
2099 \row \o IO_ModeMask \o N/A
2100 \row \o IO_Open \o Use QIODevice::isOpen() instead.
2101 \row \o IO_StateMask \o N/A
2102 \row \o IO_Ok \o N/A
2103 \row \o IO_ReadError \o N/A
2104 \row \o IO_WriteError \o N/A
2105 \row \o IO_FatalError \o N/A
2106 \row \o IO_ResourceError \o N/A
2107 \row \o IO_OpenError \o N/A
2108 \row \o IO_ConnectError \o N/A
2109 \row \o IO_AbortError \o N/A
2110 \row \o IO_TimeOutError \o N/A
2111 \row \o IO_UnspecifiedError \o N/A
2112 \endtable
2113
2114 \section1 QIODeviceSource
2115
2116 The QIODeviceSource class was used internally in Qt 2.x in
2117 conjunction with QImageConsumer. It was obsoleted in Qt 3.0.
2118 \input porting/porting4-obsoletedmechanism.qdocinc
2119
2120 \section1 QLabel
2121
2122 QLabel doesn't enable word-wrap automatically anymore when rich
2123 text is used. You can enable it by calling
2124 QLabel::setWordWrap() or by setting the
2125 \l{QLabel::wordWrap}{wordWrap} property. The reason for this
2126 change is that the old behavior was confusing to many users.
2127
2128 Also, QLabel no longer offers an \c autoResize property. Instead,
2129 you can call QWidget::setFixedSize() on the label, with
2130 QLabel::sizeHint() as the argument, whenever you change the
2131 contents of the QLabel.
2132
2133 See also \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions}
2134 for a list of QLabel virtual member functions in Qt 3 that are no
2135 longer virtual in Qt 4.
2136
2137 \section1 QLayout
2138
2139 In Qt 4, margins are always handled by layouts; there is no
2140 QLayout::setSupportsMargin() function anymore.
2141
2142 The deleteAllItems() function is now only available if
2143 \c QT3_SUPPORT is defined. If you maintain a QList of layout
2144 items, you can use qDeleteAll() to remove all the items in one
2145 go.
2146
2147 In Qt 3, it was possible to change the resizing behavior for layouts
2148 in top-level widgets by adjusting the layout's \c resizeMode property.
2149 In Qt 4, this property has been replaced by the QLayout::sizeConstraint
2150 property which provides more control over how the layout behaves when
2151 resized.
2152
2153 See also the \l{#qlayoutiterator.section}{section on
2154 QLayoutIterator} and the \l{#qglayoutiterator.section}{section on
2155 QGLayoutIterator}.
2156
2157 \target qlayoutiterator.section
2158 \section1 QLayoutIterator
2159
2160 The QLayoutIterator class is obsoleted in Qt 4. It is available
2161 only if \c QT3_SUPPORT is defined. It can be replaced by the
2162 QLayout::itemAt() and QLayout::takeAt() functions, which operate
2163 on indexes.
2164
2165 \oldcode
2166 QLayoutIterator it = layout()->iterator();
2167 QLayoutItem *child;
2168 while ((child = it.current()) != 0) {
2169 if (child->widget() == myWidget) {
2170 it.takeCurrent();
2171 return;
2172 ++it;
2173 }
2174 \newcode
2175 int i = 0;
2176 QLayoutItem *child;
2177 while ((child = layout()->itemAt(i)) != 0) {
2178 if (child->widget() == myWidget) {
2179 layout()->takeAt(i);
2180 return;
2181 }
2182 ++i;
2183 }
2184 \endcode
2185
2186 \section1 QLineEdit
2187
2188 See \l{#properties}{Properties} for a list of QLineEdit
2189 properties in Qt 3 that have changed in Qt 4.
2190
2191 The default value of QLineEdit's \l{QLineEdit::dragEnabled()}{dragEnabled}
2192 property was \c true in Qt 3. In Qt 4, the default value is \c false.
2193
2194 Note that QLineEdit in Qt 4 is no longer a subclass of QFrame.
2195 If you need to visually style a line edit with a frame, we recommend
2196 either using a QFrame as a container for a QLineEdit or customizing
2197 the line edit with a \l{Qt Style Sheets}{style sheet}.
2198
2199 \section1 QListBox
2200
2201 The \c QListBox, \c QListBoxItem, \c QListBoxText, and \c
2202 QListBoxPixmap classes have been renamed Q3ListBox,
2203 Q3ListBoxItem, Q3ListBoxText, and Q3ListBoxPixmap and have been
2204 moved to the Qt3Support library. New Qt applications
2205 should use QListWidget or its base class QListView instead.
2206
2207 See \l{Model/View Programming} for an overview of the new item
2208 view classes.
2209
2210 \section1 QListView
2211
2212 The \c QListView, \c QListViewItem, \c QCheckListItem, and \c
2213 QListViewItemIterator classes have been renamed Q3ListView,
2214 Q3ListViewItem, Q3CheckListItem, and Q3ListViewItemIterator, and
2215 have been moved to the Qt3Support library. New Qt
2216 applications should use one of the following four classes
2217 instead: QTreeView or QTreeWidget for tree-like structures;
2218 QListWidget or the new QListView class for one-dimensional lists.
2219
2220 See \l{Model/View Programming} for an overview of the new item
2221 view classes.
2222
2223 \section1 QLocalFs
2224
2225 The \c QLocalFs class is no longer part of the public Qt API. It
2226 has been renamed Q3LocalFs and moved to Qt3Support. Use QDir,
2227 QFileInfo, or QFile instead.
2228
2229 \section1 QMainWindow
2230
2231 The QMainWindow class has been redesigned in Qt 4 to provide a
2232 more modern look and feel and more flexibility. The API has
2233 changed to reflect that. The old \c QMainWindow class has been
2234 renamed Q3MainWindow and moved to Qt3Support. See the QMainWindow
2235 class documentation for details.
2236
2237 \omit ### More detail \endomit
2238
2239 \target qmemarray.section
2240 \section1 QMemArray<T>
2241
2242 QMemArray<T> has been moved to Qt3Support. It has been replaced
2243 by the QVector<T> class.
2244
2245 The following table summarizes the API differences between the
2246 two classes.
2247
2248 \table
2249 \row \o QMemArray::assign(const QMemArray<T> &) \o QVector::operator=()
2250 \row \o QMemArray::assign(const T *, uint) \o See remark below
2251 \row \o QMemArray::duplicate(const QMemArray &) \o QVector::operator=()
2252 \row \o QMemArray::duplicate(const T *, uint) \o See remark below
2253 \row \o QMemArray::setRawData(const T *, uint) \o N/A
2254 \row \o QMemArray::resetRawData(const T *, uint) \o N/A
2255 \row \o QMemArray::find(const T &, uint) \o QVector::indexOf(const T &, int)
2256 \row \o QMemArray::contains(const T &) \o QVector::count(const T &)
2257 \row \o QMemArray::sort() \o \l qSort()
2258 \row \o QMemArray::bsearch(const T &d) \o \l qBinaryFind()
2259 \row \o QMemArray::at(uint) \o QVector::operator[]()
2260 \row \o QMemArray::operator const T *() \o QVector::constData()
2261 \endtable
2262
2263 Remarks:
2264
2265 \list 1
2266 \o QMemArray::assign(const T *, uint) and QMemArray::duplicate(const T *, uint)
2267 can be replaced by QVector::resize() and qCopy().
2268
2269 \oldcode
2270 QMemArray<QSize> array;
2271 ...
2272 array.assign(data, size);
2273 \newcode
2274 QVector<QSize> vector;
2275 ...
2276 vector.resize(size);
2277 qCopy(data, data + size, vector.begin());
2278 \endcode
2279
2280 \o QMemArray is an explicitly shared class, whereas QVector is
2281 implicitly shared. See \l{Explicit Sharing} for more
2282 information.
2283 \endlist
2284
2285 \section1 QMenuBar
2286
2287 In Qt 3, QMenuBar inherited from QFrame and QMenuData; in Qt 4, it is
2288 a direct subclass of QWidget. Applications that provided customized
2289 menu bars will need to take advantage of the styling features described
2290 in the \l{Qt Style Sheets} document.
2291
2292 It is not possible to add widgets to menu bars in Qt 4.
2293
2294 \section1 QMenuData
2295
2296 In Qt 4, the QMenu class provides a menu widget that can be used in all
2297 the places where menus are used in an application. Unlike \c QMenuData,
2298 QMenu is designed around the concept of actions, provided by the QAction
2299 class, instead of the identifiers used in Qt 3.
2300
2301 In Qt 3, it was possible to insert widgets directly into menus by using
2302 a specific \c QMenuData::insertItem() overload. In Qt 4.2 and later,
2303 the QWidgetAction class can be used to wrap widgets for use in Qt 4's
2304 action-based APIs.
2305
2306 \section1 QMessageBox
2307
2308 The QMessageBox::iconPixmap() function used to return a "const
2309 QPixmap *". In Qt 4, it returns a QPixmap.
2310
2311 \section1 QMimeSourceFactory
2312
2313 The \c QMimeSourceFactory has been renamed Q3MimeSourceFactory
2314 and moved to the Qt3Support library. New Qt applications should
2315 use Qt 4's \l{Resource System} instead.
2316
2317 \section1 QMovie
2318
2319 The QMovie API has been revised in Qt 4 to make it more
2320 consistent with the other Qt classes (notably QImageReader). The
2321 table below summarizes the changes.
2322
2323 \table
2324 \header \o Qt 3 function \o Qt 4 equivalent
2325 \row \o QMovie::connectResize() \o Connect to QMovie::resized()
2326 \row \o QMovie::connectStatus() \o Connect to QMovie::stateChanged()
2327 \row \o QMovie::connectUpdate() \o Connect to QMovie::updated()
2328 \row \o QMovie::disconnectResize() \o Disconnect from QMovie::resized()
2329 \row \o QMovie::disconnectStatus() \o Disconnect from QMovie::stateChanged()
2330 \row \o QMovie::disconnectUpdate() \o Disconnect from QMovie::updated()
2331 \row \o QMovie::finished() \o Use QMovie::state() instead
2332 \row \o QMovie::frameImage() \o Use QMovie::currentImage() instead
2333 \row \o QMovie::frameNumber() \o Use QMovie::currentFrameNumber() instead
2334 \row \o QMovie::framePixmap() \o Use QMovie::currentPixmap() instead
2335 \row \o QMovie::getValidRect() \o Use frameRect() instead
2336 \row \o QMovie::isNull() \o Use QMovie::isValid() instead
2337 \row \o QMovie::pause() \o Use QMovie::setPaused(true) instead
2338 \row \o QMovie::paused() \o Use QMovie::state() instead
2339 \row \o QMovie::pushData() \o N/A
2340 \row \o QMovie::pushSpace() \o N/A
2341 \row \o QMovie::restart() \o Use QMovie::jumpToFrame(0) instead
2342 \row \o QMovie::running() \o Use QMovie::state() instead
2343 \row \o QMovie::step() \o Use QMovie::jumpToFrame() and QMovie::setPaused() instead
2344 \row \o QMovie::step() \o Use QMovie::jumpToNextFrame() instead
2345 \row \o QMovie::steps() \o Use QMovie::currentFrameNumber() and QMovie::frameCount() instead
2346 \row \o QMovie::unpause() \o Use QMovie::setPaused(false) instead
2347 \endtable
2348
2349 \section1 QMultiLineEdit
2350
2351 The \c QMultiLineEdit class in Qt 3 was a convenience QTextEdit
2352 subclass that provided an interface compatible with Qt 2's
2353 QMultiLineEdit class. In Qt 4, it is called Q3MultiLineEdit, it
2354 inherits Q3TextEdit, and it is part of Qt3Support. Use QTextEdit
2355 in new code.
2356
2357 \target qnetworkprotocol.section
2358 \section1 QNetworkProtocol
2359
2360 The QNetworkProtocol, QNetworkProtocolFactoryBase,
2361 QNetworkProtocolFactory<T>, and QNetworkOperation classes are no
2362 longer part of the public Qt API. They have been renamed
2363 Q3NetworkProtocol, Q3NetworkProtocolFactoryBase,
2364 Q3NetworkProtocolFactory<T>, and Q3NetworkOperation and have been
2365 moved to the Qt3Support library.
2366
2367 In Qt 4 applications, you can use classes like QFtp and
2368 QNetworkAccessManager directly to perform file-related actions on
2369 a remote host.
2370
2371 \section1 QObject
2372
2373 QObject::children() now returns a QObjectList instead of a
2374 pointer to a QObjectList. See also the comments on QObjectList
2375 below.
2376
2377 Use QObject::findChildren() (or qFindChildren() if you need MSVC 6
2378 compatibility) instead of QObject::queryList(). For example:
2379
2380 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 18
2381
2382 QObject::killTimers() has been removed because it was unsafe to
2383 use in subclass. (A subclass normally doesn't know whether the
2384 base class uses timers or not.)
2385
2386 The \c QObject::name property has been renamed
2387 QObject::objectName.
2388
2389 \c QObject::objectTrees() has been removed. If you are primarly
2390 interested in widgets, use QApplication::allWidgets() or
2391 QApplication::topLevelWidgets().
2392
2393 \section1 QObjectDictionary
2394
2395 The QObjectDictionary class is a synonym for
2396 QAsciiDict<QMetaObject>. See the \l{#qasciidict.section}{section
2397 on QAsciiDict<T>}.
2398
2399 \section1 QObjectList
2400
2401 In Qt 3, the QObjectList class was a typedef for
2402 QPtrList<QObject>. In Qt 4, it is a typedef for QList<QObject *>.
2403 See the \l{#qptrlist.section}{section on QPtrList<T>}.
2404
2405 \section1 QPaintDevice
2406
2407 To reimplement painter backends one previously needed to reimplement
2408 the virtual function QPaintDevice::cmd(). This function is taken out
2409 and should is replaced with the function QPaintDevice::paintEngine()
2410 and the abstract class QPaintEngine. QPaintEngine provides virtual
2411 functions for all drawing operations that can be performed on a
2412 painter backend.
2413
2414 bitBlt() and copyBlt() are now only compatibility functions. Use
2415 QPainter::drawPixmap() instead.
2416
2417 \section1 QPaintDeviceMetrics
2418
2419 All functions that used to be provided by the \c
2420 QPaintDeviceMetrics class have now been moved to QPaintDevice.
2421
2422 \oldcode
2423 QPaintDeviceMetrics metrics(widget);
2424 int deviceDepth = metrics.depth();
2425 \newcode
2426 int deviceDepth = widget->depth();
2427 \endcode
2428
2429 For compatibility, the old \c QPaintDeviceMetrics class has been
2430 renamed Q3PaintDeviceMetrics and moved to Qt3Support.
2431
2432 \section1 QPainter
2433
2434 The QPainter class has undergone some changes in Qt 4 because of
2435 the way rectangles are drawn. In Qt 4, the result of drawing a
2436 QRect with a pen width of 1 pixel is 1 pixel wider and 1 pixel
2437 taller than in Qt 3.
2438
2439 For compatibility, we provide a Q3Painter class in Qt3Support
2440 that provides the old semantics. See the Q3Painter documentation
2441 for details and for the reasons why we had to make this change.
2442
2443 The \l{http://doc.qt.nokia.com/3.3/qpainter.html#CoordinateMode-enum}{QPainter::CoordinateMode}
2444 enum has been removed in Qt 4. All clipping
2445 operations are now defined using logical coordinates and are subject
2446 to transformation operations.
2447
2448 The
2449 \l{http://doc.qt.nokia.com/3.3/qpainter.html#RasterOP-enum}{QPainter::RasterOP}
2450 enum has been replaced with QPainter::CompositionMode.
2451
2452 \section1 QPicture
2453
2454 In Qt 3, a QPicture could be saved in the SVG file format. In Qt
2455 4, the SVG support is provided by the QtSvg module, which
2456 includes classes for \e displaying the contents of SVG files.
2457
2458 If you would like to generate SVG files, you can use the Q3Picture
2459 compatibility class or the QSvgGenerator class introduced in Qt 4.3.
2460
2461 \section1 QPixmap
2462
2463 The mask() function has been changed to return a reference to a QBitmap
2464 rather than a pointer. As a result, it is no longer possible simply to
2465 test for a null pointer when determining whether a pixmap has a mask.
2466 Instead, you need to explicitly test whether the mask bitmap is null or
2467 not.
2468
2469 \oldcode
2470 if (pixmap.mask())
2471 widget->setMask(*pixmap.mask());
2472 \newcode
2473 if (!pixmap.mask().isNull())
2474 widget->setMask(pixmap.mask());
2475 \endcode
2476
2477 The \c QPixmap::setOptimization() and \c QPixmap::setDefaultOptimization()
2478 mechanism is no longer available in Qt 4.
2479
2480\omit
2481 QPixmap::fromMimeSource(const QString &) -> qPixmapFromMimeSource(const QString &)
2482\endomit
2483
2484 \section1 QPointArray
2485
2486 The \c QPointArray class has been renamed QPolygon in Qt 4 and
2487 has undergone significant changes. In Qt 3, \c QPointArray
2488 inherited from QMemArray<QPoint>. In Qt 4, QPolygon inherits from
2489 QVector<QPoint>. Everything mentioned in the
2490 \l{#qmemarray.section}{section on QMemArray<T>} apply for
2491 QPointArray as well.
2492
2493 The Qt3Support library contains a Q3PointArray class
2494 that inherits from QPolygon and provides a few functions that
2495 existed in \c QPointArray but no longer exist in QPolygon. These
2496 functions include Q3PointArray::makeArc(),
2497 Q3PointArray::makeEllipse(), and Q3PointArray::cubicBezier().
2498 In Qt 4, we recommend that you use QPainterPath for representing
2499 arcs, ellipses, and Bezier curves, rather than QPolygon.
2500
2501 The QPolygon::setPoints() and QPolygon::putPoints() functions
2502 return \c void in Qt 4. The corresponding Qt 3 functions returned
2503 a \c bool indicating whether the array was successfully resized
2504 or not. This can now be checked by checking QPolygon::size()
2505 after the call.
2506
2507\omit
2508 X11 Specific:
2509
2510 ::appDisplay() -> QX11Info::display()
2511 QPaintDevice::x11Display() -> QX11Info::display()
2512 QPaintDevice::x11AppDisplay() -> QX11Info::display()
2513 QPaintDevice::x11Screen() -> QX11Info::appScreen()
2514 QPaintDevice::x11AppScreen() -> ???
2515 QPaintDevice::x11Depth() -> QX11Info::appDepth()
2516 QPaintDevice::x11ColorMap() -> QX11Info::appColorMap()
2517 QPaintDevice::x11DefaultColorMap() -> ???
2518 QPaintDevice::x11Visual() -> QX11Info::appVisual()
2519 QPaintDevice::x11DefaultVisual() -> ???
2520
2521 QPaintDevice::x11AppDpiX() -> QX11Info::appDpiX()
2522 QPaintDevice::x11AppDpiY() -> QX11Info::appDpiY()
2523 QPaintDevice::x11SetAppDpiX() -> QX11Info::setAppDpiX()
2524 QPaintDevice::x11SetAppDpiY() -> QX11Info::setAppDpiY()
2525
2526 QPaintDevice::x11AppDepth() -> ???
2527 QPaintDevice::x11AppCells() -> ???
2528 QPaintDevice::x11AppRootWindow() -> ???
2529 QPaintDevice::x11AppColorMap() -> ???
2530 QPaintDevice::x11AppDefaultColorMap() -> ???
2531 QPaintDevice::x11AppVisual() -> ???
2532 QPaintDevice::x11AppDefaultVisual() -> ???
2533
2534 End of X11 Specific
2535\endomit
2536
2537 \section1 QPopupMenu
2538
2539 For most purposes, QPopupMenu has been replaced by QMenu in Qt
2540 4. For compatibility with older applications, Q3PopupMenu provides
2541 the old API and features that are specific to pop-up menus. Note
2542 that, when using Q3PopupMenu, the menu's actions must be \l
2543 {Q3Action}s.
2544
2545 In Qt 3, it was common practice to add entries to pop-up menus using the
2546 insertItem() function, maintaining identifiers for future use; for
2547 example, to dynamically change menu items.
2548 In Qt 4, menu entries are completely represented
2549 by actions for consistency with other user interface components, such as
2550 toolbar buttons. Create new menus with the QMenu class, and use the
2551 overloaded QMenu::addAction() functions to insert new entries.
2552 If you need to manage a set of actions created for a particular menu,
2553 we suggest that you construct a QActionGroup and add them to that.
2554
2555 The \l{Main Window Examples} provided
2556 show how to use Qt's action system to construct menus, toolbars, and other
2557 common user interface elements.
2558
2559 \section1 QPrinter
2560
2561 The QPrinter class now expects printing to be set up from a
2562 QPrintDialog.
2563
2564 \section1 QProcess
2565
2566 The QProcess class has undergone major improvements in Qt 4. It
2567 now inherits QIODevice, which makes it possible to combine
2568 QProcess with a QTextStream or a QDataStream.
2569
2570 The old \c QProcess class has been renamed Q3Process and moved to
2571 the Qt3Support library.
2572
2573 \section1 QProgressBar
2574
2575 The QProgressBar API has been significantly improved in Qt 4. The
2576 old \c QProgressBar API is available as Q3ProgressBar in the
2577 Qt3Support library.
2578
2579 \section1 QProgressDialog
2580
2581 The QProgressDialog API has been significantly improved in Qt 4.
2582 The old \c QProgressDialog API is available as Q3ProgressDialog
2583 in the Qt3Support library.
2584
2585 See \l{#properties}{Properties} for a list of QProgressDialog
2586 properties in Qt 3 that have changed in Qt 4.
2587
2588 \section1 QPtrCollection<T>
2589
2590 The \c QPtrCollection<T> abstract base class has been renamed
2591 Q3PtrCollection<T> moved to the Qt3Support library.
2592 There is no direct equivalent in Qt 4.
2593
2594 \omit
2595 ###
2596 The QPtrCollection entry is unsatisfactory. The xref is missing
2597 its list and saying "no direct equivalent" with so suggestions
2598 seems feeble.
2599 \endomit
2600
2601 See \l{Container Classes} for a list of Qt 4 containers.
2602
2603 \section1 QPtrDict<T>
2604
2605 \c QPtrDict<T> and \c QPtrDictIterator<T> have been renamed
2606 Q3PtrDict<T> and Q3PtrDictIterator<T> and have been moved to the
2607 Qt3Support library. They have been replaced by the
2608 more modern QHash<Key, T> and QMultiHash<Key, T> classes and
2609 their associated iterator classes.
2610
2611 When porting old code that uses Q3PtrDict<T> to Qt 4, there are
2612 four classes that you can use:
2613
2614 \list
2615 \o QMultiHash<void *, T *>
2616 \o QMultiHash<void *, T>
2617 \o QHash<void *, T *>
2618 \o QHash<void *, T>
2619 \endlist
2620
2621 (You can naturally use other types than \c{void *} for the key
2622 type, e.g. \c{QWidget *}.)
2623
2624 To port Q3PtrDict<T> to Qt 4, read the \l{#qdict.section}{section
2625 on QDict<T>}, mentally substituting \c{void *} for QString.
2626
2627 \target qptrlist.section
2628 \section1 QPtrList<T>
2629
2630 QPtrList<T>, QPtrListIterator<T>, and QPtrListStdIterator<T> have
2631 been moved to the Qt3Support library. They have been
2632 replaced by the more modern QList and QLinkedList classes and
2633 their associated iterator classes.
2634
2635 When porting to Qt 4, you have the choice of using QList<T> or
2636 QLinkedList<T> as alternatives to QValueList<T>. QList<T> has an
2637 index-based API and provides very fast random access
2638 (QList::operator[]), whereas QLinkedList<T> has an iterator-based
2639 API.
2640
2641 The following table summarizes the API differences between
2642 QPtrList<T> and QList<T *>:
2643
2644 \table
2645 \header \o QPtrList function \o QList equivalent
2646 \row \o QPtrList::contains(const T *) \o QList::count(T *)
2647 \row \o QPtrList::containsRef(const T *) \o QList::count(T *)
2648 \row \o QPtrList::find(const T *) \o See remark below
2649 \row \o QPtrList::findRef(const T *) \o See remark below
2650 \row \o QPtrList::getFirst() \o QList::first()
2651 \row \o QPtrList::getLast() \o QList::last()
2652 \row \o QPtrList::inSort(const T *) \o N/A
2653 \row \o QPtrList::remove(const T *) \o QList::removeAll(T *)
2654 \row \o QPtrList::remove(uint) \o QList::removeAt(int)
2655 \row \o QPtrList::removeNode(QLNode *) \o N/A
2656 \row \o QPtrList::removeRef(const T *) \o QList::removeAll(T *)
2657 \row \o QPtrList::sort() \o See remark below
2658 \row \o QPtrList::takeNode(QLNode *) \o N/A
2659 \row \o QPtrList::toVector(QGVector *) \o See remark below
2660 \endtable
2661
2662 Remarks:
2663
2664 \list 1
2665 \o QPtrList::toVector(QGVector *) can be replaced by
2666 QVector::resize() and qCopy().
2667
2668 \oldcode
2669 QPtrList<QWidget> list;
2670 ...
2671 QPtrVector<QWidget> vector;
2672 list.toVector(&vector);
2673 \newcode
2674 QList<QWidget *> list;
2675 ...
2676 QVector<QWidget *> vector;
2677 vector.resize(list.size());
2678 qCopy(list.begin(), list.end(), vector.begin());
2679 \endcode
2680
2681 \o QPtrList::sort() relied on the virtual compareItems() to
2682 sort items. In Qt 4, you can use \l qSort() instead and pass
2683 your "compare item" function as an argument.
2684
2685 \o QPtrList::find(const T *) returns an iterator, whereas
2686 QList::indexOf(T *) returns an index. To convert an index
2687 into an iterator, add the index to QList::begin().
2688
2689 \o QPtrList::removeFirst() and QPtrList::removeLast() return a \c
2690 bool that indicates whether the element was removed or not.
2691 The corresponding QList functions return \c void. You can
2692 achieve the same result by calling QList::isEmpty() before
2693 attempting to remove an item.
2694 \endlist
2695
2696 If you use QPtrList's auto-delete feature (by calling
2697 QPtrList::setAutoDelete(true)), you need to do some more work.
2698 You have two options: Either you call \c delete yourself whenever
2699 you remove an item from the container, or you can use QList<T>
2700 instead of QList<T *> (i.e. store values directly instead of
2701 pointers to values). Here, we'll see when to call \c delete.
2702
2703 \omit
2704 (See \l{What's Wrong with Auto-Delete} for an explanation of why
2705 the Qt 4 containers don't offer that feature.)
2706 \endomit
2707
2708 The following table summarizes the idioms that you need to watch
2709 out for if you want to call \c delete yourself.
2710
2711 \table
2712 \header \o QPtrList idiom \o QList idiom
2713 \row
2714 \o
2715 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 19
2716 \o
2717 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 20
2718 \row
2719 \o
2720 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 21
2721 \o
2722 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 22
2723 \row
2724 \o
2725 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 23
2726 \o
2727 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 24
2728 \row
2729 \o
2730 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 25
2731 \o
2732 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 26
2733 \row
2734 \o
2735 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 27
2736 \o
2737 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 28
2738 \row
2739 \o
2740 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 29
2741 (removes the current item)
2742
2743 \o
2744 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 30
2745 \row
2746 \o
2747 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 31
2748
2749 (also called from QPtrList's destructor)
2750
2751 \o
2752 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 32
2753
2754 In 99% of cases, the following idiom also works:
2755
2756 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 33
2757
2758 However, it may lead to crashes if \c list is referenced from
2759 the value type's destructor, because \c list contains
2760 dangling pointers until clear() is called.
2761 \endtable
2762
2763 Be aware that QPtrList's destructor automatically calls clear().
2764 If you have a QPtrList data member in a custom class and use the
2765 auto-delete feature, you will need to call \c delete on all the
2766 items in the container from your class destructor to avoid a
2767 memory leak.
2768
2769 QPtrList had the concept of a "current item", which could be used
2770 for traversing the list without using an iterator. When porting
2771 to Qt 4, you can use the Java-style QListIterator<T *> (or
2772 QMutableListIterator<T *>) class instead. The following table
2773 summarizes the API differences:
2774
2775 \table
2776 \header \o QPtrList function \o QListIterator equivalent
2777 \row \o QPtrList::at() \o N/A
2778 \row \o QPtrList::current() \o QMutableListIterator::value()
2779 \row \o QPtrList::currentNode() \o N/A
2780 \row \o QPtrList::findNext(const T *) \o QListIterator::findNext(const T *)
2781 \row \o QPtrList::findNextRef(const T *) \o QListIterator::findNext(const T *)
2782 \row \o QPtrList::first() \o QPtrList::toFront()
2783 \row \o QPtrList::last() \o QPtrList::toBack()
2784 \row \o QPtrList::next() \o QPtrList::next()
2785 \row \o QPtrList::prev() \o QPtrList::previous()
2786 \row \o QPtrList::remove() \o QMutableListIterator::remove()
2787 \row \o QPtrList::take() \o QMutableListIterator::remove()
2788 \endtable
2789
2790 Be aware that QListIterator has a different way of iterating than
2791 QPtrList. A typical loop with QPtrList looks like this:
2792
2793 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 34
2794
2795 Here's the equivalent QListIterator loop:
2796
2797 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 35
2798
2799 Finally, QPtrListIterator<T> must also be ported. There are no
2800 fewer than four iterator classes that can be used as a
2801 replacement: QList::const_iterator, QList::iterator,
2802 QListIterator, and QMutableListIterator. The most straightforward
2803 class to use when porting is QMutableListIterator<T *> (if you
2804 modify the list through the iterator) or QListIterator<T *> (if
2805 you don't). The following table summarizes the API differences:
2806
2807 \table
2808 \header \o QPtrListIterator function \o Qt 4 equivalent
2809 \row \o QPtrListIterator::atFirst() \o !QListIterator::hasPrevious() (notice the \c{!})
2810 \row \o QPtrListIterator::atLast() \o !QListIterator::hasNext() (notice the \c{!})
2811 \row \o QPtrListIterator::count() \o QList::count() or QList::size()
2812 \row \o QPtrListIterator::current() \o QMutableListIterator::value()
2813 \row \o QPtrListIterator::isEmpty() \o QList::isEmpty()
2814 \row \o QPtrListIterator::toFirst() \o QListIterator::toFront()
2815 \row \o QPtrListIterator::toLast() \o QListIterator::toBack()
2816 \row \o QPtrListIterator::operator() \o QMutableListIterator::value()
2817 \row \o QPtrListIterator::operator*() \o QMutableListIterator::value()
2818 \endtable
2819
2820 Again, be aware that QListIterator has a different way of
2821 iterating than QPtrList. A typical loop with QPtrList looks like
2822 this:
2823
2824 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 36
2825
2826 Here's the equivalent QListIterator loop:
2827
2828 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 37
2829
2830 Finally, QPtrListStdIterator<T> must also be ported. This is
2831 easy, because QList also provides STL-style iterators
2832 (QList::iterator and QList::const_iterator).
2833
2834 \section1 QPtrQueue<T>
2835
2836 QPtrQueue has been moved to the Qt3Support library.
2837 It has been replaced by the more modern QQueue class.
2838
2839 The following table summarizes the differences between
2840 QPtrQueue<T> and QQueue<T *>:
2841
2842 \table
2843 \header \o QPtrQueue function \o QQueue equivalent
2844 \row \o QPtrQueue::autoDelete() \o See discussion below
2845 \row \o QPtrQueue::count() \o QQueue::count() or QQueue::size() (equivalent)
2846 \row \o QPtrQueue::current() \o QQueue::head()
2847 \row \o QPtrQueue::remove() \o QQueue::dequeue()
2848 \row \o QPtrQueue::setAutoDelete() \o See discussion below
2849 \endtable
2850
2851 If you use QPtrQueue's auto-delete feature (by calling
2852 QPtrQueue::setAutoDelete(true)), you need to do some more work.
2853 You have two options: Either you call \c delete yourself whenever
2854 you remove an item from the container, or you can use QQueue<T>
2855 instead of QQueue<T *> (i.e. store values directly instead of
2856 pointers to values). Here, we will show when to call \c delete.
2857
2858 \omit
2859 (See \l{What's Wrong with Auto-Delete} for an explanation of why
2860 the Qt 4 containers don't offer that feature.)
2861 \endomit
2862
2863 \table
2864 \header \o QPtrQueue idiom \o QQueue idiom
2865 \row
2866 \o
2867 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 38
2868 \o
2869 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 39
2870 \row
2871 \o
2872 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 40
2873 \o
2874 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 41
2875 \row
2876 \o
2877 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 42
2878
2879 (also called from QPtrQueue's destructor)
2880
2881 \o
2882 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 43
2883
2884 In 99% of cases, the following idiom also works:
2885
2886 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 44
2887
2888 However, it may lead to crashes if \c queue is referenced
2889 from the value type's destructor, because \c queue contains
2890 dangling pointers until clear() is called.
2891 \endtable
2892
2893 \section1 QPtrStack<T>
2894
2895 QPtrStack has been moved to the Qt3Support library.
2896 It has been replaced by the more modern QStack class.
2897
2898 The following table summarizes the differences between
2899 QPtrStack<T> and QStack<T *>:
2900
2901 \table
2902 \header \o QPtrStack function \o QStack equivalent
2903 \row \o QPtrStack::autoDelete() \o See discussion below
2904 \row \o QPtrStack::count() \o QStack::count() or QStack::size() (equivalent)
2905 \row \o QPtrStack::current() \o QStack::top()
2906 \row \o QPtrStack::remove() \o QStack::pop()
2907 \row \o QPtrStack::setAutoDelete() \o See discussion below
2908 \endtable
2909
2910 If you use QPtrStack's auto-delete feature (by calling
2911 QPtrStack::setAutoDelete(true)), you need to do some more work.
2912 You have two options: Either you call \c delete yourself whenever
2913 you remove an item from the container, or you can use QStack<T>
2914 instead of QStack<T *> (i.e. store values directly instead of
2915 pointers to values). Here, we will show when to call \c delete.
2916
2917 \omit
2918 (See \l{What's Wrong with Auto-Delete} for an explanation of why
2919 the Qt 4 containers don't offer that feature.)
2920 \endomit
2921
2922 \table
2923 \header \o QPtrStack idiom \o QStack idiom
2924 \row
2925 \o
2926 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 45
2927 \o
2928 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 46
2929 \row
2930 \o
2931 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 47
2932 \o
2933 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 48
2934 \row
2935 \o
2936 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 49
2937
2938 (also called from QPtrStack's destructor)
2939
2940 \o
2941 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 50
2942
2943 In 99% of cases, the following idiom also works:
2944
2945 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 51
2946
2947 However, it may lead to crashes if \c stack is referenced
2948 from the value type's destructor, because \c stack contains
2949 dangling pointers until clear() is called.
2950 \endtable
2951
2952 \section1 QPtrVector<T>
2953
2954 QPtrVector<T> has been moved to Qt3Support. It has been replaced
2955 by the more modern QVector class.
2956
2957 When porting to Qt 4, you can use QVector<T *> as an alternative
2958 to QPtrVector<T>. The APIs of QPtrVector<T> and QVector<T *> are
2959 somewhat similar. The main issue is that QPtrVector supports
2960 auto-delete whereas QVector doesn't.
2961
2962 \omit
2963 (See \l{What's Wrong with Auto-Delete} for an explanation of why
2964 the Qt 4 containers don't offer that feature.)
2965 \endomit
2966
2967 The following table summarizes the API differences between the
2968 two classes:
2969
2970 \table
2971 \header \o QPtrVector function \o QVector equivalent
2972 \row \o QPtrVector::autoDelete() \o See discussion below
2973 \row \o QPtrVector::bsearch(const T *) \o \l qBinaryFind()
2974 \row \o QPtrVector::contains(const T *) \o QVector::count(T *)
2975 \row \o QPtrVector::containsRef(const T *) \o QVector::count(T *)
2976 \row \o QPtrVector::count() \o See remark below
2977 \row \o QPtrVector::insert(uint, T *) \o See remark below
2978 \row \o QPtrVector::isNull() \o N/A
2979 \row \o QPtrVector::remove(uint) \o See remark below
2980 \row \o QPtrVector::setAutoDelete() \o See discussion below
2981 \row \o QPtrVector::sort() \o \l qSort()
2982 \row \o QPtrVector::take(uint) \o See remark below
2983 \row \o QPtrVector::toList(QGList *) \o QList::QList(const QVector &)
2984 \endtable
2985
2986 Remarks:
2987
2988 \list 1
2989 \o QPtrVector::insert(uint, T *) sets an item to store a certain
2990 pointer value. This is \e not the same as QVector::insert(int, T *),
2991 which creates space for the item by moving following items by
2992 one position. Use \c{vect[i] = ptr} to set a QVector item to
2993 a particular value.
2994 \o QPtrVector::remove(uint) sets an item to be 0. This is \e not
2995 the same as QVector::removeAt(int), which entirely erases the
2996 item, reducing the size of the vector. Use \c{vect[i] = 0} to
2997 set a QVector item to 0.
2998 \o Likewise, QPtrVector::take(uint) sets an item to be 0 and
2999 returns the previous value of the item. Again, this is easy to
3000 achieve using QVector::operator[]().
3001 \o QPtrVector::count() returns the number of non-null items in
3002 the vector, whereas QVector::count() (like QVector::size())
3003 returns the number of items (null or non-null) in the vector.
3004 Fortunately, it's not too hard to simulate QPtrVector::count().
3005
3006 \oldcode
3007 int numValidItems = vect.count();
3008 \newcode
3009 int numValidItems = vect.size() - vect.count(0);
3010 \endcode
3011 \endlist
3012
3013 If you use QVector's auto-delete feature (by calling
3014 QVector::setAutoDelete(true)), you need to do some more work. You
3015 have two options: Either you call \c delete yourself whenever you
3016 remove an item from the container, or you use QVector<T> instead
3017 of QVector<T *> (i.e. store values directly instead of pointers
3018 to values). Here, we'll see when to call \c delete.
3019
3020 The following table summarizes the idioms that you need to watch
3021 out for if you want to call \c delete yourself.
3022
3023 \table
3024 \header \o QPtrVector idiom \o QVector idiom
3025 \row
3026 \o
3027 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 52
3028 \o
3029 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 53
3030 \row
3031 \o
3032 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 54
3033 \o
3034 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 55
3035 \row
3036 \o
3037 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 56
3038 \o
3039 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 57
3040 \row
3041 \o
3042 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 58
3043 \o
3044 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 59
3045 \row
3046 \o
3047 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 60
3048
3049 (also called from QPtrVector's destructor)
3050
3051 \o
3052 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 61
3053
3054 In 99% of cases, the following idiom also works:
3055
3056 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 62
3057
3058 However, it may lead to crashes if \c vect is referenced from
3059 the value type's destructor, because \c vect contains
3060 dangling pointers until clear() is called.
3061 \endtable
3062
3063 Be aware that QPtrVector's destructor automatically calls
3064 clear(). If you have a QPtrVector data member in a custom class
3065 and use the auto-delete feature, you will need to call \c delete
3066 on all the items in the container from your class destructor to
3067 avoid a memory leak.
3068
3069 \section1 QPushButton
3070
3071 See \l{#properties}{Properties} for a list of QPushButton
3072 properties in Qt 3 that have changed in Qt 4.
3073
3074 \section1 QRangeControl
3075
3076 In Qt 3, various "range control" widgets (QDial, QScrollBar,
3077 QSlider, and QSpin) inherited from both QWidget and
3078 \c QRangeControl.
3079
3080 In Qt 4, \c QRangeControl has been replaced with the new
3081 QAbstractSlider and QAbstractSpinBox classes, which inherit from
3082 QWidget and provides similar functionality. Apart from eliminating
3083 unnecessary multiple inheritance, the new design allows
3084 QAbstractSlider to provide signals, slots, and properties.
3085
3086 The old \c QRangeControl class has been renamed Q3RangeControl
3087 and moved to the Qt3Support library, together with
3088 the (undocumented) \c QSpinWidget class.
3089
3090 If you use \c QRangeControl as a base class in your application,
3091 you can switch to use QAbstractSlider or QAbstractSpinBox instead.
3092
3093 \oldcode
3094 class VolumeControl : public QWidget, public QRangeControl
3095 {
3096 ...
3097 protected:
3098 void valueChange() {
3099 update();
3100 emit valueChanged(value());
3101 }
3102 void rangeChange() {
3103 update();
3104 }
3105 void stepChange() {
3106 update();
3107 }
3108 };
3109 \newcode
3110 class VolumeControl : public QAbstractSlider
3111 {
3112 ...
3113 protected:
3114 void sliderChange(SliderChange change) {
3115 update();
3116 if (change == SliderValueChange)
3117 emit valueChanged(value());
3118 }
3119 };
3120 \endcode
3121
3122 \section1 QRegExp
3123
3124 The search() and searchRev() functions have been renamed to indexIn()
3125 and lastIndexIn() respectively.
3126
3127 \section1 QRegion
3128
3129 The following changes have been made to QRegion in Qt 4:
3130
3131 \list
3132 \o There is no longer any difference between a \e null region and
3133 an \e empty region. Use isEmpty() in most places where you
3134 would have used a null QRegion.
3135 \o QRegion::rects() used to return a QMemArray<QRect>. It now returns
3136 a QVector<QRect>.
3137 \endlist
3138
3139 \section1 QScrollBar
3140
3141 See \l{#properties}{Properties} for a list of QScrollBar
3142 properties in Qt 3 that have changed in Qt 4.
3143
3144 \section1 QScrollView
3145
3146 The \c QScrollView class has been renamed Q3ScrollView and moved
3147 to the Qt3Support library. It has been replaced by
3148 the QAbstractScrollArea and QScrollArea classes.
3149
3150 Note that Qt 4 in general uses the QScrollArea::widget() function
3151 where Qt 3 used QScrollView::viewport(). The rationale for this is
3152 that it is no longer possible to draw directly on a scroll
3153 area. The QScrollArea::widget() function returns the widget set on
3154 the scroll area.
3155
3156 \c QScrollView was designed to work around the 16-bit limitation
3157 on widget coordinates found on most window systems. In Qt 4, this
3158 is done transparently for \e all widgets, so there is no longer a
3159 need for such functionality in \c QScrollView. For that reason,
3160 the new QAbstractScrollArea and QScrollArea classes are much more
3161 lightweight, and concentrate on handling scroll bars.
3162
3163 \section1 QServerSocket
3164
3165 The \c QServerSocket class has been renamed Q3ServerSocket and
3166 moved to the Qt3Support library. In Qt 4, it has been
3167 replaced by QTcpServer.
3168
3169 With Q3ServerSocket, connections are accepted by reimplementing a
3170 virtual function (Q3ServerSocket::newConnection()). With
3171 QTcpServer, on the other hand, you don't need to subclass.
3172 Instead, simply connect to the QTcpServer::newConnection()
3173 signal.
3174
3175 \section1 QSettings
3176
3177 The QSettings class has been rewritten to be more robust and to
3178 respect existing standards (e.g., the INI file format). The API
3179 has also been extensively revised. The old API is still provided
3180 when Qt 3 support is enabled.
3181
3182 Since the format and location of settings have changed between Qt
3183 3 and Qt 4, the Qt 4 version of your application won't recognize
3184 settings written using Qt 3.
3185
3186 \section1 QShared
3187
3188 The \c QShared class has been obsoleted by the more powerful
3189 QSharedData and QSharedDataPointer as a means of creating custom
3190 implicitly shared classes. It has been renamed Q3Shared and moved
3191 to the Qt3Support library.
3192
3193 An easy way of porting to Qt 4 is to include this class into your
3194 project and to use it instead of \c QShared:
3195
3196 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63
3197
3198 If possible, we recommend that you use QSharedData and
3199 QSharedDataPointer instead. They provide thread-safe reference
3200 counting and handle all the reference counting behind the scenes,
3201 eliminating the risks of forgetting to increment or decrement the
3202 reference count.
3203
3204 \section1 QSignal
3205
3206 The QSignal class has been renamed to Q3Signal and moved to the
3207 Qt3Support library. The preferred approach is to create your own
3208 QObject subclass with a signal that has the desired signature.
3209 Alternatively, you can call QMetaObject::invokeMethod() if you
3210 want to invoke a slot.
3211
3212 \section1 QSimpleRichText
3213
3214 QSimpleRichText has been obsoleted by QTextDocument. It has
3215 been renamed Q3SimpleRichText and moved to the Qt3Support
3216 library.
3217
3218 Previously, you would do the following with Q3SimpleRichText:
3219
3220 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63a
3221
3222 However, with QTextDocument, you use the following code instead:
3223
3224 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63b
3225
3226 See \l{Rich Text Processing} for an overview of the Qt 4 rich
3227 text classes.
3228
3229 \section1 QSlider
3230
3231 The QSlider::sliderStart() and QSlider::sliderRect() functions
3232 have been removed.
3233
3234 The slider's rect can now be retrieved using the code snippet below:
3235
3236 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 63c
3237
3238 In addition, the direction of a vertical QSlider has changed,
3239 i.e. the bottom is now the minimum, and the top the maximum. You
3240 can use the QAbstractSlider::invertedAppearance property to
3241 control this behavior.
3242
3243 See \l{#properties}{Properties} for a list of QSlider properties
3244 in Qt 3 that have changed in Qt 4.
3245
3246 \section1 QSocket
3247
3248 The \c QSocket class has been renamed Q3Socket and moved to the
3249 Qt3Support library. In Qt 4, it has been replaced by
3250 the QTcpSocket class, which inherits most of its functionality
3251 from QAbstractSocket.
3252
3253 \section1 QSocketDevice
3254
3255 The \c QSocketDevice class has been renamed Q3SocketDevice and
3256 moved to the Qt3Support library. In Qt 4, there is no
3257 direct equivalent to Q3SocketDevice:
3258
3259 \list \o If you use Q3SocketDevice in a thread to perform blocking
3260 network I/O (a technique encouraged by the \e{Qt Quarterly}
3261 article \l{http://doc.qt.nokia.com/qq/qq09-networkthread.html}
3262 {Unblocking Networking}), you can now use QTcpSocket, QFtp, or
3263 QNetworkAccessManager, which can be used from non-GUI threads.
3264
3265 \o If you use Q3SocketDevice for UDP, you can now use QUdpSocket instead.
3266
3267 \o If you use Q3SocketDevice for other uses, Qt 4 offers no
3268 alternative right now. However, there is a \c QAbstractSocketEngine
3269 internal class that offers a low-level socket API similar to
3270 Q3SocketDevice. Should the need for such functionality arise in
3271 Qt 4 applications, we will consider making this class public in a
3272 future release.
3273 \endlist
3274
3275 \section1 QSortedList
3276
3277 The QSortedList<T> class has been deprecated since Qt 3.0. In Qt
3278 4, it has been moved to the Qt3Support library.
3279
3280 In new code, we recommend that you use QList<T> instead and use
3281 \l qSort() to sort the items.
3282
3283 \section1 QSplitter
3284
3285 The function setResizeMode() has been moved into Qt3Support. Set
3286 the stretch factor in the widget's size policy to get equivalent
3287 functionality.
3288
3289 The obsolete function drawSplitter() has been removed. Use
3290 QStyle::drawPrimitive() to acheive similar functionality.
3291
3292 \section1 QSpinBox
3293
3294 See \l{#properties}{Properties} for a list of QSpinBox properties
3295 in Qt 3 that have changed in Qt 4.
3296
3297 \section1 QSqlCursor
3298
3299 The \c QSqlCursor class has been renamed Q3SqlCursor and moved to
3300 the Qt3Support library. In Qt 4, you can use
3301 QSqlQuery, QSqlQueryModel, or QSqlTableModel, depending on
3302 whether you want a low-level or a high-level interface for
3303 accessing databases.
3304
3305 See \l{QtSql Module} for an overview of the new SQL classes.
3306
3307 \section1 QSqlDatabase
3308
3309 QSqlDatabase is now a smart pointer that is passed around by
3310 value. Simply replace all QSqlDatabase pointers by QSqlDatabase
3311 objects.
3312
3313 \section1 QSqlEditorFactory
3314
3315 The \c QSqlEditorFactory class has been renamed
3316 Q3SqlEditorFactory and moved to Qt3Support.
3317
3318 See \l{QtSql Module} for an overview of the new SQL classes.
3319
3320 \section1 QSqlError
3321
3322 The enum \c{Type} was renamed to \c{ErrorType}, The values were renamed as well:
3323
3324 \list
3325 \o None - use NoError instead
3326 \o Connection - use ConnectionError instead
3327 \o Statement - use StatementError instead
3328 \o Transaction - use TransactionError instead
3329 \o Unknown - use UnknownError instead
3330 \endlist
3331
3332 \section1 QSqlFieldInfo
3333
3334 The QSqlFieldInfo class has been moved to Qt3Support. Its
3335 functionality is now provided by the QSqlField class.
3336
3337 See \l{QtSql Module} for an overview of the new SQL classes.
3338
3339 \section1 QSqlForm
3340
3341 The \c QSqlForm class has been renamed Q3SqlForm and moved to the
3342 Qt3Support library.
3343
3344 See \l{QtSql Module} for an overview of the new SQL classes.
3345
3346 \section1 QSqlPropertyMap
3347
3348 The \c QSqlPropertyMap class has been renamed Q3SqlPropertyMap
3349 moved to the Qt3Support library.
3350
3351 See \l{QtSql Module} for an overview of the new SQL classes.
3352
3353 \section1 QSqlQuery
3354
3355 QSqlQuery::prev() was renamed to QSqlQuery::previous().
3356 QSqlQuery::prev() remains, but it just calls previous().
3357 QSqlQuery no longer has any virtual methods, i.e., exec(),
3358 value(), seek(), next(), prev(), first(), last(), and the
3359 destructor are no longer virtual.
3360
3361 \section1 QSqlRecord
3362
3363 QSqlRecord behaves like a vector now, QSqlRecord::insert() will
3364 actually insert a new field instead of replacing the existing
3365 one.
3366
3367 \section1 QSqlRecordInfo
3368
3369 The QSqlRecordInfo class has been moved to Qt3Support. Its
3370 functionality is now provided by the QSqlRecord class.
3371
3372 See \l{QtSql Module} for an overview of the new SQL classes.
3373
3374 \section1 QSqlSelectCursor
3375
3376 The \c QSqlSelectCursor class has been renamed Q3SqlSelectCursor
3377 and moved to the Qt3Support library.
3378
3379 See \l{QtSql Module} for an overview of the new SQL classes.
3380
3381 \section1 QStoredDrag
3382
3383 The \c QStoredDrag class has been renamed Q3StoredDrag and moved
3384 to the Qt3Support library. In Qt 4, use QMimeData
3385 instead and call QMimeData::setData() to set the data.
3386
3387 See \l{Porting to Qt 4 - Drag and Drop} for a comparison between
3388 the drag and drop APIs in Qt 3 and Qt 4.
3389
3390 \section1 QStr(I)List
3391
3392 The QStrList and QStrIList convenience classes have been
3393 deprecated since Qt 2.0. In Qt 4, they have been moved to the
3394 Qt3Support library. If you used any of these, we
3395 recommend that you use QStringList or QList<QByteArray> instead.
3396
3397 \section1 QStr(I)Vec
3398
3399 The QStrVec and QStrIVec convenience classes have been deprecated
3400 since Qt 2.0. In Qt 4, they have been moved to Qt3Support. If you
3401 used any of these, we recommend that you use QStringList or
3402 QList<QByteArray> instead.
3403
3404 \section1 QString
3405
3406 Here are the main issues to be aware of when porting QString to
3407 Qt 4:
3408
3409 \list 1
3410 \o The QString::QString(QChar) constructor performed implicit
3411 conversion in Qt 3. Now, you will need a cast to convert a
3412 QChar to a QString.
3413
3414 \o The QString::QString(const QByteArray &) constructor used to
3415 stop at the first '\\0' it encountered, for compatibility
3416 with Qt 1. This quirk has now been fixed; in Qt 4, the
3417 resulting QString always has the same length as the
3418 QByteArray that was passed to the constructor.
3419
3420 \o The QString::null static constant has been deprecated in Qt
3421 4. For compatibility, Qt 4 provides a QString::null symbol
3422 that behaves more or less the same as the old constant. The
3423 new idiom is to write QString() instead of QString::null, or
3424 to call clear().
3425
3426 \oldcode
3427 str1 = QString::null;
3428 if (str2 == QString::null)
3429 do_something(QString::null);
3430 \newcode
3431 str1.clear();
3432 if (str2.isNull())
3433 do_something(QString());
3434 \endcode
3435
3436 In new code, we recommend that you don't rely on the
3437 distinction between a null string and a (non-null) empty
3438 string. See \l{Distinction Between Null and Empty Strings}
3439 for details.
3440
3441 \o QString::latin1() and QString::ascii() have been replaced
3442 with QString::toLatin1() and QString::toAscii(), which return
3443 a QByteArray instead of a (non-reentrant) \c{const char *}.
3444 For consistency, QString::utf8() and QString::local8Bit(),
3445 which already returned a QByteArray (actually a \c QCString),
3446 have been renamed QString::toUtf8() and
3447 QString::toLocal8Bit().
3448
3449 To obtain a \c{const char *} pointer to ASCII or Latin-1 data,
3450 use QString::toAscii() or QString::toLatin1() to obtain a
3451 QByteArray containing the data, then call QByteArray::constData()
3452 to access the character data directly. Note that the pointer
3453 returned by this function is only valid for the lifetime of the
3454 byte array; you should avoid taking a pointer to the data
3455 contained in temporary objects.
3456
3457 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 64
3458
3459 In the above example, the \c goodData pointer is valid for the lifetime
3460 of the \c asciiData byte array. If you need to keep a copy of the data
3461 in a non-Qt data structure, use standard C memory allocation and string
3462 copying functions to do so \e before destroying the byte array.
3463
3464 \o QString::at() returned a non-const reference, whereas the
3465 new QString::at() returns a const value. Code like
3466
3467 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 65
3468
3469 will no longer compile. Instead, use QString::operator[]:
3470
3471 \snippet doc/src/snippets/code/doc_src_porting4.qdoc 66
3472
3473 \o The QString::contains(\e x) function (where \e x is a
3474 character or a string) has been renamed QString::count(\e x).
3475 In addition, there now exists a set of QString::contains()
3476 functions that returns a boolean value. Replace old calls to
3477 contains() with either count() or contains(), depending on
3478 whether you care about the specific number of occurrences of
3479 a character in the string or only care about whether the
3480 string contains that character or not.
3481
3482 \o Many functions in QString had a \c bool parameter that
3483 specified case sensitivity. In Qt 4, in the interest of code
3484 readability and maintainability, the \c bool parameters have
3485 been replaced by the Qt::CaseSensitivity enum, which can take
3486 the values Qt::CaseSensitive and Qt::CaseInsensitive.
3487
3488 \oldcode
3489 if (url.startsWith("http:", false))
3490 ...
3491 \newcode
3492 if (url.startsWith("http:", Qt::CaseInsensitive))
3493 ...
3494 \endcode
3495
3496 \o The QString::setExpand(uint, QChar) function, which already
3497 was obsolete in Qt 3, is no longer available. Use
3498 QString::operator[] instead.
3499
3500 \oldcode
3501 str.setExpand(32, '$');
3502 \newcode
3503 str[32] = '$';
3504 \endcode
3505
3506 \o The \c QT_NO_ASCII_CAST and \c QT_NO_CAST_ASCII macros have
3507 been renamed \c QT_NO_CAST_TO_ASCII and \c
3508 QT_NO_CAST_FROM_ASCII, respectively.
3509
3510 \o The QString::data() used to return the same as
3511 QString::ascii(). It now returns a pointer to the Unicode
3512 data stored in the QString object. Call QString::ascii() if
3513 you want the old behavior.
3514
3515 \o QString::arg() now converts two-digit place markers, allowing
3516 up to 99 place markers to be used in any given string.
3517
3518 \o Comparisons between QStrings and \c NULL in order to determine
3519 whether strings are empty are no longer allowed.
3520 Use \l{QString::}{isEmpty()} instead.
3521
3522 \endlist
3523
3524 \section1 QStringList
3525
3526 QStringList now inherits from QList<QString> and can no longer be
3527 converted to a QValueList<QString>. Since QValueList inherits QList a
3528 cast will work as expected.
3529
3530 This change implies some API incompatibilities for QStringList.
3531 For example, at() returns the string, not an iterator. See the
3532 \l{#qvaluelist.section}{section on QValueList} for details.
3533
3534 The static QStringList::split() function for splitting strings into
3535 lists of smaller strings has been replaced by QString::split(),
3536 which returns a QStringList.
3537
3538 \section1 QStyle
3539
3540 The QStyle API has been overhauled and improved. Most of the information on
3541 why this change was done is described in \l{The Qt 4 Style API}{the QStyle overview}.
3542
3543 Since QStyle is mostly used internally by Qt's widgets and styles and since
3544 it is not essential to the good functioning of an application, there is no
3545 compatibility path. This means that we have changed many enums and
3546 functions and the qt3to4 porting tool will not change much in your qstyle
3547 code. To ease the pain, we list some of the major changes here.
3548
3549 QStyleOption has taken on a more central role and is no longer an optional
3550 argument, please see the QStyleOption documentation for more information.
3551
3552 The QStyle::StyleFlags have been renamed QStyle::StateFlags and are now prefixed State_
3553 instead of Style_, in addition the Style_ButtonDefault flag has moved to
3554 QStyleOptionButton.
3555
3556 The QStyle::PrimitiveElement enumeration has undergone extensive change.
3557 Some of the enums were moved to QStyle::ControlElement, some were removed
3558 and all were renamed. This renaming is not done by the qt3to4 porting tool,
3559 so you must do it yourself. The table below shows how things look
3560 now.
3561
3562 \table
3563 \header \o Old name \o New name \o Remark
3564 \row \o \c PE_ButtonCommand \o QStyle::PE_PanelButtonCommand
3565 \row \o \c PE_ButtonDefault \o QStyle::PE_FrameDefaultButton
3566 \row \o \c PE_ButtonBevel \o QStyle::PE_PanelButtonBevel
3567 \row \o \c PE_ButtonTool \o QStyle::PE_PanelButtonTool
3568 \row \o \c PE_ButtonDropDown \o QStyle::PE_IndicatorButtonDropDown
3569 \row \o \c PE_FocusRect \o QStyle::PE_FrameFocusRect
3570 \row \o \c PE_ArrowUp \o QStyle::PE_IndicatorArrowUp
3571 \row \o \c PE_ArrowDown \o QStyle::PE_IndicatorArrowDown
3572 \row \o \c PE_ArrowRight \o QStyle::PE_IndicatorArrowRight
3573 \row \o \c PE_ArrowLeft \o QStyle::PE_IndicatorArrowLeft
3574 \row \o \c PE_SpinBoxUp \o QStyle::PE_IndicatorSpinUp
3575 \row \o \c PE_SpinBoxDown \o QStyle::PE_IndicatorSpinDown
3576 \row \o \c PE_SpinBoxPlus \o QStyle::PE_IndicatorSpinPlus
3577 \row \o \c PE_SpinBoxMinus \o QStyle::PE_IndicatorSpinMinus
3578 \row \o \c PE_SpinBoxSlider \o QStyle::CE_SpinBoxSlider \o uses QStyle::drawControl()
3579 \row \o \c PE_Indicator \o QStyle::PE_IndicatorCheckBox
3580 \row \o \c PE_IndicatorMask \o N/A \o use QStyle::styleHint() to retrieve mask
3581 \row \o \c PE_ExclusiveIndicator \o QStyle::PE_IndicatorRadioButton
3582 \row \o \c PE_ExclusiveIndicatorMask \o N/A \o use QStyle::styleHint() to retrieve mask
3583 \row \o \c PE_DockWindowHandle \o QStyle::PE_IndicatorToolBarHandle
3584 \row \o \c PE_DockWindowSeparator \o QStyle::PE_Q3DockWindowSeparator
3585 \row \o \c PE_DockWindowResizeHandle \o QStyle::PE_IndicatorDockWindowResizeHandle
3586 \row \o \c PE_DockWindowTitle \o QStyle::CE_DockWindowTitle \o uses QStyle::drawControl()
3587 \row \o \c PE_Splitter \o QStyle::CE_Splitter \o uses QStyle::drawControl()
3588 \row \o \c PE_Panel \o QStyle::PE_Frame
3589 \row \o \c PE_PanelMenu \o QStyle::PE_FrameMenu
3590 \row \o \c PE_PanelMenuBar \o QStyle::PE_PanelMenuBar
3591 \row \o \c PE_PanelDockWindow \o QStyle::PE_FrameDockWindow
3592 \row \o \c PE_TabBarBase \o QStyle::PE_FrameTabBarBase
3593 \row \o \c PE_HeaderSection \o QStyle::CE_HeaderSection \o uses QStyle::drawControl()
3594 \row \o \c PE_HeaderArrow \o QStyle::PE_IndicatorHeaderArrow
3595 \row \o \c PE_StatusBarSection \o QStyle::PE_FrameStatusBar
3596 \row \o \c PE_Separator \o QStyle::PE_Q3Separator
3597 \row \o \c PE_SizeGrip \o QStyle::CE_SizeGrip \o uses QStyle::drawControl()
3598 \row \o \c PE_CheckMark \o QStyle::PE_IndicatorMenuCheckMark
3599 \row \o \c PE_ScrollBarAddLine \o QStyle::CE_ScrollBarAddLine \o uses QStyle::drawControl()
3600 \row \o \c PE_ScrollBarSubLine \o QStyle::CE_ScrollBarSubLine \o uses QStyle::drawControl()
3601 \row \o \c PE_ScrollBarAddPage \o QStyle::CE_ScrollBarAddPage \o uses QStyle::drawControl()
3602 \row \o \c PE_ScrollBarSubPage \o QStyle::CE_ScrollBarSubPage \o uses QStyle::drawControl()
3603 \row \o \c PE_ScrollBarSlider \o QStyle::CE_ScrollBarSlider \o uses QStyle::drawControl()
3604 \row \o \c PE_ScrollBarFirst \o QStyle::CE_ScrollBarFirst \o uses QStyle::drawControl()
3605 \row \o \c PE_ScrollBarLast \o QStyle::CE_ScrollBarLast \o uses QStyle::drawControl()
3606 \row \o \c PE_ProgressBarChunk \o QStyle::PE_IndicatorProgressChunk
3607 \row \o \c PE_PanelLineEdit \o QStyle::PE_FrameLineEdit
3608 \row \o \c PE_PanelTabWidget \o QStyle::PE_FrameTabWidget
3609 \row \o \c PE_WindowFrame \o QStyle::PE_FrameWindow
3610 \row \o \c PE_CheckListController \o QStyle::PE_Q3CheckListController
3611 \row \o \c PE_CheckListIndicator \o QStyle::PE_Q3CheckListIndicator
3612 \row \o \c PE_CheckListExclusiveIndicato\o QStyle::PE_Q3CheckListExclusiveIndicator
3613 \row \o \c PE_PanelGroupBox \o QStyle::PE_FrameGroupBox
3614 \row \o \c PE_TreeBranch \o QStyle::PE_IndicatorBranch
3615 \row \o \c PE_RubberBand \o QStyle::CE_RubberBand \o uses QStyle::drawControl()
3616 \row \o \c PE_PanelToolBar \o QStyle::PE_PanelToolBar
3617 \row \o \c PE_ToolBarHandle \o QStyle::PE_IndicatorToolBarHandle
3618 \row \o \c PE_ToolBarSeparator \o QStyle::PE_IndicatorToolBarSeparator
3619 \endtable
3620
3621 The QStyle::drawControlMask() and QStyle::drawComplexControlMask()
3622 functions have been removed. They are replaced with a style hint.
3623
3624 The QStyle::drawItem() overloads that took both a pixmap and a string have
3625 been removed. Use QStyle::drawItemText() and QStyle::drawItemPixmap() directly.
3626
3627 The QStyle::itemRect() overload that took both a pixmap and a string is also removed, use
3628 either QStyle::itemTextRect() or QStyle::itemPixmapRect() instead.
3629
3630 \section1 QStyleSheet
3631
3632 The QStyleSheet and QStyleSheetItem classes have been renamed
3633 Q3StyleSheet and Q3StyleSheetItem, and have been moved to the
3634 Qt3Support library.
3635
3636 See \l{Rich Text Processing} for an overview of the Qt 4 rich
3637 text classes, and \l{Qt Style Sheets} for a description of
3638 CSS-like style sheet support in Qt 4.2 and above.
3639
3640 \section1 QSyntaxHighlighter
3641
3642 The \c QSyntaxHighlighter class from Qt 3 has been renamed
3643 Q3SyntaxHighlighter and moved to the Qt3Support library. Since Qt
3644 4.1, it has been replaced by a new QSyntaxHighlighter class based
3645 on Qt 4's new rich text engine.
3646
3647 \section1 QTabBar
3648
3649 See \l{#properties}{Properties} for a list of QTabBar properties
3650 in Qt 3 that have changed in Qt 4.
3651
3652 \section1 QTabDialog
3653
3654 The \c QTabDialog class is no longer part of the public Qt API.
3655 It has been renamed Q3TabDialog and moved to Qt3Support. In Qt 4
3656 applications, you can easily obtain the same result by combining
3657 a QTabWidget with a QDialog and provide \l{QPushButton}s
3658 yourself.
3659
3660 See also the \l{dialogs/tabdialog} example, which shows how to
3661 implement tab dialogs in Qt 4.
3662
3663 \section1 QTabWidget
3664
3665 See \l{#properties}{Properties} for a list of QTabWidget
3666 properties in Qt 3 that have changed in Qt 4.
3667
3668 \section1 QTable
3669
3670 The \c QTable, \c QTableItem, \c QComboTableItem, \c
3671 QCheckTableItem, and \c QTableSelection classes have been renamed
3672 Q3Table, Q3TableItem, Q3ComboTableItem, Q3CheckTableItem, and
3673 Q3TableSelection and moved to the Qt3Support library.
3674 New Qt applications should use the new QTableWidget or QTableView
3675 class instead.
3676
3677 Some of these classes behave differently with respect to the way
3678 they handle \c NULL pointers. For example, Q3TableItem::setPixmap()
3679 no longer accepts \c NULL or 0 to indicate that the item should
3680 contain a null pixmap; in this case, a null pixmap should be
3681 constructed and passed explicitly to the function.
3682
3683 See \l{Model/View Programming} for an overview of the new item
3684 view classes.
3685
3686 \section1 QTextCodec
3687
3688 The loadCharmap() and loadCharmapFromFile() functions are no longer
3689 available in Qt 4. You need to create your own codec if you want to
3690 create a codec based on a POSIX2 charmap definition.
3691
3692 \section1 QTextDrag
3693
3694 The \c QTextDrag class has been renamed Q3TextDrag and moved to
3695 the Qt3Support library. In Qt 4, use QMimeData
3696 instead and call QMimeData::setText() to set the data.
3697
3698 See \l{Porting to Qt 4 - Drag and Drop} for a comparison between
3699 the drag and drop APIs in Qt 3 and Qt 4.
3700
3701 \section1 QTextEdit
3702
3703 The old QTextEdit and QTextBrowser classes have been renamed
3704 Q3TextEdit and Q3TextBrowser, and have been moved to Qt3Support.
3705 The new QTextEdit and QTextBrowser have a somewhat different API.
3706
3707 The \c QTextEdit::setWrapPolicy() function has been renamed to \l{QTextEdit::setWordWrapMode()}{setWordWrapMode()} and the
3708 \c QTextEdit::setWrapColumnOrWidth() function has been renamed to \l{QTextEdit::setLineWrapColumnOrWidth()}
3709 {setLineWrapColumnOrWidth()}. The Q3TextEdit::setWrapPolicy() and Q3TextEdit::setWrapColumnOrWidth() still provide this
3710 functionality in the Q3TextEdit class.
3711
3712
3713 See \l{Rich Text Processing} for an overview of the Qt 4 rich
3714 text classes.
3715
3716 \section1 QTextIStream
3717
3718 The QTextIStream convenience class is no longer provided in Qt 4. Use
3719 QTextStream directly instead.
3720
3721 \section1 QTextOStream
3722
3723 The QTextOStream convenience class is no longer provided in Qt 4. Use
3724 QTextStream directly instead.
3725
3726 \section1 QTextOStreamIterator
3727
3728 The undocumented \c QTextOStreamIterator class has been removed
3729 from the Qt library. If you need it in your application, feel
3730 free to copy the source code from the Qt 3 \c <qtl.h> header
3731 file.
3732
3733 \section1 QTextStream
3734
3735 QTextStream has undergone a number of API and implementation enhancements,
3736 and some of the changes affect QTextStream's behavior:
3737
3738 \list
3739 \o QTextStream now uses buffered writing, which means that you need to
3740 call QTextStream::flush(), or use the streaming manipulators \c endl or
3741 \c flush if you need QTextStream to flush its write buffer. The stream is
3742 flushed automatically if QTextStream is deleted or when the device is
3743 closed.
3744 \o QTextStream now uses buffered reading, so if you read a line from the
3745 stream, QTextStream will read as much as it can from the device to
3746 fill up its internal read buffer. This speeds up reading significantly,
3747 but Qt 3 code that mixed QTextStream access and direct device access
3748 may need to be updated.
3749 \o While QTextStream in Qt 3 always translated end-of-line characters from
3750 Windows style ("\\r\\n") to Unix style ("\\n") on Windows, QTextStream in
3751 Qt 4 only does this on devices opened with the \c{QIODevice::Text} mode
3752 (formerly \c{IO_Translate}).
3753 \endlist
3754
3755 Note that when using a QTextStream on a QFile in Qt 4, calling
3756 QIODevice::reset() on the QFile will not have the expected result
3757 because QTextStream now buffers the file. Use the
3758 QTextStream::seek() function instead.
3759
3760 \section1 QTextView
3761
3762 The \c QTextView class has been renamed Q3TextView and moved to the
3763 Qt3Support library.
3764
3765 \section1 QTimeEdit
3766
3767 The QTimeEdit class in Qt 4 is a convenience class based on
3768 QDateTimeEdit. The old class has been renamed Q3TimeEdit and moved
3769 to the Qt3Support library.
3770
3771 See \l{Porting to Qt 4 - Virtual Functions}{Virtual Functions} for
3772 a list of \c QTimeEdit virtual member functions in Qt 3 that are no
3773 longer virtual in Qt 4.
3774
3775 \section1 QTimer
3776
3777 Windows restricts the granularity of timers, but starting with Qt 4,
3778 we emulate a finer time resolution. On Windows XP we use the
3779 multimedia timer API, which gives us 1 millisecond resolution for
3780 QTimer.
3781
3782 Note that Windows 2000 has a lower timer resolution, and that code relying
3783 on underlying system timer restrictions encounters no such limitations
3784 using Qt 4 (e.g., setting an interval of 0 millisecond results in Qt
3785 occupying all of the processor time when no GUI events need processing).
3786
3787 \section1 QToolBar
3788
3789 The old \c QToolBar class, which worked with the old \c
3790 QMainWindow and \c QDockArea classes and inherited from \c
3791 QDockWindow, has been renamed Q3ToolBar and moved to
3792 Qt3Support. Note that, when using Q3ToolBar, the toolbar's actions
3793 must be \l {Q3Action}s.
3794
3795 Use the new QToolBar class in new applications.
3796
3797 \note \l{Q3ToolBar}'s
3798 \l{Q3DockWindow::setHorizontallyStretchable()}{horizontallyStretchable}
3799 property can be achieved in QToolBar with
3800 \l{QWidget#Size Hints and Size Policies}{size policies}.
3801
3802 \section1 QToolButton
3803
3804 See \l{#properties}{Properties} for a list of QToolButton properties
3805 in Qt 3 that have changed in Qt 4.
3806
3807 Note that many of the properties that could previously be set in
3808 the constructor must now be set separately.
3809
3810 \section1 QToolTip
3811
3812 The QToolTip::setGloballyEnabled() function no longer exists.
3813 Tooltips can be disabled by \l{QObject::installEventFilter()}{installing
3814 an event filter} on qApp (the unique QApplication object) to block events
3815 of type QEvent::ToolTip.
3816
3817 \section1 QUriDrag
3818
3819 The \c QUriDrag class has been renamed Q3UriDrag and moved to the
3820 Qt3Support library. In Qt 4, use QMimeData instead
3821 and call QMimeData::setUrl() to set the URL.
3822
3823 See \l{Porting to Qt 4 - Drag and Drop} for a comparison between
3824 the drag and drop APIs in Qt 3 and Qt 4.
3825
3826 \section1 QUrl
3827
3828 The QUrl class has been rewritten from scratch in Qt 4 to be more
3829 standard-compliant. The old QUrl class has been renamed Q3Url and
3830 moved to the Qt3Support library.
3831
3832 The new QUrl class provides an extensive list of compatibility
3833 functions to ease porting from Q3Url to QUrl. A few functions
3834 require you to change your code:
3835
3836 \list
3837 \o Q3Url::Q3Url(const Q3Url &, const QString &, bool) can be
3838 simulated by combining the URLs manually (using
3839 QString::operator+(), for example).
3840 \o Q3Url::setEncodedPathAndQuery(const QString &) is replaced by
3841 QUrl::setPath() and QUrl::setEncodedQuery().
3842 \o Q3Url::encodedPathAndQuery() is replaced by QUrl::path() and
3843 QUrl::encodedQuery().
3844 \o Q3Url::isLocalFile() can be simulated by checking that
3845 QUrl::protocol() is "file".
3846 \o Q3Url::toString(bool, bool) is replaced by
3847 QUrl::toString(int), where the \c int parameter specifies a
3848 combination of \l{QUrl::FormattingOptions}{formatting
3849 options}.
3850 \endlist
3851
3852 \section1 QUrlOperator
3853
3854 The \c QUrlOperator class is no longer part of the public Qt API.
3855 It has been renamed Q3UrlOperator and moved to Qt3Support.
3856
3857 From Qt 4.4, the Network Access API provides a subset of the features
3858 provided by \c QUrlOperator that are mostly intended for use with
3859 applications that use the HTTP and FTP protocols. See the
3860 QNetworkRequest, QNetworkReply, and QNetworkAccessManager documentation
3861 for further details.
3862
3863 \target qvaluelist.section
3864 \section1 QValueList<T>
3865
3866 The QValueList<T> class has been replaced by QList<T> and
3867 QLinkedList<T> in Qt 4. As a help when porting older Qt
3868 applications, the Qt3Support library contains a
3869 QValueList<T> class implemented in terms of the new
3870 QLinkedList<T>. Similarly, it contains QValueListIterator<T> and
3871 QValueListConstIterator<T> classes implemented in terms of
3872 QLinkedList<T>::iterator and QLinkedList<T>::const_iterator.
3873
3874 When porting to Qt 4, you have the choice of using QList<T> or
3875 QLinkedList<T> as alternatives to QValueList<T>. QList<T> has an
3876 index-based API and provides very fast random access
3877 (QList::operator[]), whereas QLinkedList<T> has an iterator-based
3878 API.
3879
3880 Here's a list of problem functions:
3881
3882 \list
3883 \o QValueList(const std::list<T> &) doesn't exist in QList or
3884 QLinkedList. You can simulate it by calling
3885 \l{QLinkedList::append()}{append()} in a loop.
3886
3887 \o QValueList::insert(iterator, size_type, const T& x) doesn't
3888 exist in QList or QLinkedList. Call
3889 \l{QLinkedList::insert()}{insert()} repeatedly instead.
3890
3891 \o QValueList::fromLast() doesn't exist in QList or QLinkedList. Use
3892 QValueList::end() instead.
3893
3894 \oldcode
3895 for (QValueList<T>::iterator i = list.fromLast(); i != list.begin(); --i)
3896 do_something(*i);
3897 \newcode
3898 QLinkedList<T>::iterator i = list.end();
3899 while (i != list.begin()) {
3900 --i; // decrement i before using it
3901 do_something(*i);
3902 }
3903 \endcode
3904
3905 \o QValueList::append() and QValueList::prepend() return an
3906 iterator to the inserted item. QList's and QLinkedList's
3907 corresponding functions don't, but it's not a problem because
3908 QValueList::prepend() always returns begin() and append()
3909 always returns QValueList::end() - 1.
3910
3911 \o QValueList::at(\e i) return an iterator to the item at index
3912 \e i. This corresponds to QList::begin() + \e i.
3913
3914 \o QValueList::contains(const T &) corresponds to
3915 QList::count(const T &) and QLinkedList::count(const T &).
3916 \endlist
3917
3918 \section1 QValueVector<T>
3919
3920 The QValueVector<T> class has been replaced by QVector<T> in Qt
3921 4. As a help when porting older Qt applications, the Qt3Support
3922 library contains a Q3ValueVector<T> class implemented in terms of
3923 the new QVector<T>.
3924
3925 When porting from QValueVector<T> to QVector<T>, you might run
3926 into the following incompatibilities:
3927
3928 \list
3929 \o QValueVector(const std::vector<T> &) doesn't exist in QVector.
3930 You can simulate it by calling QVector::append()} in a loop.
3931 \o QValueVector::resize(int, const T &) doesn't exist in QVector.
3932 If you want the new items to be initialized with a particular
3933 value, use QVector::insert() instead.
3934 \o QValueVector::at() on a non-const vector returns a non-const
3935 reference. This corresponds to QVector::operator[]().
3936 \o Both QValueVector::at() functions have an \e ok parameter of
3937 type \c{bool *} that is set to true if the index is within
3938 bounds. This functionality doesn't exist in QVector; instead,
3939 check the index against QVector::size() yourself.
3940 \endlist
3941
3942 See \l{Container Classes} for an overview of the Qt 4 container
3943 classes.
3944
3945 \section1 QVariant
3946
3947 Some changes to the rest of the Qt library have
3948 implications on QVariant:
3949
3950 \list 1
3951 \o The \c QVariant::ColorGroup enum value is defined only
3952 if \c QT3_SUPPORT is defined.
3953 \o The \c QVariant::IconSet enum value has been renamed
3954 QVariant::Icon.
3955 \o The \c QVariant::CString enum value is now a synonym for
3956 QVariant::ByteArray.
3957 \endlist
3958
3959 Also, the QVariant(bool, int) constructor has been replaced by QVariant(bool).
3960 Old code like QVariant(true, 0) should be replaced with QVariant(true); otherwise,
3961 the QVariant(int, void *) overload might accidentally be triggered.
3962
3963 Many of QVariant's convenience functions in Qt 3, such as toColor() and
3964 toKeySequence(), have been removed to enable QVariant to be part of the
3965 QtCore module. QVariant is still able to hold values of these types.
3966
3967 Types which are not supported by any of the QVariant constructors can be
3968 stored as variants with the QVariant::fromValue() function. Types with no
3969 suitable convenience function for unpacking can be retrieved with the
3970 QVariant::value() function or passed directly to classes that implement
3971 the QVariant() operator.
3972
3973 \table
3974 \header \o Qt 3 function \o Qt 4 function
3975 \input porting/porting4-removedvariantfunctions.qdocinc
3976 \endtable
3977
3978 See the QVariant::Type enum for a list of types supported by QVariant.
3979
3980 \section1 QVBox
3981
3982 The \c QVBox class is now only available as Q3VBox in Qt 4. You
3983 can achieve the same result as \c QVBox by creating a QWidget
3984 with a vertical layout:
3985
3986 \oldcode
3987 QVBox *vbox = new QVBox;
3988 QPushButton *child1 = new QPushButton(vbox);
3989 QPushButton *child2 = new QPushButton(vbox);
3990 \newcode
3991 QWidget *vbox = new QWidget;
3992 QPushButton *child1 = new QPushButton;
3993 QPushButton *child2 = new QPushButton;
3994
3995 QVBoxLayout *layout = new QVBoxLayout;
3996 layout->addWidget(child1);
3997 layout->addWidget(child2);
3998 vbox->setLayout(layout);
3999 \endcode
4000
4001 Note that child widgets are not automatically placed into the widget's
4002 layout; you will need to manually add each widget to the QVBoxLayout.
4003
4004 \section1 QVGroupBox
4005
4006 The \c QVGroupBox class has been renamed Q3VGroupBox and moved to
4007 the Qt3Support library.
4008 Qt 4 does not provide a specific replacement class for \c QVGroupBox
4009 since QGroupBox is designed to be a generic container widget. As a
4010 result, you need to supply your own layout for any child widgets.
4011
4012 See \l{#QGroupBox} for more information about porting code that uses
4013 group boxes.
4014
4015 \section1 QWhatsThis
4016
4017 The QWhatsThis class has been redesigned in Qt 4. The old \c
4018 QWhatsThis class is available as Q3WhatsThis in Qt3Support.
4019
4020 \section1 QWidget
4021
4022 Widget background painting has been greatly improved, supporting
4023 flicker-free updates and making it possible to have
4024 semi-transparent widgets. This renders the following background
4025 handling functions obsolete:
4026
4027 \list
4028 \o QWidget::repaint(bool noErase) - the \c noErase boolean parameter is gone
4029 \o QWidget::setBackgroundMode(BackgroundMode m)
4030 \o QWidget::backgroundBrush() const
4031 \o QWidget::setBackgroundPixmap(const QPixmap &pm)
4032 \o QWidget::backgroundPixmap() const
4033 \o QWidget::setBackgroundColor(const QColor &c)
4034 \o QWidget::backgroundColor() const
4035 \o QWidget::foregroundColor() const
4036 \o QWidget::eraseColor() const
4037 \o QWidget::setEraseColor(const QColor &c)
4038 \o QWidget::erasePixmap() const
4039 \o QWidget::setErasePixmap(const QPixmap &p)
4040 \o QWidget::paletteForegroundColor()
4041 \o QWidget::setPaletteForegroundColor(const QColor &c)
4042 \o QWidget::paletteBackgroundColor()
4043 \o QWidget::setPaletteBackgroundColor(const QColor &c)
4044 \o QWidget::paletteBackgroundPixmap() const
4045 \o QWidget::setPaletteBackgroundPixmap(const QPixmap &p)
4046 \o QWidget::erase()
4047 \o QWidget::erase(const QRect &r)
4048 \o QWidget::setBackgroundOrigin( BackgroundOrigin )
4049 \o QWidget::BackgroundOrigin backgroundOrigin() const
4050 \o QWidget::backgroundOffset()
4051 \endlist
4052
4053 Sample code on how to do obtain similar behavior from Qt 4, previously
4054 handled by some of the above functions can be found in the
4055 \l{http://doc.qt.nokia.com/qwidget-qt3.html}{Qt 3 Support Members for QWidget}
4056 page.
4057
4058 A widget now receives change events in its QWidget::changeEvent()
4059 handler. This makes the following virtual change handlers obsolete:
4060
4061 \list
4062 \o QWidget::styleChange - use QEvent::StyleChange
4063 \o QWidget::enabledChange - use QEvent::EnabledChange
4064 \o QWidget::paletteChange - use QEvent::PaletteChange
4065 \o QWidget::fontChange - use QEvent::FontChange
4066 \o QWidget::windowActivationChange - use QEvent::ActivationChange
4067 \o QWidget::languageChange - use QEvent::LanguageChange
4068 \endlist
4069
4070 The following functions were slots, but are no more:
4071 \list
4072 \o QWidget::clearFocus()
4073 \o QWidget::setMouseTracking()
4074 \o QWidget::stackUnder(QWidget*)
4075 \o QWidget::move(int x, int y)
4076 \o QWidget::move(const QPoint &)
4077 \o QWidget::resize(int w, int h)
4078 \o QWidget::resize(const QSize &)
4079 \o QWidget::setGeometry(int x, int y, int w, int h)
4080 \o QWidget::setGeometry(const QRect &)
4081 \o QWidget::adjustSize()
4082 \o QWidget::update(int x, int y, int w, int h)
4083 \o QWidget::update(const QRect&)
4084 \o QWidget::repaint(bool erase)
4085 \o QWidget::repaint(int x, int y, int w, int h, bool erase)
4086 \o QWidget::repaint(const QRect &, bool erase)
4087 \o QWidget::repaint(const QRegion &, bool erase)
4088 \o QWidget::setCaption(const QString &)
4089 \o QWidget::setIcon(const QPixmap &)
4090 \o QWidget::setIconText(const QString &)
4091 \endlist
4092
4093 The following functions were incorrectly marked as virtual:
4094
4095 \list
4096 \o QWidget::close(bool alsoDelete)
4097 \o QWidget::create(WId, bool, bool)
4098 \o QWidget::destroy(bool)
4099 \o QWidget::move(int x, int y)
4100 \o QWidget::reparent(QWidget *parent, WFlags, const QPoint &, bool)
4101 \o QWidget::resize(int w, int h)
4102 \o QWidget::setAcceptDrops(bool on)
4103 \o QWidget::setActiveWindow()
4104 \o QWidget::setAutoMask(bool)
4105 \o QWidget::setBackgroundColor(const QColor &)
4106 \o QWidget::setBackgroundMode(BackgroundMode)
4107 \o QWidget::setBackgroundOrigin(BackgroundOrigin)
4108 \o QWidget::setBackgroundPixmap(const QPixmap &)
4109 \o QWidget::setCaption(const QString &)
4110 \o QWidget::setCursor(const QCursor &)
4111 \o QWidget::setEnabled(bool)
4112 \o QWidget::setEraseColor(const QColor &)
4113 \o QWidget::setErasePixmap(const QPixmap &)
4114 \o QWidget::setFocus()
4115 \o QWidget::setFocusPolicy(FocusPolicy)
4116 \o QWidget::setFocusProxy(QWidget *)
4117 \o QWidget::setFont(const QFont &)
4118 \o QWidget::setGeometry(const QRect &)
4119 \o QWidget::setGeometry(int x, int y, int w, int h)
4120 \o QWidget::setIcon(const QPixmap &)
4121 \o QWidget::setIconText(const QString &)
4122 \o QWidget::setKeyCompression(bool)
4123 \o QWidget::setMask(const QBitmap &)
4124 \o QWidget::setMask(const QRegion &)
4125 \o QWidget::setMaximumSize(int maxw, int maxh)
4126 \o QWidget::setMicroFocusHint(int x, int y, int w, int h, bool, QFont *f)
4127 \o QWidget::setMinimumSize(int minw, int minh)
4128 \o QWidget::setMouseTracking(bool enable)
4129 \o QWidget::setPalette(const QPalette &)
4130 \o QWidget::setPaletteBackgroundColor(const QColor &)
4131 \o QWidget::setPaletteBackgroundPixmap(const QPixmap &)
4132 \o QWidget::setSizeIncrement(int w, int h)
4133 \o QWidget::setSizePolicy(QSizePolicy)
4134 \o QWidget::setUpdatesEnabled(bool enable)
4135 \o QWidget::setWState(uint)
4136 \o QWidget::show()
4137 \o QWidget::showFullScreen()
4138 \o QWidget::showMaximized()
4139 \o QWidget::showMinimized()
4140 \o QWidget::showNormal()
4141 \o QWidget::sizePolicy()
4142 \o QWidget::unsetCursor()
4143 \endlist
4144
4145 The internal clearWState() function was removed. Use
4146 QWidget::setAttribute() instead.
4147
4148 setWFlags() was renamed QWidget::setWindowFlags().
4149
4150 clearWFlags() has no direct replacement. You can use
4151 QWidget::setAttribute() instead. For example,
4152 \c{setAttribute(..., false)} to clear an attribute. More information
4153 is available \l{http://doc.qt.nokia.com/qwidget.html#setAttribute}{here}.
4154
4155 testWFlags() was renamed to \l{QWidget::testAttribute()}{testAttribute()}.
4156
4157 See \l{#properties}{Properties} for a list of QWidget properties
4158 in Qt 3 that have changed in Qt 4.
4159
4160 \section1 QWidgetFactory
4161
4162 The \c QWidgetFactory class has been replaced by QFormBuilder in Qt 4.
4163
4164 \section1 QWidgetIntDict
4165
4166 The QWidgetIntDict class was a synonym for QIntDict<QWidget>. It
4167 is no longer available in Qt 4. If you link against Qt3Support,
4168 you can use Q3IntDict<QWidget> instead; otherwise, see the
4169 \l{#qdict.section}{section on QDict<T>}.
4170
4171 \target qwidgetlist.section
4172 \section1 QWidgetList
4173
4174 In Qt 3, the QWidgetList class was a typedef for
4175 QPtrList<QWidget>. In Qt 4, it is a typedef for QList<QWidget *>.
4176 See the \l{#qptrlist.section}{section on QPtrList<T>}.
4177
4178 \section1 QWidgetPlugin
4179
4180 The QWidgetPlugin class is no longer available in Qt 4. To create
4181 custom widget plugins, subclass QDesignerCustomWidgetInterface to
4182 provide information about the custom widget, and build a plugin in
4183 the way described in the \l{designer/customwidgetplugin}{Custom
4184 Widget Plugin} example.
4185
4186 \section1 QWidgetStack
4187
4188 The QWidgetStack class is no longer part of the Qt public API. It
4189 has been renamed Q3WidgetStack and moved to Qt3Support. In Qt 4
4190 applications, you can use QStackedWidget instead to obtain the
4191 same results.
4192
4193 \section1 QWizard
4194
4195 The \c QWizard class was reintroduced in Qt 4.3. See the
4196 \l{Trivial Wizard Example}, \l{License Wizard Example} and
4197 \l{Class Wizard Example} for more details.
4198
4199 \section1 QWorkspace
4200
4201 The \c QWorkspace in Qt 4 class requires explicit adding of MDI
4202 windows with QWorkspace::addWindow().
4203*/
4204
4205/*!
4206 \page porting4-virtual-functions.html
4207 \title Porting to Qt 4 - Virtual Functions
4208 \contentspage {Porting Guides}{Contents}
4209 \previouspage Porting to Qt 4
4210 \nextpage Porting to Qt 4 - Drag and Drop
4211 \ingroup porting
4212 \brief An overview of changes to virtual functions in Qt 4.
4213
4214 \section1 Virtual Functions
4215
4216 Virtual functions that changed their signature in Qt 4:
4217
4218 \table
4219 \header \o Qt 3 function signature \o Qt 4 function signature
4220 \input porting/porting4-modifiedvirtual.qdocinc
4221 \endtable
4222
4223 Virtual functions that are not virtual in Qt 4:
4224
4225 \table
4226 \header \o Qt 3 function \o Comment
4227 \input porting/porting4-removedvirtual.qdocinc
4228 \endtable
4229*/
Note: See TracBrowser for help on using the repository browser.