source: trunk/doc/src/porting4.qdoc@ 424

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \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://lists.trolltech.com/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 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 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 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} \c .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 \c .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()