/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \group porting

    \title Porting Guides

    \brief Guides related to porting Qt applications and libraries.

    \ingroup best-practices

    A number of guides and documents are available that cover porting issues,

    from detailed coverage of API differences between Qt 3 and Qt 4 to

    platform and tool-specific documentation.

    \generatelist{related}

*/

/*!

    \page porting4.html

    \title Porting to Qt 4

    \contentspage {Porting Guides}{Contents}

    \previouspage Porting Guides

    \nextpage Porting to Qt 4 - Virtual Functions

    \ingroup porting

    \brief An overview of issues and techniques to consider when porting from Qt 3 to Qt 4.

\omit

    ### QFileInfo::PermissionSpec -> QFile::Permission(s?)

    ### refer to porting4-renamedfunctions.qdoc

    ### QApplication library mutex is gone

    ### no integral conversion for containers? strings?

    ### QVector etc. are initialized to 0 by default?

    ### How to port from Qt 2.3 to Qt 4.

    ### missing sort() functions?

    ### QToolTipGroup

    ### QServerSocket -> Q3ServerSocket

    ### remove these when the classes are re-ported

    ### QApplication::eventLoop()

    \row \o void QCheckListItem::paintCell(QPainter *, const QColorGroup &, int, int, int)\row \o void Q3CheckListItem::paintCell(QPainter *, const QPalette &, int, int, int)

    \row \o void QCheckListItem::paintFocus(QPainter *, const QColorGroup &, const QRect &) \o void Q3CheckListItem::paintFocus(QPainter *, const QPalette &, const QRect &)

    \row \o QDataTable: a whole bunch of virtual functions have a different signature

    <     Function: void QIconViewItem::paintFocus(QPainter *, const QColorGroup &)

    >     Function: void QIconViewItem::paintFocus(QPainter *, const QPalette &)

    <     Function: void QIconViewItem::paintItem(QPainter *, const QColorGroup &)

    >     Function: void QIconViewItem::paintItem(QPainter *, const QPalette &)

    <     Function: bool QUrlOperator::checkValid()

    <     Function: void QWSInputMethod::setFont(const QFont &)

    ### OpenMode or OpenMode

    ### QWSDecoration

\endomit

    This document describes the process of porting applications from

    Qt 3 to Qt 4.

    If you haven't yet made the decision about porting, or are unsure

    about whether it is worth it, take a look at the \l{What's New in

    Qt 4}{key features} offered by Qt 4. See also

    \l{Moving from Qt 3 to Qt 4} for tips on how to write Qt 3 code

    that is easy to port to Qt 4.

    \bold{Other porting guides:}

    \list

    \o \l{Moving from Qt 3 to Qt 4} \mdash covers some high level topics relevant

       to developers porting from Qt 3 to Qt 4.

    \o \l{Porting to Qt 4 - Drag and Drop} \mdash covers differences in the

       way drag and drop is handled between Qt 3 and Qt 4.

    \o \l{Porting UI Files to Qt 4} \mdash describes the new format used to

       describe forms created with \QD.

    \o \l{Porting to Graphics View} \mdash provides a class-by-class overview

       of the differences between Qt 3's canvas API and Qt 4's Graphics

       View framework.

    \o \l{qt3to4 - The Qt 3 to 4 Porting Tool} \mdash provides an overview

       of a tool aimed at helping developers start the process of porting an

       application to Qt 4.

    \endlist

    The Qt 4 series is not binary compatible with the 3 series. This

    means programs compiled for Qt 3 must be recompiled to work with

    Qt 4. Qt 4 is also not completely \e source compatible with 3,

    however nearly all points of incompatibility cause compiler

    errors or run-time messages (rather than mysterious results). Qt

    4 includes many additional features and discards obsolete

    functionality. Porting from Qt 3 to Qt 4 requires some effort,

    but once completed the considerable additional power and

    flexibility of Qt 4 is available for use in your applications.

    To port code from Qt 3 to Qt 4:

    \list 1

    \o Briefly read the porting notes below to get an idea of what to expect.

    \o Be sure that your code compiles and runs well on all your target

       platforms with Qt 3.

    \o Add the line \c{QT += qt3support} to your \c .pro file if you use

       \c qmake; otherwise, edit your makefile or project file to

       link against the Qt3Support library and add \c -DQT3_SUPPORT to your

       compiler flags. (You might also need to specify other

       libraries. See \l{What's New in Qt 4} for details.)

    \o Run the \l qt3to4 porting tool. The tool will go through your

       source code and adapt it to Qt 4.

    \o Follow the instructions in the \l{Porting UI Files to Qt 4}

       page to port Qt Designer files.

    \o Recompile with Qt 4. For each error, search below for related

       identifiers (e.g., function names, class names). This document

       mentions all relevant identifiers to help you get the information

       you need at the cost of being a little verbose.

    \endlist

    The \l qt3to4 porting tool replaces occurrences of Qt 3 classes

    that don't exist anymore in Qt 4 with the corresponding Qt 3

    support class; for example, \c QListBox is turned into \c

    Q3ListBox.

    At some point, you might want to stop linking against the Qt 3

    support library (\l{Qt3Support}) and take advantage of Qt 4's

    new features. The instructions below explain how to do that for

    each compatibility class.

    In addition to the Qt3Support classes (such as \c Q3Action, \c

    Q3ListBox, and \c Q3ValueList), Qt 4 provides compatibility

    functions when it's possible for an old API to cohabit with the

    new one. For example, QString provides a

    QString::simplifyWhiteSpace() compatibility function that's

    implemented inline and that simply calls QString::simplified().

    \bold{The compatibility functions are not documented here; instead,

    they are documented for each class.}

    If you have the line \c{QT += qt3support} in your \c .pro file, \c

    qmake will automatically define the \c QT3_SUPPORT symbol, turning

    on compatibility function support. You can also define the symbol

    manually (e.g., if you don't want to link against the \c

    Qt3Support library), or you can define \c QT3_SUPPORT_WARNINGS

    instead, telling the compiler to emit a warning when a

    compatibility function is called. (This works only with GCC 3.2+

    and MSVC 7.)

    If you get stuck, ask on the

    \l{http://qt.nokia.com/lists/qt-interest/}{qt-interest}

    mailing list. If you are a licensed customer, you can also contact

    Qt's technical support team.

\omit

    ### what to do with slots that aren't slots anymore

    ### what to do with virtual functions that aren't virtual anymore

    ### what to do with virtual functions that changed signature

\endomit

\omit

    ### <qtl.h> -- stuff that vanished?

    ### implicit sharing

    ### uint -> int indexes

\endomit

    Table of contents:

    \tableofcontents{4}

\omit

    \section1 Header Files

    ### New style of headers

    \table

    \header \o Old header \o New header

    \row \o \c{<qtl.h>} \o \c{<qalgorithms.h>} or \c{<QtAlgorithms>}

    \endtable

    ### Some headers don't include each other anymore...

\endomit

    \section1 Casting and Object Types

    In Qt 3, it was possible to use the \c qt_cast() function to determine

    whether instances of QObject subclasses could be safely cast to derived

    types of those subclasses. For example, if a QFrame instance is passed

    to a function whose signature specifies a QWidget pointer as its argument,

    \c qt_cast() could be used to obtain a QFrame pointer so that the

    instance's functions can be accessed.

    In Qt 4, much of this functionality is provided by the qobject_cast()

    function, and additional functions also provide similar functionality for

    certain non-QObject types:

    \table

    \header \o Qt 3 function \o Qt 4 function

    \row    \o T *qt_cast<T *>(QObject *) \o \l{qobject_cast()}{T *qobject_cast<T *>(QObject *)}

    \row    \o                            \o \l{qgraphicsitem_cast()}{T qgraphicsitem_cast<T>(QGraphicsItem *)}

    \row    \o                            \o \l{qstyleoption_cast()}{T qstyleoption_cast<T>(QStyleOption *)}

    \row    \o                            \o \l{qvariant_cast()}{T qvariant_cast<T>(const QVariant &)}

    \row    \o                            \o \l{qdbus_cast()}{T qdbus_cast(const QDBusArgument &)}

    \endtable

\omit

    \section1 Global Functions

    \table

    \header \o Qt 3 function \o Qt 4 function

    \row \o cstrcmp() \o strcmp()

    \row \o cstrcpy() \o strcpy()

    \row \o cstrlen() \o strlen()

    \row \o cstrncmp() \o strncmp()

    \row \o qmemmove() \o memmove()

    \endtable

    qGLVersion() ###

    copyBlt() ###

    bitBlt()

    #ifdef compat classes:

        * QLayoutIterator

        * QColorGroup

        * QMenuItem

    QWidget visibleRect property compat

    QWidget::BackgroundOrigin compat

\endomit

    \section1 Type Names

    The table below lists the classes that have been renamed in Qt 4.

    If you compile your applications with \c QT3_SUPPORT defined, the

    old names will be available.

    Whenever you see an occurrence of the name on the left, you can

    safely replace it with the Qt 4 equivalent in your program. The

    \l qt3to4 tool performs the conversion automatically.

    \table

    \header \o Qt 3 class name \o Qt 4 class name

    \input porting/porting4-renamedclasses.qdocinc

    \endtable

    The table below lists the enums and typedefs that have been

    renamed in Qt 4. If you compile your applications with \c

    QT3_SUPPORT defined, the old names will be available.

    Whenever you see an occurrence of the name on the left, you can

    safely replace it with the Qt 4 equivalent in your program. The

    \l qt3to4 tool performs the conversion

    automatically.

    \table

    \header \o Qt 3 type name \o Qt 4 type name

    \input porting/porting4-renamedtypes.qdocinc

    \endtable

    \omit

    ###

    \row \o QButton::ToggleState \o Use QCheckBox::ToggleState instead.

    \endomit

    \section1 Enum Values

    The table below lists the enum values that have been renamed in

    Qt 4. If you compile your applications with \c QT3_SUPPORT defined,

    the old names will be available.

    Whenever you see an occurrence of the name on the left, you can

    safely replace it with the Qt 4 equivalent in your program. The

    \l qt3to4 tool performs the conversion automatically.

    \table

    \header \o Qt 3 enum value name \o Qt 4 enum value name

    \input porting/porting4-renamedenumvalues.qdocinc

    \endtable

    In addition, the following \l{Qt::WindowFlags}{window flags} have

    been either replaced with \l{Qt::WidgetAttribute}{widget

    attributes} or have been deprecated:

    \table

    \header \o Qt 3 type \o Qt 4 equivalent

    \row \o Qt::WDestructiveClose \o Use QWidget::setAttribute(Qt::WA_DeleteOnClose) instead.

    \row \o Qt::WStaticContents \o{1,2} Use QWidget::setAttribute(Qt::WA_StaticContents) instead.

    \row \o Qt::WNorthWestGravity

    \row \o Qt::WNoAutoErase \o{1,3} Use QWidget::setAttribute(Qt::WA_NoBackground) instead.

    \row \o Qt::WResizeNoErase

    \row \o Qt::WRepaintNoErase

    \row \o Qt::WPaintClever \o Unnecessary in Qt 4.

         \omit ### Check with Matthias \endomit

    \row \o Qt::WMacNoSheet \o Unnecessary in Qt 4.

         \omit ### Check with Sam \endomit

    \endtable

    In Qt 4.1, the widget flags used to determine window modality were

    replaced by a single enum that can be used to specify the modal

    behavior of top-level widgets:

    \table

    \header \o Qt 3 type \o Qt 4 equivalent

    \row \o Qt::WShowModal \o Use QWidget::setWindowModality(Qt::ApplicationModal) instead.

    \row \o Qt::WGroupLeader \o Use QWidget::setWindowModality(Qt::WindowModal)

         for each child dialog of the group leader, but do not change the modality

         of the group leader itself.

    \endtable

    \target properties

    \section1 Properties

    Some properties have been renamed in Qt 4, to make Qt's API more

    consistent and more intuitive. For example, QWidget's \c caption

    property has been renamed \c windowTitle to make it clear that it

    refers to the title shown in the window's title bar.

    In addition, the property system has been extended to allow

    properties to be redefined in subclasses with the \l Q_PROPERTY()

    macro, removing the need for a \c Q_OVERRIDE() macro.

    The table below lists the Qt properties that have been renamed in

    Qt 4. Occurrences of these in \e{Qt Designer} UI files are

    automatically converted to the new name by \c uic.

    \table

    \header \o Qt 3 name \o Qt 4 name

    \row \o QButton::accel \o QButton::shortcut

    \row \o QButton::on \o QButton::checked

    \row \o QButton::toggleButton \o QAbstractButton::checkable

    \row \o QDial::lineStep \o QDial::singleStep

    \row \o QDial::maxValue \o QDial::maximum

    \row \o QDial::minValue \o QDial::minimum

    \row \o QDialog::modal \o QDialog::isModal

    \row \o QLineEdit::edited \o QLineEdit::modified

    \row \o QLineEdit::hasMarkedText \o QLineEdit::hasSelectedText

    \row \o QLineEdit::markedText \o QLineEdit::selectedText

    \row \o QObject::name \o QObject::objectName

    \row \o QProgressDialog::progress \o QProgressDialog::value

    \row \o QProgressDialog::totalSteps \o QProgressDialog::maximum

    \row \o QProgressDialog::wasCancelled \o QProgressDialog::wasCanceled

    \row \o QPushButton::iconSet \o QPushButton::icon

    \row \o QScrollBar::draggingSlider \o QScrollBar::sliderDown

    \row \o QScrollBar::lineStep \o QScrollBar::singleStep

    \row \o QScrollBar::maxValue \o QScrollBar::maximum

    \row \o QScrollBar::minValue \o QScrollBar::minimum

    \row \o QSlider::lineStep \o QSlider::singleStep

    \row \o QSlider::maxValue \o QSlider::maximum

    \row \o QSlider::minValue \o QSlider::minimum

    \row \o QSpinBox::lineStep \o QSpinBox::singleStep

    \row \o QSpinBox::maxValue \o QSpinBox::maximum

    \row \o QSpinBox::minValue \o QSpinBox::minimum

    \row \o QTabBar::currentTab \o QTabBar::currentIndex

    \row \o QTabWidget::currentPage \o QTabWidget::currentWidget

    \row \o QToolButton::iconSet \o QToolButton::icon

    \row \o QToolButton::textLabel \o QToolButton::text

    \row \o QWidget::caption \o QWidget::windowTitle

    \row \o QWidget::icon \o QWidget::windowIcon

    \row \o QWidget::iconText \o QWidget::windowIconText

    \endtable

    A handful of properties in Qt 3 are no longer properties in Qt 4,

    but the access functions still exist as part of the Qt 4 API.

    These are not used by \e{Qt Designer}; the only case where you

    need to worry about them is in highly dynamic applications that

    use Qt's meta-object system to access properties. Here's the list

    of these properties with the read and write functions that you

    can use instead:

    \table

    \header \o Qt 3 property \o Qt 4 read function \o Qt 4 write function

    \row \o QSqlDatabase::connectOptions \o QSqlDatabase::connectOptions() \o QSqlDatabase::setConnectOptions()

    \row \o QSqlDatabase::databaseName \o QSqlDatabase::databaseName() \o QSqlDatabase::setDatabaseName()

    \row \o QSqlDatabase::hostName \o QSqlDatabase::hostName() \o QSqlDatabase::setHostName()

    \row \o QSqlDatabase::password \o QSqlDatabase::password() \o QSqlDatabase::setPassword()

    \row \o QSqlDatabase::port \o QSqlDatabase::port() \o QSqlDatabase::setPort()

    \row \o QSqlDatabase::userName \o QSqlDatabase::userName() \o QSqlDatabase::setUserName()

    \endtable

    Some properties have been removed from Qt 4, but the associated

    access functions are provided if \c QT3_SUPPORT is defined to help

    porting to Qt 4. When converting Qt 3 UI files to Qt 4, \c uic

    generates calls to the Qt 3 compatibility functions. Note that

    this only applies to the properties of the Qt3Support library,

    i.e. \c QT3_SUPPORT properties of the other libraries must be

    ported manually when converting Qt 3 UI files to Qt 4.

    The table below lists these properties with the read and write

    functions that you can use instead. The documentation for the

    individual functions explains how to replace them with

    non-compatibility Qt 4 functions.

    \table

    \header \o Qt 3 property \o Qt 4 read function (\c QT3_SUPPORT)\o Qt 4 write function (\c QT3_SUPPORT)

    \row \o QMenuBar::separator \o QMenuBar::separator() \o QMenuBar::setSeparator()

    \row \o QPushButton::menuButton \o QPushButton::isMenuButton() \o N/A

    \row \o QTabWidget::margin \o QTabWidget::margin() \o QTabWidget::setMargin()

    \row \o QTextEdit::textFormat \o QTextEdit::textFormat() \o QTextEdit::setTextFormat()

    \row \o QWidget::backgroundBrush \o QWidget::backgroundBrush() \o N/A

    \row \o QWidget::backgroundMode \o QWidget::backgroundMode() \o QWidget::setBackgroundMode()

    \row \o QWidget::backgroundOrigin \o QWidget::backgroundOrigin() \o QWidget::setBackgroundOrigin()

    \row \o QWidget::colorGroup \o QWidget::colorGroup() \o QWidget::setColorGroup()

    \row \o QWidget::customWhatsThis \o QWidget::customWhatsThis() \o QWidget::setCustomWhatsThis()

    \row \o QWidget::inputMethodEnabled \o QWidget::inputMethodEnabled() \o QWidget::setInputMethodEnabled()

    \row \o QWidget::ownCursor \o QWidget::ownCursor() \o N/A

    \row \o QWidget::ownFont \o QWidget::ownFont() \o N/A

    \row \o QWidget::ownPalette \o QWidget::ownPalette() \o N/A

    \row \o QWidget::paletteBackgroundColor \o QWidget::paletteBackgroundColor() \o QWidget::setPaletteBackgroundColor()

    \row \o QWidget::paletteBackgroundPixmap \o QWidget::paletteBackgroundPixmap() \o QWidget::setPaletteBackgroundPixmap()

    \row \o QWidget::paletteForegroundColor \o QWidget::paletteForegroundColor() \o QWidget::setPaletteForegroundColor()

    \row \o QWidget::underMouse \o QWidget::underMouse() \o N/A

    \endtable

    The following Qt 3 properties and their access functions are no

    longer available in Qt 4. In most cases, Qt 4 provides similar

    functionality.

    \table

    \header \o Qt 3 property \o Qt 4 equivalent

    \row \o QButton::autoRepeat \o N/A

    \row \o QButton::autoResize \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents.

    \row \o QButton::exclusiveToggle \o See \l QAbstractButton::autoExclusive.

    \row \o QButton::pixmap \o Use QAbstractButton::icon instead.

    \row \o QButton::toggleState \o Use QCheckBox::setState() and QCheckBox::state() instead.

    \row \o QButton::toggleType \o Use QCheckBox::setTristate() instead.

    \row \o QComboBox::autoResize \o Call QWidget:setFixedSize(QWidget::sizeHint()) whenever you change the contents.

    \row \o QFrame::contentsRect \o Use Q3Frame::contentsRect() instead.

    \row \o QFrame::margin \o Use QWidget::setContentsMargins() instead.

    \row \o QTabBar::keyboardFocusTab \o N/A

    \row \o QToolButton::offIconSet \o Use the \l{QIcon::Off}{off component} of QAbstractButton::icon instead.

    \row \o QToolButton::onIconSet \o Use the \l{QIcon::On}{on component} of QAbstractButton::icon instead.

    \row \o QWidget::microFocusHint \o N/A

    \row \o QMimeSource::serialNumber () \o N/A 

    \endtable

\omit

    \section1 Inheritance Chain

    ### QMenuBar, etc.

    \section1 Null vs. Empty

    ###

\endomit

    \section1 Explicit Sharing

    Qt 4 is the first version of Qt that contains no \link

    http://qt.nokia.com/doc/3.3/shclass.html explicitly shared

    \endlink classes. All classes that were explicitly shared in Qt 3

    are \e implicitly shared in Qt 4:

    \list

    \o QImage

    \o QBitArray

    \o QByteArray

    \o Q3PointArray

    \endlist

    This means that if you took a copy of an instance of the class

    (using operator=() or the class's copy constructor), any

    modification to the copy would affect the original and vice

    versa. Needless to say, this behavior is rarely desirable.

    Fortunately, nearly all Qt 3 applications don't rely on explicit

    sharing. When porting, you typically only need to remove calls to

    detach() and/or copy(), which aren't necessary anymore.

    If you deliberately rely on explicit sharing in your application,

    you can use pointers or references to achieve the same result in

    Qt 4.

    \oldcode

        void asciify(QByteArray array)

        {

            for (int i = 0; i < (int)array.size(); ++i) {

                if ((uchar)array[i] >= 128)

                    array[i] = '?';

            }

        }

    \newcode

        void asciify(QByteArray &array)

        {

            for (int i = 0; i < array.size(); ++i) {

                if ((uchar)array[i] >= 128)

                    array[i] = '?';

            }

        }

    \endcode