src/quick/doc/src/appdevguide/porting.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qtquick-porting-qt5.html
  30 \title Porting QML Applications to Qt 5
  31 \brief Guide to porting from Qt 4.8 to Qt 5 for QML applications
  32
  33 When porting QML-related code from Qt 4.8 to Qt 5, application developers should be aware that
  34 the QML infrastructure has undergone considerable changes in Qt 5. Below is a guide to updating
  35 existing code to work with Qt 5.
  36
  37 (This article just describes the changes that affect existing code. Developers may also be
  38 interested in the summary of all new features in Qt 5 for QML application development, as described
  39 in the \l{qtqml-releasenotes.html}{QtQml Release Notes} and \l{qtquick-releasenotes.html}{QtQuick
  40 Release Notes}.)
  41
  42
  43 \section1 Porting QML code
  44
  45 The QtQuick module has been updated to version 2.0. All QML applications should update their import
  46 statements to use the new version:
  47
  48 \qml
  49 import QtQuick 2.0
  50 \endqml
  51
  52
  53 \section2 Property and Method Changes
  54
  55 \list
  56 \li ListView's \c highlightMoveSpeed and \c highlightResizeSpeed properties have been renamed to
  57 \l{ListView::}{highlightMoveVelocity} and \l{ListView::}{highlightResizeVelocity}, respectively.
  58 \li TextInput and TextEdit's \c openSoftwareInputPanel() and \c closeSoftwareInputPanel() methods
  59 have been removed. Use the new Qt.inputMethod property and call Qt.inputMethod.show()
  60 Qt.inputMethod.hide() to show and hide the virtual keyboard.
  61 \endlist
  62
  63 \section2 Type and API Changes
  64
  65 \list
  66 \li XmlListModel has moved into its own module, QtQuick.XmlListModel. Any code that uses the
  67 XmlListModel and XmlRole types must import \e {QtQuick.XmlListModel} instead.
  68 \li The local storage API that enables SQL support has been moved from the \l {QML Global Object}
  69 into a \c QtQuick.LocalStorage module API. Any code that requires the local storage API must import
  70 \e {QtQuick.LocalStorage} with a namespaced import instead. See the \l LocalStorage documentation
  71 for examples.
  72 \li The \c LayoutItem type has been removed from the \c QtQuick module as it was specific to the
  73 Graphics View framework backend used in QtQuick 1.
  74 \endlist
  75
  76 \section2 Changes to experimental Qt.labs modules
  77
  78 \list
  79 \li The \c Qt.labs.particles module has been removed. It is replaced by the fully-fledged \l
  80 QtQuick.particles module which is an enormous improvement on its predecessor.
  81 \li The \c Qt.labs.shaders module has been removed as the \c ShaderEffectItem and \l
  82 ShaderEffectSource types from this module have been moved into the \l QtQuick module. Note the \c
  83 ShaderEffectItem type has been renamed to \l ShaderEffect.
  84 \endlist
  85
  86
  87 \section1 Porting C++ code
  88
  89 In Qt 5, all QML applications are rendered with an OpenGL scenegraph architecture rather than the
  90 Graphics View framework used in Qt 4. Due to the scale of this architectural change, the C++ API has
  91 been extensively restructured and the \c QtDeclarative module has been deprecated in favour of two
  92 new modules: \l QtQml, which implements the QML engine and language infrastructure, and \l QtQuick,
  93 which implements the visual canvas and scenegraph backend.
  94
  95 All classes that were previously in the \c QtDeclarative module have been moved into the \l QtQml
  96 and \l QtQuick modules, and their class names have been changed to reflect their new module
  97 locations. The class name changes are as follows:
  98
  99 \table
 100 \header
 101     \li QtQml
 102     \li QtQuick
 103 \row
 104     \li
 105         \list
 106         \li QDeclarativeComponent -> QQmlComponent
 107         \li QDeclarativeContext -> QQmlContext
 108         \li QDeclarativeEngine -> QQmlEngine
 109         \li QDeclarativeError -> QQmlError
 110         \li QDeclarativeExpression -> QQmlExpression
 111         \li QDeclarativeExtensionPlugin -> QQmlExtensionPlugin
 112         \li QDeclarativeInfo -> QQmlInfo
 113         \li QDeclarativeListReference -> QQmlListReference
 114         \li QDeclarativeNetworkAccessManagerFactory -> QQmlNetworkAccessManagerFactory
 115         \li QDeclarativeParserStatus -> QQmlParserStatus
 116         \li QDeclarativeProperty -> QQmlProperty
 117         \li QDeclarativePropertyMap -> QQmlPropertyMap
 118         \li QDeclarativePropertyValueSource -> QQmlPropertyValueSource
 119         \li QDeclarativeScriptString -> QQmlScriptString
 120         \endlist
 121     \li
 122         \list
 123         \li QDeclarativeItem -> QQuickItem
 124         \li QDeclarativeView -> QQuickView
 125         \li QDeclarativeImageProvider -> QQuickImageProvider
 126         \endlist
 127 \endtable
 128
 129 To use the new \c QtQml* and \c QtQuick* classes in Qt 5, link against the approprate module from
 130 your qmake \c .pro file. For example the following will link against both the QtQml and QtQuick
 131 modules:
 132
 133 \code
 134 QT += qml quick
 135 \endcode
 136
 137 Required header files can then be included:
 138
 139 \code
 140 #include <QtQml/QQmlEngine>
 141 #include <QtQuick/QQuickView>
 142 \endcode
 143
 144 (The \c QtDeclarative module is still available to developers as the \l QtQuick1 module, as
 145 discussed in \l{Using the QtDeclarative module in Qt 5}{below}. However, it should not be used for
 146 new applications.)
 147
 148
 149 \section3 Porting uses of QDeclarativeItem and QDeclarativeView
 150
 151 When porting to QQuickItem, note that QDeclarativeItem inherited from QGraphicsItem; in contrast,
 152 QQuickItem inherits directly from QObject, and any QGraphicsItem-specific functionality is longer
 153 available. In particular, QQuickItem does not have a \c paint() method for performing custom
 154 rendering through the QPainter API. Instead, in Qt 5, custom rendering should be performed through
 155 the new \c QSG* classes to take full advantage of the scene graph. See the \l {Qt Quick Scene Graph}
 156 documentation details on using these classes.
 157
 158 Alternatively, the QQuickPaintedItem provides a \c paint() method and can be used as
 159 a convenient way to port QDeclarativeItem-based classes that use the QPainter API. Note this method
 160 is less performant than using the \c QSG* classes.
 161
 162 When porting from QDeclarativeView to QQuickView, note that QDeclarativeItem inherited from
 163 QGraphicsView. In contrast, QQuickView inherits from QQuickWindow and uses the QWindow
 164 infrastructure introduced in Qt 5; any QGraphicsView-specific functionality is no longer available.
 165
 166
 167 \section3 Using qmlscene instead of qmlviewer
 168
 169 The \c qmlviewer tool provided for prototyping and testing QML applications in Qt 4.x has been
 170 replaced with the \c qmlscene tool which integrates with the new scenegraph features in Qt 5.
 171
 172
 173 \section2 Porting QML plugins
 174
 175 All QML plugins should extend QQmlExtensionPlugin in Qt 5.
 176
 177 Additionally, plugins should use the new Qt plugin infrastructure introduced in Qt 5. QML plugins no
 178 longer require the Q_EXPORT_PLUGIN2() macro. Instead, they should use the Q_PLUGIN_METADATA() macro
 179 within the plugin class declarations and provide a \c .json file for the plugin.
 180
 181 See the updated \l {qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} documentation for
 182 an overview of creating QML plugins in Qt 5.
 183
 184
 185 \section2 Using the QtDeclarative module in Qt 5
 186
 187 For the purposes of porting older applications, the \c QtDeclarative module is still available in Qt
 188 5 but has been renamed to \c QtQuick1. Applications that required QtQuick 1 specific API (e.g.
 189 QDeclarativeView or QDeclarativeItem and the Graphics View integration) can use this module. Note
 190 that new applications should use the new \l QtQml and \l QtQuick modules instead.
 191
 192 To use the \c QtQuick1 module, add “quick1” module to your qmake \c .pro file:
 193
 194 \code
 195 QT += quick1
 196 \endcode
 197
 198 Required header files can be included from the QtQuick 1 module:
 199
 200 \code
 201 #include <QtQuick1/QDeclarativeView>
 202 #include <QtQuick1/QDeclarativeItem>
 203 \endcode
 204
 205 */