path: root/doc/src/porting4-overview.qdoc

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** 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 either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** 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 http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page porting4-overview.html
    \title Moving from Qt 3 to Qt 4
    \ingroup porting
    \brief Porting advice for authors of new and existing Qt 3 applications.

    This document describes which parts of Qt should be used when
    writing an application with Qt 3, so that it can be upgraded to
    use Qt 4 later with a minimum of effort. However, the advice may
    also be useful to developers who are porting existing applications
    from Qt 3 to Qt 4.

    For a detailed overview
    of the porting process for existing Qt 3 applications, see the
    \l{Porting to Qt 4} document.

    \tableofcontents

    Since Qt 4 provides important new functionality at the cost of
    some compatibility with Qt 3, it is useful for developers of
    Qt 3-based applications to learn how to take advantage of
    Qt 3's API now while preparing for future changes that will be
    needed when upgrading to Qt 4.

    Certain advanced Qt 3 features were moved to the Qt 3 support
    library (\l{Qt3Support}) in Qt 4.0, and have been gradually
    replaced in subsequent releases of Qt 4.

    Making Qt 3 applications as portable to Qt 4 as possible
    enables a smooth transition between versions of Qt in the
    long term, and allows for a stable development process
    throughout.

    \section1 Qt 3 Features to Avoid

    Although we are proud of the level of stability we have achieved
    with Qt, it is important to realise that, for Qt 4 to be a
    substantial improvement over Qt 3, certain features have
    been revised to make the framework more maintainable for us
    and more usable for developers. It is therefore useful to
    know which features of Qt 3 should be avoided to help save
    time during a later porting effort to Qt 4. Note that it is
    still possible to use many of the following classes and
    features through the use of the \l{Qt3Support} module.

    \section2 Painting Outside Paint Events

    In Qt 3, under certain circumstances, it was possible to use
    QPainter to draw on a given custom widget outside its
    \l{QWidget::}{paintEvent()} reimplementation. In Qt 4, in most
    situations, painting must occur within a widget's paint event
    handler.

    On X11, it is possible to set the \l{Qt::WA_PaintOutsidePaintEvent}
    attribute on widgets to keep existing code, but we recommend
    restricting the use of painting code to within paint event handlers
    where possible.

    More information about this change can be found in the
    \l{Porting to Qt 4#Painting and Redrawing Widgets}{Painting and Redrawing Widgets}
    section of the \l{Porting to Qt 4} document.

    \section2 Qt Designer

    The version of Qt Designer supplied with Qt 3 provided
    extensive code editing and project management features
    (control over \c{.ui.h} and \c{.pro} files), and encouraged
    users to design main window applications from within the
    Qt Designer environment.

    The version of Qt Designer supplied with Qt 4 is intended
    to be integrated with other software development tools (such
    as integrated development environments), and does not
    support these project-level features.

    We recommend using one of the
    \l{Using a Designer .ui File in Your Application}{form subclassing approaches}
    with forms created using Qt Designer. This avoids the need
    to use \c{.ui.h} files and special purpose code editors.

    Existing Qt 3 forms created using Qt Designer can be gradually
    ported to Qt 4 by following the advice in the
    \l{Porting .ui Files to Qt 4} guide. However, some extra effort
    will be required to move application logic from \c{.ui.h} files
    into the main body of a Qt 4 application.

    \section2 Menu Items (QMenuItem)

    The old-style construction of menus by creating individual
    menu items has been superseded in Qt 4 by the use of
    generic actions which can be used in menus, toolbars, and
    as keyboard shortcuts.

    Qt 3 also supports this action-based approach, so, by using
    QAction throughout your application, less work will be
    required to adapt your application to Qt 4.

    \section2 Pointer-Based Classes (QPtr*)

    Qt 3 provides a group of pointer-based classes (\c QPtrList,
    \c QPtrDict, \c QPtrVector, etc.) that help manage collections
    of pointers to objects (usually QObject subclasses) in an
    application. In addition, the value-based collection classes
    (\c QValueList, \c QValueDict, \c QValueVector, etc.) provide
    a way to store standard value types which cannot be easily stored
    in pointer-based collections.

    Qt 4 introduces a single set of collection classes which
    does not require developers to pay as much attention to
    memory allocation and object ownership issues. As a result,
    Qt 3's pointer-based classes have no direct equivalent
    classes in Qt 4.

    To ease migration, use Qt 3's value-based classes to store
    most objects, including pointers; for example, use
    \c QValueVector<QWidget *> rather than
    \c QPtrVector<QWidget *>. These can be replaced by
    Qt 4's QVector, QLinkedList, and QList later.

    \section2 Other Collection Classes (QStrList, Q*Dict)

    Some collection classes in Qt 3 have been deprecated in
    favor of easier to use, higher level alternatives. These
    include the dictionary classes (\c QAsciiDict, \c QDict,
    \c QIntDict, \c QPtrDict) and \c QStrList.

    \c QStrList can usually replaced by the higher level QStringList
    class in Qt 3; this is also available in Qt 4. It is
    recommended that you use the QMap class instead of the \c QDict
    classes. In Qt 4, QMap is also complemented by the QHash
    class.

    \section2 Memory Arrays (QMemArray)

    In Qt 3, the \c QMemArray class is used as a simple array
    container for simple data types. This class is deprecated in
    Qt 4 in favor of the QVector and QVarLengthVector classes
    which provide more powerful and consistent array objects.

    Qt 3's closest equivalent class to Qt 4's QVector is the
    \c QValueVector class. For many purposes, this can be used
    instead of \c QMemArray.

    \section2 URL Operations (QUrlOperator)

    The URL operator in Qt 3 provides an abstract way to
    handle files via HTTP, FTP, and on the local file system.
    However, Qt 4 only provides this functionality through the
    use of the Q3UrlOperator.

    From Qt 4.4, the Network Access API provides a subset of the features
    provided by \c QUrlOperator that are mostly intended for use with
    applications that use the HTTP and FTP protocols. See the
    QNetworkRequest, QNetworkReply, and QNetworkAccessManager documentation
    for further details.

    It is also possible to perform operations on remote files
    through the QHttp and QFtp classes, and on local files with
    the QFile class.

    \section2 SQL Cursors (QSqlCursor)

    In Qt 3, one of the preferred methods of working with SQL
    is to use a cursor to manipulate the contents of a database.
    In Qt 4, the preferred method of working with SQL is to use
    the model/view architecture (QSqlQueryModel and QSqlTableModel)
    and, as a result, the cursor interface is only supplied in the
    Q3SqlCursor class.

    The easiest way to ensure continuity between Qt 3 and Qt 4
    is to use QSqlQuery rather than \c QSqlCursor,
    and migrate to QSqlQueryModel later.

    \section2 Domain Name Service (QDns)

    The QDns class in Qt 4 provides a much simpler interface
    than the QDns class in Qt 3, and is mainly used for host
    name resolution.
    As a result, many of the more complex features of Qt 3's
    QDns class are only available through Qt 4's Q3Dns
    compatibility class.

    To resolve host names with Qt 3, it is recommended that you
    use the higher level interface of QSocket rather than QDns.
    The equivalent functionality is available in Qt 4 in the
    QAbstractSocket and QHostInfo classes.

    \section2 Wizard Dialogs (QWizard)

    Qt 3 provides support for "wizard" dialogs in the form of
    the \c QWizard class. Prior to Qt 4.3, this class was made
    available as Q3Wizard, and provides the same interface for
    creating relatively complex wizards.

    In Qt 4.3 and later, a revised QWizard class can be used to
    create this kind of dialog, but existing Qt 3 wizard
    implementations may need to be redesigned to work with the
    new QWizard API.

    \section2 Abstract Grid Views (QGridView)

    Before the introduction of the Qt 3 \c QTable class,
    \c QGridView was the recommended way to create tables of
    custom items.
    With the introduction of \c QTable, the \c QGridView class was
    effectively obsoleted, and the \c QTable class should now be
    used to display tabular information in your Qt 3 application.
    This approach allows you to use QTableWidget as a replacement
    when later porting your application to Qt 4.

    \section2 Specialized Scrolling Views

    In Qt 3, the \c QScrollView class provides a viewport that can
    be used to display part of a larger widget, and will
    optionally provide scroll bars for navigation purposes.
    In Qt 4, this functionality is superseded by classes such as
    QScrollArea, which provides a more intuitive interface for
    developers to use.
    \c QScrollView is available in Qt 4 as the Q3ScrollView class.

    In Qt 3, it is recommended that \c QScrollView should be
    used with child widgets rather than subclassed. However, it
    should be noted that this approach may not be appropriate if
    you need to use extremely large scrolling areas in your
    application, since Qt 3 widgets cannot be wider or taller
    than 32767 pixels.

    \section1 Significantly Changed Features

    Some Qt 3 features have changed significantly for Qt 4. 
    and the recommended way of using them has therefore changed
    significantly, too. This is most notably true for the drag 
    and drop API. 

    Additionally, some of the more specialized features in Qt 3 are
    often used to help customize widgets and add extra polish to an
    application.
    Although these improvements make applications more presentable to
    users, many of them are unnecessary with Qt 4, and may create
    additional porting work.

    \section2 Drag and Drop

    Qt 4 introduces a simpler and more intuitive implementation
    of drag and drop between widgets, and with other applications.
    As a result, there is no simple approach that can be used to
    make drag and drop in a Qt 3 application easier to port to
    Qt 4.

    \section2 Extensive Customization of Item Views

    Each of the classes that are used to display list, tree,
    and table items in Qt 3 can be subclassed for the purposes
    of customizing their appearance. The item view framework
    in Qt 4 is implemented according to a different paradigm
    (model/view) which does not allow items to be customized
    using this method.

    Although Qt 4 provides compatibility classes (Q3ListBoxItem,
    Q3ListViewItem, and Q3TableItem) that can be used in the same
    way as their Qt 3 counterparts, these cannot be used within
    the standard model/view framework. It is recommended that,
    to minimize porting effort, extensive customization of item
    classes should be avoided in Qt 3, if at all possible.

    \section2 Double Buffering

    Qt 3 applications often use double buffering for reducing
    flicker when painting custom widgets. This approach is
    unnecessary with Qt 4 because double buffering is
    automatically performed by the paint engine.

    It still makes sense to use double buffering in
    Qt 4 in certain contexts. For example, in
    Chapter 5 of \l{GUI Programming with Qt 3}, double buffering
    was presented as a speed optimization and not just as a means
    of reducing flicker.

    \section2 Data-Aware Forms

    The \c QDataTable, \c QDataBrowser, and \c QDataView classes
    in Qt 3 allow integration between widgets and SQL-based
    databases.

    In Qt 4.1 and earlier, the preferred way to create a data-aware
    widget is to connect an generic item view (such as a table view)
    to a SQL model. In Qt 4.2 and later, the QDataWidgetMapper class
    can be used to map data to widgets in a form-based user interface.

    New applications written with Qt 3 should use QSqlQuery in
    preference to an approach based on the old-style data-aware
    widgets.
    This offers a choice of porting strategies when later migrating
    the application to Qt 4: You can either continue to use
    QSqlQuery or take the opportunity to use the model/view
    classes to handle database integration.

    \section2 Dock Windows and Areas

    In Qt 4, the way that dock windows are constructed and used
    in main window applications differs significantly to the
    pattern of use provided by Qt 3. As a result, the introduction
    of a simpler and cleaner API means that Qt 3 applications that
    make extensive use of dock window areas will require careful
    examination when they are ported to Qt 4.

    We recommend that the QMainWindow class be used in preference
    to the Q3MainWindow compatibility class when an existing Qt 3
    main window application is ported to Qt 4. Therefore, we
    recommend that specialized use of dock window areas should
    be avoided when writing a Qt 3 application with Qt 4 in mind.

    \section2 Custom Styles

    The style system used to provide consistent themes for Qt's
    standard widgets has been revised for Qt 4. As a result,
    custom styles for Qt 3 require some porting work to be done
    before they can be used with Qt 4. To ease the porting process,
    we recommend that you avoid implementing custom widget styles
    for Qt 3 applications unless it is absolutely necessary for
    your users.

    In Qt 4.2 and later, \l{Qt Style Sheets} can be used to
    implement many common modifications to existing styles, and
    this may be sufficient for Qt 3 applications.

    \section2 Events
    In Qt 3, QCloseEvents were not accepted by default. In Qt 4,
    the event handler QWidget::closeEvent() receives QCloseEvents,
    and accepts them by default closing the application. To avoid 
    this, please reimplement QWidget::closeEvent().  
*/