Update copyright headers
[qt:qt.git] / doc / src / porting / porting4.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \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.cpp 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.cpp 1
864
865         will no longer compile. Instead, use QByteArray::operator[]:
866
867         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 3
939
940     becomes
941
942         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 5
954
955         becomes
956
957         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 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.cpp 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.cpp 9
1420         \o
1421         \snippet doc/src/snippets/code/doc_src_porting4.cpp 10
1422     \row
1423         \o
1424         \snippet doc/src/snippets/code/doc_src_porting4.cpp 11
1425         \o
1426         \snippet doc/src/snippets/code/doc_src_porting4.cpp 12
1427     \row
1428         \o
1429         \snippet doc/src/snippets/code/doc_src_porting4.cpp 13
1430
1431         (also called from Q3Dict's destructor)
1432
1433         \o
1434         \snippet doc/src/snippets/code/doc_src_porting4.cpp 14
1435
1436         In 99% of cases, the following idiom also works:
1437
1438         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 16
1475
1476     Here's the equivalent QHashIterator loop:
1477
1478     \snippet doc/src/snippets/code/doc_src_porting4.cpp 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() instead of QObject::queryList().
2378     For example:
2379
2380     \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 19
2716         \o
2717         \snippet doc/src/snippets/code/doc_src_porting4.cpp 20
2718     \row
2719         \o
2720         \snippet doc/src/snippets/code/doc_src_porting4.cpp 21
2721         \o
2722         \snippet doc/src/snippets/code/doc_src_porting4.cpp 22
2723     \row
2724         \o
2725         \snippet doc/src/snippets/code/doc_src_porting4.cpp 23
2726         \o
2727         \snippet doc/src/snippets/code/doc_src_porting4.cpp 24
2728     \row
2729         \o
2730         \snippet doc/src/snippets/code/doc_src_porting4.cpp 25
2731         \o
2732         \snippet doc/src/snippets/code/doc_src_porting4.cpp 26
2733     \row
2734         \o
2735         \snippet doc/src/snippets/code/doc_src_porting4.cpp 27
2736         \o
2737         \snippet doc/src/snippets/code/doc_src_porting4.cpp 28
2738     \row
2739         \o
2740         \snippet doc/src/snippets/code/doc_src_porting4.cpp 29
2741         (removes the current item)
2742
2743         \o
2744         \snippet doc/src/snippets/code/doc_src_porting4.cpp 30
2745     \row
2746         \o
2747         \snippet doc/src/snippets/code/doc_src_porting4.cpp 31
2748
2749         (also called from QPtrList's destructor)
2750
2751         \o
2752         \snippet doc/src/snippets/code/doc_src_porting4.cpp 32
2753
2754         In 99% of cases, the following idiom also works:
2755
2756         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 34
2794
2795     Here's the equivalent QListIterator loop:
2796
2797     \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 36
2825
2826     Here's the equivalent QListIterator loop:
2827
2828     \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 38
2868         \o
2869         \snippet doc/src/snippets/code/doc_src_porting4.cpp 39
2870     \row
2871         \o
2872         \snippet doc/src/snippets/code/doc_src_porting4.cpp 40
2873         \o
2874         \snippet doc/src/snippets/code/doc_src_porting4.cpp 41
2875     \row
2876         \o
2877         \snippet doc/src/snippets/code/doc_src_porting4.cpp 42
2878
2879         (also called from QPtrQueue's destructor)
2880
2881         \o
2882         \snippet doc/src/snippets/code/doc_src_porting4.cpp 43
2883
2884         In 99% of cases, the following idiom also works:
2885
2886         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 45
2927         \o
2928         \snippet doc/src/snippets/code/doc_src_porting4.cpp 46
2929     \row
2930         \o
2931         \snippet doc/src/snippets/code/doc_src_porting4.cpp 47
2932         \o
2933         \snippet doc/src/snippets/code/doc_src_porting4.cpp 48
2934     \row
2935         \o
2936         \snippet doc/src/snippets/code/doc_src_porting4.cpp 49
2937
2938         (also called from QPtrStack's destructor)
2939
2940         \o
2941         \snippet doc/src/snippets/code/doc_src_porting4.cpp 50
2942
2943         In 99% of cases, the following idiom also works:
2944
2945         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 52
3028         \o
3029         \snippet doc/src/snippets/code/doc_src_porting4.cpp 53
3030     \row
3031         \o
3032         \snippet doc/src/snippets/code/doc_src_porting4.cpp 54
3033         \o
3034         \snippet doc/src/snippets/code/doc_src_porting4.cpp 55
3035     \row
3036         \o
3037         \snippet doc/src/snippets/code/doc_src_porting4.cpp 56
3038         \o
3039         \snippet doc/src/snippets/code/doc_src_porting4.cpp 57
3040     \row
3041         \o
3042         \snippet doc/src/snippets/code/doc_src_porting4.cpp 58
3043         \o
3044         \snippet doc/src/snippets/code/doc_src_porting4.cpp 59
3045     \row
3046         \o
3047         \snippet doc/src/snippets/code/doc_src_porting4.cpp 60
3048
3049         (also called from QPtrVector's destructor)
3050
3051         \o
3052         \snippet doc/src/snippets/code/doc_src_porting4.cpp 61
3053
3054         In 99% of cases, the following idiom also works:
3055
3056         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 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.cpp 63a
3221
3222     However, with QTextDocument, you use the following code instead:
3223
3224     \snippet doc/src/snippets/code/doc_src_porting4.cpp 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.cpp 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.cpp 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.cpp 65
3468
3469         will no longer compile. Instead, use QString::operator[]:
3470
3471         \snippet doc/src/snippets/code/doc_src_porting4.cpp 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