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

**

** Copyright (C) 2009 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$

**

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

/*!

    \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 QNetworkAccessManager 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().  

*/