--- /dev/null
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtquick-porting-qt5.html
+\title Porting QML Applications to Qt 5
+\brief Guide to porting from Qt 4.8 to Qt 5 for QML applications
+
+When porting QML-related code from Qt 4.8 to Qt 5, application developers should be aware that
+the QML infrastructure has undergone considerable changes in Qt 5. Below is a guide to updating
+existing code to work with Qt 5.
+
+(This article just describes the changes that affect existing code. Developers may also be
+interested in the summary of all new features in Qt 5 for QML application development, as described
+in the \l{qtqml-releasenotes.html}{QtQml Release Notes} and \l{qtquick-releasenotes.html}{QtQuick
+Release Notes}.)
+
+
+\section1 Porting QML code
+
+The QtQuick module has been updated to version 2.0. All QML applications should update their import
+statements to use the new version:
+
+\qml
+import QtQuick 2.0
+\endqml
+
+
+\section2 Property and Method Changes
+
+\list
+\li ListView's \c highlightMoveSpeed and \c highlightResizeSpeed properties have been renamed to
+\l{ListView::}{highlightMoveVelocity} and \l{ListView::}{highlightResizeVelocity}, respectively.
+\li TextInput and TextEdit's \c openSoftwareInputPanel() and \c closeSoftwareInputPanel() methods
+have been removed. Use the new Qt.inputMethod property and call Qt.inputMethod.show()
+Qt.inputMethod.hide() to show and hide the virtual keyboard.
+\endlist
+
+\section2 Type and API Changes
+
+\list
+\li XmlListModel has moved into its own module, QtQuick.XmlListModel. Any code that uses the
+XmlListModel and XmlRole types must import \e {QtQuick.XmlListModel} instead.
+\li The local storage API that enables SQL support has been moved from the \l {QML Global Object}
+into a \c QtQuick.LocalStorage module API. Any code that requires the local storage API must import
+\e {QtQuick.LocalStorage} with a namespaced import instead. See the \l LocalStorage documentation
+for examples.
+\li The \c LayoutItem type has been removed from the \c QtQuick module as it was specific to the
+Graphics View framework backend used in QtQuick 1.
+\endlist
+
+\section2 Changes to experimental Qt.labs modules
+
+\list
+\li The \c Qt.labs.particles module has been removed. It is replaced by the fully-fledged \l
+QtQuick.particles module which is an enormous improvement on its predecessor.
+\li The \c Qt.labs.shaders module has been removed as the \c ShaderEffectItem and \l
+ShaderEffectSource types from this module have been moved into the \l QtQuick module. Note the \c
+ShaderEffectItem type has been renamed to \l ShaderEffect.
+\endlist
+
+
+\section1 Porting C++ code
+
+In Qt 5, all QML applications are rendered with an OpenGL scenegraph architecture rather than the
+Graphics View framework used in Qt 4. Due to the scale of this architectural change, the C++ API has
+been extensively restructured and the \c QtDeclarative module has been deprecated in favour of two
+new modules: \l QtQml, which implements the QML engine and language infrastructure, and \l QtQuick,
+which implements the visual canvas and scenegraph backend.
+
+All classes that were previously in the \c QtDeclarative module have been moved into the \l QtQml
+and \l QtQuick modules, and their class names have been changed to reflect their new module
+locations. The class name changes are as follows:
+
+\table
+\header
+ \li QtQml
+ \li QtQuick
+\row
+ \li
+ \list
+ \li QDeclarativeComponent -> QQmlComponent
+ \li QDeclarativeContext -> QQmlContext
+ \li QDeclarativeEngine -> QQmlEngine
+ \li QDeclarativeError -> QQmlError
+ \li QDeclarativeExpression -> QQmlExpression
+ \li QDeclarativeExtensionPlugin -> QQmlExtensionPlugin
+ \li QDeclarativeInfo -> QQmlInfo
+ \li QDeclarativeListReference -> QQmlListReference
+ \li QDeclarativeNetworkAccessManagerFactory -> QQmlNetworkAccessManagerFactory
+ \li QDeclarativeParserStatus -> QQmlParserStatus
+ \li QDeclarativeProperty -> QQmlProperty
+ \li QDeclarativePropertyMap -> QQmlPropertyMap
+ \li QDeclarativePropertyValueSource -> QQmlPropertyValueSource
+ \li QDeclarativeScriptString -> QQmlScriptString
+ \endlist
+ \li
+ \list
+ \li QDeclarativeItem -> QQuickItem
+ \li QDeclarativeView -> QQuickView
+ \li QDeclarativeImageProvider -> QQuickImageProvider
+ \endlist
+\endtable
+
+To use the new \c QtQml* and \c QtQuick* classes in Qt 5, link against the approprate module from
+your qmake \c .pro file. For example the following will link against both the QtQml and QtQuick
+modules:
+
+\code
+QT += qml quick
+\endcode
+
+Required header files can then be included:
+
+\code
+#include <QtQml/QQmlEngine>
+#include <QtQuick/QQuickView>
+\endcode
+
+(The \c QtDeclarative module is still available to developers as the \l QtQuick1 module, as
+discussed in \l{Using the QtDeclarative module in Qt 5}{below}. However, it should not be used for
+new applications.)
+
+
+\section3 Porting uses of QDeclarativeItem and QDeclarativeView
+
+When porting to QQuickItem, note that QDeclarativeItem inherited from QGraphicsItem; in contrast,
+QQuickItem inherits directly from QObject, and any QGraphicsItem-specific functionality is longer
+available. In particular, QQuickItem does not have a \c paint() method for performing custom
+rendering through the QPainter API. Instead, in Qt 5, custom rendering should be performed through
+the new \c QSG* classes to take full advantage of the scene graph. See the \l {Qt Quick Scene Graph}
+documentation details on using these classes.
+
+Alternatively, the QQuickPaintedItem provides a \c paint() method and can be used as
+a convenient way to port QDeclarativeItem-based classes that use the QPainter API. Note this method
+is less performant than using the \c QSG* classes.
+
+When porting from QDeclarativeView to QQuickView, note that QDeclarativeItem inherited from
+QGraphicsView. In contrast, QQuickView inherits from QQuickCanvas and uses the QWindow
+infrastructure introduced in Qt 5; any QGraphicsView-specific functionality is no longer available.
+
+
+\section3 Using qmlscene instead of qmlviewer
+
+The \c qmlviewer tool provided for prototyping and testing QML applications in Qt 4.x has been
+replaced with the \c qmlscene tool which integrates with the new scenegraph features in Qt 5.
+
+
+\section2 Porting QML plugins
+
+All QML plugins should extend QQmlExtensionPlugin in Qt 5.
+
+Additionally, plugins should use the new Qt plugin infrastructure introduced in Qt 5. QML plugins no
+longer require the Q_EXPORT_PLUGIN2() macro. Instead, they should use the Q_PLUGIN_METADATA() macro
+within the plugin class declarations and provide a \c .json file for the plugin.
+
+See the updated \l {qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} documentation for
+an overview of creating QML plugins in Qt 5.
+
+
+\section2 Using the QtDeclarative module in Qt 5
+
+For the purposes of porting older applications, the \c QtDeclarative module is still available in Qt
+5 but has been renamed to \c QtQuick1. Applications that required QtQuick 1 specific API (e.g.
+QDeclarativeView or QDeclarativeItem and the Graphics View integration) can use this module. Note
+that new applications should use the new \l QtQml and \l QtQuick modules instead.
+
+To use the \c QtQuick1 module, add “quick1” module to your qmake \c .pro file:
+
+\code
+QT += quick1
+\endcode
+
+Required header files can be included from the QtQuick 1 module:
+
+\code
+#include <QtQuick1/QDeclarativeView>
+#include <QtQuick1/QDeclarativeItem>
+\endcode
+
+*/
The QtQuick C++ module is new in Qt 5. It provides the visual canvas and scenegraph backend
as well as the QtQuick QML module for QML application development.
-(Prior to Qt 5, the QtQuick QML module was provided by the QtDeclarative C++ module. In Qt 5
-the QtDeclarative module has been replaced by the new QtQml and QtQuick C++ modules.)
+As of Qt 5, the QtQuick module is based on an OpenGL scenegraph. Many of the classes in
+the QtQuick module have been ported from the \c QtDeclarative module from Qt 4.8 to use
+the scenegraph architecture; these classes have been renamed to use a \c QQuick* prefix.
+(See the \l {Porting QML Applications to Qt 5} for porting information.)
-As of Qt 5, the QtQuick module is based on an OpenGL scenegraph. The following C++ classes replace
-their \c QDeclarative* equivalents from QtQuick 1:
+The following classes provide the basic functionality for interacting with the QML visual
+canvas from C++:
\list
-\li QQuickView
-\li QQuickCanvas
-\li QQuickItem
-\li QQuickPaintedItem
+\li QQuickItem - the base visual QML type (replaces \c QDeclarativeItem)
+\li QQuickView - a window for rendering a QML scene from a QML file (replaces \c QDeclarativeView)
+\li QQuickCanvas - a base canvas for displaying a QML scene
+\li QQuickPaintedItem - convenience for using the QPainter API with the scenegraph
+\li QQuickImageProvider - fetches custom images for use in QML applications (replaces \c QDeclarativeImageProvider)
+\li QQuickTextureFactory - use with QQuickImageProvider::requestTexture()
+\endlist
+
+Custom rendering can be performed on the scenegraph using the following new classes:
+
+\list
+\li QSGNode
+\li QSGMaterial
+\li QSGBasicGeometryNode
+\li QSGGeometryNode
+\li QSGClipNode
+\li QSGTransformNode
+\li QSGRootNode
+\li QSGOpacityNode
+\li QSGNodeVisitor
+\li QSGFlatColorMaterial
+\li QSGSimpleRectNode
+\li QSGSimpleTextureNode
+\li QSGTexture
+\li QSGDynamicTexture
+\li QSGOpaqueTextureMaterial
+\li QSGTextureMaterial
+\li QSGTextureProvider
+\li QSGVertexColorMaterial
\endlist
\section2 QtQuick.XmlListModel
-XmlListModel has now moved into its own module, QtQuick.XmlListModel. This module must now be imported to use the XmlListModel and XmlListModelRole types.
+XmlListModel has now moved into its own module, QtQuick.XmlListModel. This module must now be imported to use the XmlListModel and XmlRole types.
*/