--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/porting/porting4-overview.qdoc Wed Mar 31 11:06:36 2010 +0300
@@ -0,0 +1,373 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+ \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().
+*/