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

**

** 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 qt4-intro.html

    \title What's New in Qt 4

    \startpage index.html Qt Reference Documentation

    \nextpage The Tulip Container Classes

    This document covers the most important differences between Qt 3

    and Qt 4. Although it is not intended to be a comprehensive

    porting guide, it tells you about the most important portability

    issues that you may encounter. It also explains how to turn on Qt

    3 compatibility support.

    \tableofcontents

    \section1 New Technologies in Qt 4

    Qt 4 introduces the following core technologies:

    \list

    \o \l{The Tulip Container Classes}{Tulip}, a new set of template container classes.

    \o \l{The Interview Framework}{Interview}, a model/view architecture for item views.

    \o \l{The Arthur Paint System}{Arthur}, the Qt 4 painting framework.

    \o \l{The Scribe Classes}{Scribe}, the Unicode text renderer with a public API

    for performing low-level text layout.

    \o \l{The Qt 4 Main Window Classes}{Mainwindow}, a modern action-based

    mainwindow, toolbar, menu, and docking architecture.

    \o The new \l{The New Qt Designer}{\QD} user interface design tool.

    \endlist

    \section1 Recent Additions to Qt 4

    The following features have been added to Qt since the first release of Qt 4:

    In Qt 4.5:

    \list

    \o The WebKit browser engine included with Qt has been

       upgraded to the latest upstream (trunk) version of WebKit,

       bringing the latest features and improvements to Qt applications.

    \o Qt for Mac OS X has been substantially rewritten to use

       Apple's Cocoa API, enabling Qt applications to be deployed on

       64-bit Macintosh hardware.

    \o The QtXmlPatterns module has been extended to cover XSLT, a

       transformation language for XML documents.

    \o Qt Script introduced its debugger, 

       providing error reporting for scripts, and to let users track down

       bugs in their own scripts.

    \o Qt 4.5 includes support for writing rich text documents as

       OpenDocument files via the newly-introduced QTextDocumentWriter

       class.

    \o Qt Linguist can load and edit multiple translation

       files simultaneously.

    \o Support for ARGB top-level widgets (i.e., translucent

       windows).

    \endlist

    In Qt 4.4:

    \list

    \o \l{QtWebkit Module}{Qt WebKit integration}, making it possible for developers

    to use a fully-featured Web browser to display documents and access online

    services.

    \o A multimedia API provided by the \l{Phonon Overview}{Phonon Multimedia Framework}.

    \o \l{QtXmlPatterns Module}{XQuery and XPath} support, providing facilities for

    XML processing beyond that supported by the QtXml module.

    \o Support for embedded widgets in \l{Graphics View} scenes.

    \o The \l{Thread Support in Qt}{QtConcurrent framework} for

    concurrent programming using Qt paradigms and threading features.

    \o An \l{QtHelp Module}{improved help system} that can be used in conjunction

    with Qt Assistant or as an independent help resource manager.

    \o Printing system improvements, including the QPrinterInfo, QPrintPreviewWidget

    and QPrintPreviewDialog classes.

    \o Support for \l{Windows CE - Introduction to using Qt}{Qt for Windows CE} as

    a mainstream Qt platform.

    \o Improvements in performance of Qt for Embedded Linux and extended support for

    display hardware.

    \endlist

    In Qt 4.3:

    \list

    \o Support for different \l{The Qt 4 Main Window Classes}{main window paradigms and styles},

       such as those found in Visual Studio or KDevelop.

    \o The \l{QtScript} module, providing support for application scripting with ECMAScript.

    \o Improved graphics features, including an experimental Direct3D paint engine

       and improved provision for hardware accelerated rendering with OpenGL, and

       support for OpenGL ES in Qt for Embedded Linux.

    \o \l{QSvgGenerator}{Scalable Vector Graphics (SVG) export}, allowing SVG drawings to

       be created using the standard QPainter API.

    \o Support for arbitrary matrix transformations and set operations on painter paths.

    \o Native look and feel on Windows Vista; improved look and feel on Mac OS X.

    \o An improved \l{QMdiArea}{Multiple Document Interface (MDI)} implementation.

    \o Continuous improvements to \QD, including support for

       \l{Qt Designer's Widget Editing Mode#The Property Editor}{dynamic properties}.

    \o Support for Secure Socket Layer (SSL) communications via the QSslSocket class.

    \o Support for XML Localization Interchange File Format (XLIFF) files in \QL.

    \o A new font subsystem for Qt for Embedded Linux.

    \endlist

    In Qt 4.2:

    \list

    \o The \l{Graphics View} framework for producing interactive graphics.

    \o \l{Desktop Integration}{Desktop integration} facilities for applications.

    \o \l{Qt Style Sheets} enable easy, yet powerful customization of

       user interfaces.

    \o Support for the \l{intro-to-dbus.html}{D-Bus} Inter-Process Communication (IPC) and Remote Procedure Calling (RPC) mechanism.

    \o An \l{Undo Framework}{Undo framework} based on the

       \l{Books about GUI Design#Design Patterns}{Command pattern}.

    \o Support for model-based \l{QCompleter}{text completion} in standard and

       custom widgets.

    \o New widgets and GUI features, such as QCalendarWidget and

       QGLFramebufferObject.

    \o Classes to provide higher level application infrastructure, such as

       QFileSystemWatcher and QDataWidgetMapper.

    \endlist

    In Qt 4.1:

    \list

    \o Integrated support for rendering

    \l{The Arthur Paint System#SVG Rendering Support}{Scalable Vector Graphics}

    (SVG) drawings and animations.

    \o Support for

       \l{QWidget#Transparency and Double Buffering}{child widget transparency}

       on all platforms.

    \o A Portable Document Format (PDF) backend for Qt's printing system.

    \o A \l{QTestLib Manual}{unit testing framework} for Qt applications and

       libraries.

    \o Modules for \l{QtDesigner}{extending \QD} and

       \l{QtUiTools}{dynamic user interface building}.

    \o New \l{Proxy Models}{proxy models} to enable view-specific sorting and

       filtering of data displayed using item views.

    \o Support for \l{Installing Qt on Mac OS X}{universal binaries} on Mac OS X.

    \o Additional features for developers using \l{QtOpenGL}{OpenGL}, such as

    support for pixel and sample buffers.

    \o A flexible \l{QSyntaxHighlighter}{syntax highlighting class} based on the

       \l{Scribe} rich text framework.

    \o Support for \l{QNetworkProxy}{network proxy} servers using the SOCKS5

       protocol.

    \o Support for OLE verbs and MIME data handling in \l{ActiveQt}.

    \endlist

    For more information about improvements in each Qt release, see

    the \l{http://qt.nokia.com/developer/changes/}

    {detailed lists of changes}.

    \section1 Significant Improvements

    The following modules have been significantly improved for Qt 4:

    \list

    \o A fully cross-platform \l{accessibility}

    module, with support for the emerging SP-API Unix standard in

    addition to Microsoft and Mac Accessibility.

    \o The \l{qt4-sql.html}{SQL module}, which is now based on the

    Interview model/view framework.

    \o The \l{qt4-network.html}{network module}, with better support

    for UDP and synchronous sockets.

    \o The \l{qt4-styles.html}{style API}, which is now decoupled from

    the widgets, meaning that you can draw any user interface element on

    any device (widget, pixmap, etc.).

    \o Enhanced \l{qt4-threads.html}{thread support}, with signal-slot

    connections across threads and per-thread event loops.

    \o A new \l{resource system} for embedding images

    and other resource files into the application executable.

    \endlist

    \section1 Build System

    Unlike previous Qt releases, Qt 4 is a collection of smaller

    libraries:

    \table

    \header \o Library          \o Description

    \row    \o \l{QtCore}       \o Core non-GUI functionality

    \row    \o \l{QtGui}        \o Core GUI functionality

    \row    \o \l{QtNetwork}    \o Network module

    \row    \o \l{QtOpenGL}     \o OpenGL module

    \row    \o \l{QtSql}        \o SQL module

    \row    \o \l{QtSvg}        \o SVG rendering classes

    \row    \o \l{QtXml}        \o XML module

    \row    \o \l{Qt3Support}   \o Qt 3 support classes

    \row    \o \l{QAxContainer} \o ActiveQt client extension

    \row    \o \l{QAxServer}    \o ActiveQt server extension

    \row    \o \l{QtAssistant}  \o Classes for launching Qt Assistant

    \row    \o \l{QtDesigner}   \o Classes for extending and embedding Qt Designer

    \row    \o \l{QtUiTools}       \o Classes for dynamic GUI generation

    \row    \o \l{QtTest}       \o Tool classes for unit testing

    \endtable

    QtCore contains tool classes like QString, QList, and QFile, as

    well as kernel classes like QObject and QTimer. The QApplication

    class has been refactored so that it can be used in non-GUI

    applications. It is split into QCoreApplication (in \l QtCore)

    and QApplication (in \l QtGui).

    This split makes it possible to develop server applications using Qt

    without linking in any unnecessary GUI-related code and without

    requiring GUI-related system libraries to be present on the target

    machine (e.g. Xlib on X11, Carbon on Mac OS X).

    If you use qmake to generate your makefiles, qmake will by default

    link your application against QtCore and QtGui. To remove the

    dependency upon QtGui, add the line

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 0

    to your .pro file. To enable the other libraries, add the line

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 1

    Another change to the build system is that moc now understands

    preprocessor directives. qmake automatically passes the defines set

    for your project (using "DEFINES +=") on to moc, which has its own

    built-in C++ preprocessor.

    To compile code that uses UI files, you will also need this line in

    the .pro file:

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 2

    \section1 Include Syntax

    The syntax for including Qt class definitions has become

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 3

    For example:

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 4

    This is guaranteed to work for any public Qt class. The old syntax,

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 5

    still works, but we encourage you to switch to the new syntax.

    If you attempt to include a header file from a library that isn't

    linked against the application, this will result in a

    compile-time warning (e.g., "QSqlQuery: No such file or

    directory"). You can remedy to this problem either by removing

    the offending include or by specifying the missing library in the

    QT entry of your \c .pro file (see \l{Build System} above).

    To include the definitions for all the classes in a library, simply

    specify the name of that library. For example:

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 6

    \section1 Namespaces

    Qt 2 introduced a class called Qt for global-like constants

    (e.g., \c{Qt::yellow}). The C++ namespace construct was not used

    because not all compilers understood it when it was released.

    With Qt 4, the Qt class has become the Qt namespace. If you want

    to access a constant that is part of the Qt namespace, prefix it

    with \c Qt:: (e.g., \c{Qt::yellow}), or add the directive

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 7

    at the top of your source files, after your \c #include

    directives. If you use the \c{using namespace} syntax you don't

    need the prefix (e.g., \c yellow is sufficient).

    When porting Qt 3 applications, you may run into some source

    compatibility problems with some of these symbols. For example,

    in Qt 3, it was legal to write \c QWidget::yellow instead of \c

    Qt::yellow, because QWidget inherited from Qt. This won't work in

    Qt 4; you must write \c Qt::yellow or add the "using namespace"

    directive and drop the \c Qt:: prefix.

    The \l{qt3to4 - The Qt 3 to 4 Porting Tool}{qt3to4} porting tool

    automates this conversion.

    \section1 QObject/QWidget Constructors

    In Qt 4 we have tried to simplify the constructors of QObject/QWidget

    subclasses. This makes subclassing easier, at the same time as it

    helps make the Qt library more efficient.

    Constructors no longer take a "const char *name" parameter. If

    you want to specify a name for a QObject, you must call

    QObject::setObjectName() after construction. The object name is

    now a QString. The reasons for this change are:

    \list

    \o  Code that used it looked confusing, for example:

        \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 8

        \c label1 is a QLabel that displays the text "Hello"; \c

        label2 is a QLabel with no text, with the object name

        "Hello".

    \o  From surveys we did, most users didn't use the name, although

        they blindly followed Qt's convention and provided a "const

        char *name" in their subclasses's constructors. For example:

        \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 9

    \o  The name parameter was in Qt since version 1, and it always

        was documented as: "It is not very useful in the current

        version of Qt, but it will become increasingly important in

        the future." Ten years later, it still hasn't fulfilled its

        promise.

    \endlist

    QWidget's \c WFlags data type has been split in two:

    Qt::WindowFlags specifies low-level window flags (the type of

    window and the frame style), whereas Qt::WidgetAttribute

    specifies various higher-level attributes about the widget (e.g.,

    WA_StaticContents). Widget attributes can be set at any time

    using QWidget::setAttribute(); low-level window flags can be

    passed to the QWidget constructor or set later using

    QWidget::setParent(). As a consequence, the constructors of most

    QWidget subclasses don't need to provide a \c WFlags parameter.

    The \e parent parameter of all QObject classes in Qt defaults to

    a 0 pointer, as it used to do in Qt 1. This enables a style of

    programming where widgets are created without parents and then

    inserted in a layout, at which point the layout automatically

    reparents them.

    \section1 Dynamic Casts

    Qt 4 provides a qobject_cast<>() function that performs a dynamic cast

    based on the meta-information generated by moc for QObject

    subclasses. Unlike the standard C++ dynamic_cast<>() construct,

    qobject_cast<>() works even when RTTI is disabled, and it works correctly

    across DLL boundaries.

    Here's the Qt 3 idiom to cast a type to a subtype:

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 10

    The Qt 4 idiom is both cleaner and safer, because typos will always

    result in compiler errors:

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 11

    \section1 QPointer<T>

    The QPointer<T> class provides a pointer to type T (where T inherits

    from QObject) that is automatically set to 0 when the referenced

    object is destroyed. Guarded pointers are useful whenever you want to

    store a pointer to an object you do not own.

    Example:

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 12

    QPointer<T> is more or less the same as the old QGuardedPtr<T> class,

    except that it is now implemented in a much more lightweight manner

    than before. The cost of one QPointer<T> object is now approximately

    the same as that of a signal--slot connection.

    \section1 Paint Events

    Qt 4 supports double buffering transparently on all platforms. This

    feature can be turned off on a per-widget basis by calling

    QWidget::setAttribute(Qt::WA_PaintOnScreen).

    A consequence of this is that all painting must now be done from the

    paintEvent() function. This is also required by the HIView API on Mac

    OS X. In practice, this is seldom a problem, since you can call

    update() from anywhere in your code to create a paint event, with the

    region to update as the argument.

    To help porting, QWidget supports a Qt::WA_PaintOutsidePaintEvent

    attribute that can be set to make it possible to paint outside

    \l{QWidget::paintEvent()}{paintEvent()} on Windows and X11.

    \section1 Qt 3 Support Layer

    Qt 4 provides an extension library that applications based on Qt 3,

    called Qt3Support, that Qt applications can link against. This allows

    for more compatibility than ever before, without bloating Qt.

    \list

    \o  Classes that have been replaced by a different class with the

        same name, such as QListView, and classes that no longer exist in Qt 4

        are available with a \c 3 in their name (e.g., Q3ListView, Q3Accel).

    \o  Other classes provide compatibility functions. Most of these are

        implemented inline, so that they don't bloat the Qt libraries.

    \endlist

    To enable the Qt 3 support classes and functions, add the line

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 13

    to your \c .pro file.

    On Visual C++ 7 and GCC 3.2+, using compatibility functions often results

    in a compiler warning (e.g., "'find' is deprecated"). If you want to turn

    off that warning, add the line

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 14

    to your \c .pro file.

    If you want to use compatibility functions but don't want to link

    against the Qt3Support library, add the line

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 15

    or

    \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 16

    to your \c .pro file, depending on whether you want compatibility

    function calls to generate compiler warnings or not.

*/

/*!

    \page qt4-6-intro.html

    \title What's New in Qt 4.6

    Qt 4.6 provides many improvements and enhancements over the

    previous releases in the Qt 4 series. This document covers the

    most important features in this release, separated by category.

\omit

    A comprehensive list of changes between Qt 4.5 and Qt 4.6 is

    included in the \c changes-4.6.0 file

    \l{http://qt.nokia.com/developer/changes/changes-4.6.0}{available

    online}. A \l{Known Issues in %VERSION%}{list of known issues}

    for this release is also available.

    Changes between this release and the previous release are provided

    in the \c{changes-%VERSION%} file (also

    \l{http://qt.nokia.com/developer/changes/changes-%VERSION%}{available online}).

\endomit

    A list of other Qt 4 features can be found on the \bold{\l{What's

    New in Qt 4}} page.

    \bold{Highlights}

    \tableofcontents

    \section1 Support for Symbian

    Qt 4.6 is the first release to include support for the Symbian

    platform, with integration into the S60 framework. The port to

    Symbian and S60 provides all functionality required to develop

    rich end-user applications for devices running S60 3.1 and

    later.

    \section1 Animation Framework

    The animation framework helps build highly animated,

    high-performance GUIs without the hassle of managing complex

    structures, timers, and easing curves, not to mention the large

    state graphs that all animated GUIs tend to be full of.

    The framework makes it easy to animate \l{QObject}s, including

    QWidgets, by allowing Qt properties to be animated. It also allows

    creating custom animations and interpolation functions. Graphics

    views are not left out; one can animate \l{QGraphicsWidget}s and

    new \l{QGraphicsObject}s which inherit from QGraphicsItem

    (and thereby enable properties).

    Animations are controlled using easing curves and can be grouped

    together. This enables animations of arbitrary complexity.

    The API is easy to grasp with functions such as start(), stop(),

    pause(), and currentTime(). Here is an image from one of the

    examples that come with the framework:

    \image whatsnewanimatedtiles.png

    The animation framework also plugs into the new Qt Statemachine by

    allowing an animation to be played when transitions are triggered.

    The state machine framework is introduced in 4.6 and is described

    below.

    See \l{The Animation Framework} documentation for more information.

    \section1 State Machine Framework

    The state machine framework provides a robust state chart

    implementation based on Harel statecharts and SCXML. Qt's API lets

    you construct such state graphs and execute them. The key benefits

    of a state machine are: