From 5796f88d544a59c507356a8830d72957104d73db Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Wed, 27 Jun 2012 16:49:20 +1000 Subject: [PATCH] Add porting guide for QML apps Change-Id: Ie633b5c7457a6223b49dca35b07cf1d5ad723fc7 Reviewed-by: Martin Jones Reviewed-by: Martin Jones --- src/qml/doc/src/whatsnew.qdoc | 9 +- .../doc/src/appdevguide/applicationdevelopers.qdoc | 8 + src/quick/doc/src/appdevguide/porting.qdoc | 205 +++++++++++++++++++++ src/quick/doc/src/whatsnew.qdoc | 45 ++++- 4 files changed, 256 insertions(+), 11 deletions(-) create mode 100644 src/quick/doc/src/appdevguide/porting.qdoc diff --git a/src/qml/doc/src/whatsnew.qdoc b/src/qml/doc/src/whatsnew.qdoc index 8640094..55ee20a 100644 --- a/src/qml/doc/src/whatsnew.qdoc +++ b/src/qml/doc/src/whatsnew.qdoc @@ -36,7 +36,8 @@ The QtQml C++ module is new in Qt 5. It provides the QML engine and implements the QML language supporting infrastructure. (Prior to Qt 5, this functionality was provided by the QtDeclarative module, which -has now been replaced by the new QtQml and QtQuick C++ modules.) +has now been replaced by the new QtQml and QtQuick C++ modules. See the +\l {Porting QML Applications to Qt 5} for more information.) \section2 QML Engine @@ -49,7 +50,11 @@ has now been replaced by the new QtQml and QtQuick C++ modules.) \section2 Component and Object creation \list -\li Loading/compilation can now be performed in a separate thread. Enable this by loading a \l Loader object asynchronously through its \l{Loader::}{source} property, or by passing the \c Component.Asynchronous parameter to \c Qt.createComponent(). +\li QML objects can now be created asynchronously to improve application performance. + \list + \li New QQmlIncubator and QQmlIncubationController C++ classes can be used to create objects asynchronously. + \li From QML code, this behavior is enabled by loading a \l Loader object asynchronously through its \l{Loader::}{source} property, or by passing the \c Component.Asynchronous parameter to \c Qt.createComponent(). + \endlist \li The component returned by \c Qt.createComponent() is no longer parented to the engine. Be sure to hold a reference, or provide a parent. \endlist diff --git a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc index 2b172ef..848a425 100644 --- a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc +++ b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc @@ -95,6 +95,14 @@ access to all of that functionality with a single import statement. \li \l{qtquick-qtquicktest.html}{QtQuickTest: QML Unit Testing Framework} \endlist +\section1 Release Notes and Porting Guides +\list +\li \l{qtqml-releasenotes.html}{QtQml Module Release Notes} +\li \l{qtquick-releasenotes.html}{QtQuick Module Release Notes} +\li \l{qtquick-porting-qt5.html}{Porting QML Applications to Qt 5} +\endlist + + \section1 Further Information About The QML Language Please see the documentation for the \l{qtqml-main.html}{Qt QML Module} for diff --git a/src/quick/doc/src/appdevguide/porting.qdoc b/src/quick/doc/src/appdevguide/porting.qdoc new file mode 100644 index 0000000..44afd4d --- /dev/null +++ b/src/quick/doc/src/appdevguide/porting.qdoc @@ -0,0 +1,205 @@ +/**************************************************************************** +** +** 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 +#include +\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 +#include +\endcode + +*/ diff --git a/src/quick/doc/src/whatsnew.qdoc b/src/quick/doc/src/whatsnew.qdoc index 03d5433..f989a19 100644 --- a/src/quick/doc/src/whatsnew.qdoc +++ b/src/quick/doc/src/whatsnew.qdoc @@ -35,17 +35,44 @@ 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 @@ -190,7 +217,7 @@ The new QtQuick.Particles module provides particle system support for creating a \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. */ -- 2.7.4