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

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  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 singleton type. Any code that requires the local storage API must import
  70 \e {QtQuick.LocalStorage} instead. See the \l {QtQuick.LocalStorage 2}{QtQuick.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 Behavioral Changes
  77
  78 QtQuick 2.0 includes a number of behavioral changes and you should thoroughly test your applications after
  79 porting. These changes will not necessarily lead to run-time errors, but may break certain assumptions in your code.
  80 Below are the prominent changes to be aware of when porting your applications.
  81
  82 Item opacity and visibility:
  83
  84 \list
  85 \li The input handling details of \l{Item::}{opacity} and \l{Item::}{visible} have changed. An opacity of zero no
  86     longer affects input handling, where previously it stopped mouse input. A visibility of false no longer affects
  87     keyboard input, but still stops mouse input. The new \l{Item::}{enabled} property stops mouse and keyboard input, but does not affect how or whether
  88     the item is rendered. A workaround for applying the old behavior in most cases is to bind enabled to
  89     \tt {(visible && opacity > 0.0)}.
  90 \li Previously, if an item was in a positioner (i.e. a \l Row, \l Column, \l Grid and \l Flow)
  91     and the item's \c opacity changed to 0, or its \c visible value became \c false, the positioner
  92     would remove the item from its layout and collapse the space for that item. In QtQuick 2.0, this
  93     now only happens when an item's \c visible is \c false; the item opacity no longer affects whether
  94     the item is laid out. (This is consistent with the existing behavior of ListView and GridView).
  95 \endlist
  96
  97 Text:
  98
  99 \list
 100 \li The TextEdit::textFormat property now defaults to \c PlainText instead of \c AutoText.
 101 \li When Text::textFormat is set to \c Text.AutoText format, the text object will automatically
 102     switch to \c Text.StyledText instead of \c Text.RichText.
 103 \endlist
 104
 105 Other:
 106
 107 \list
 108 \li Modifying the Image::sourceSize now fits the image to the size, maintaining aspect
 109     ratio.
 110 \li For ListView and GridView, the \c cacheBuffer property now has a non-zero default and
 111     delegates in the cache buffer are created asynchronously. Also, using a \c RightToLeft layout
 112     now also reverses the \c preferredHighlightBegin and \c preferredHighlightEnd.
 113 \li For \l Loader, the \c sourceChanged and \c sourceComponentChanged signals are now only emitted
 114     when their respective properties change value. (Previously \l Loader emitted both of these signals
 115     when either of the relevant properties had changed.)
 116 \endlist
 117
 118
 119 \section2 Changes to experimental Qt.labs modules
 120
 121 \list
 122 \li The \c Qt.labs.particles module has been removed. It is replaced by the fully-fledged \l
 123 QtQuick.particles module which is an enormous improvement on its predecessor.
 124 \li The \c Qt.labs.shaders module has been removed as the \c ShaderEffectItem and \l
 125 ShaderEffectSource types from this module have been moved into the \l QtQuick module. Note the \c
 126 ShaderEffectItem type has been renamed to \l ShaderEffect.
 127 \endlist
 128
 129
 130 \section1 Porting C++ code
 131
 132 In Qt 5, all QML applications are rendered with an OpenGL scenegraph architecture rather than the
 133 Graphics View framework used in Qt 4. Due to the scale of this architectural change, the C++ API has
 134 been extensively restructured and the \c QtDeclarative module has been deprecated in favour of two
 135 new modules: \l QtQml, which implements the QML engine and language infrastructure, and \l QtQuick,
 136 which implements the visual canvas and scenegraph backend.
 137
 138 All classes that were previously in the \c QtDeclarative module have been moved into the \l QtQml
 139 and \l QtQuick modules, and their class names have been changed to reflect their new module
 140 locations. The class name changes are as follows:
 141
 142 \table
 143 \header
 144     \li QtQml
 145     \li QtQuick
 146 \row
 147     \li
 148         \list
 149         \li QDeclarativeComponent -> QQmlComponent
 150         \li QDeclarativeContext -> QQmlContext
 151         \li QDeclarativeEngine -> QQmlEngine
 152         \li QDeclarativeError -> QQmlError
 153         \li QDeclarativeExpression -> QQmlExpression
 154         \li QDeclarativeExtensionPlugin -> QQmlExtensionPlugin
 155         \li QDeclarativeInfo -> QQmlInfo
 156         \li QDeclarativeListReference -> QQmlListReference
 157         \li QDeclarativeNetworkAccessManagerFactory -> QQmlNetworkAccessManagerFactory
 158         \li QDeclarativeParserStatus -> QQmlParserStatus
 159         \li QDeclarativeProperty -> QQmlProperty
 160         \li QDeclarativePropertyMap -> QQmlPropertyMap
 161         \li QDeclarativePropertyValueSource -> QQmlPropertyValueSource
 162         \li QDeclarativeScriptString -> QQmlScriptString
 163         \endlist
 164     \li
 165         \list
 166         \li QDeclarativeItem -> QQuickItem
 167         \li QDeclarativeView -> QQuickView
 168         \li QDeclarativeImageProvider -> QQuickImageProvider
 169         \endlist
 170 \endtable
 171
 172 To use the new \c QtQml* and \c QtQuick* classes in Qt 5, link against the approprate module from
 173 your qmake \c .pro file. For example the following will link against both the QtQml and QtQuick
 174 modules:
 175
 176 \code
 177 QT += qml quick
 178 \endcode
 179
 180 Required header files can then be included:
 181
 182 \code
 183 #include <QtQml/QQmlEngine>
 184 #include <QtQuick/QQuickView>
 185 \endcode
 186
 187 (The \c QtDeclarative module is still available to developers as the \l QtQuick1 module, as
 188 discussed in \l{Using the QtDeclarative module in Qt 5}{below}. However, it should not be used for
 189 new applications.)
 190
 191
 192 \section3 Porting uses of QDeclarativeItem and QDeclarativeView
 193
 194 When porting to QQuickItem, note that QDeclarativeItem inherited from QGraphicsItem; in contrast,
 195 QQuickItem inherits directly from QObject, and any QGraphicsItem-specific functionality is longer
 196 available. In particular, QQuickItem does not have a \c paint() method for performing custom
 197 rendering through the QPainter API. Instead, in Qt 5, custom rendering should be performed through
 198 the new \c QSG* classes to take full advantage of the scene graph. See the \l {Qt Quick Scene Graph}
 199 documentation details on using these classes.
 200
 201 Alternatively, the QQuickPaintedItem provides a \c paint() method and can be used as
 202 a convenient way to port QDeclarativeItem-based classes that use the QPainter API. Note this method
 203 is less performant than using the \c QSG* classes.
 204
 205 When porting from QDeclarativeView to QQuickView, note that QDeclarativeItem inherited from
 206 QGraphicsView. In contrast, QQuickView inherits from QQuickWindow and uses the QWindow
 207 infrastructure introduced in Qt 5; any QGraphicsView-specific functionality is no longer available.
 208
 209
 210 \section3 Using qmlscene instead of qmlviewer
 211
 212 The \c qmlviewer tool provided for prototyping and testing QML applications in Qt 4.x has been
 213 replaced with the \c qmlscene tool which integrates with the new scenegraph features in Qt 5.
 214
 215
 216 \section2 Porting QML plugins
 217
 218 All QML plugins should extend QQmlExtensionPlugin in Qt 5.
 219
 220 Additionally, plugins should use the new Qt plugin infrastructure introduced in Qt 5. QML plugins no
 221 longer require the Q_EXPORT_PLUGIN2() macro. Instead, they should use the Q_PLUGIN_METADATA() macro
 222 within the plugin class declaration.
 223
 224 See the updated \l {qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} documentation for
 225 an overview of creating QML plugins in Qt 5.
 226
 227
 228 \section2 Using the QtDeclarative module in Qt 5
 229
 230 For the purposes of porting older applications, the \c QtDeclarative module is still available in Qt
 231 5 but has been renamed to \c QtQuick1. Applications that required QtQuick 1 specific API (e.g.
 232 QDeclarativeView or QDeclarativeItem and the Graphics View integration) can use this module. Note
 233 that new applications should use the new \l QtQml and \l QtQuick modules instead.
 234
 235 To use the \c QtQuick1 module, add “quick1” module to your qmake \c .pro file:
 236
 237 \code
 238 QT += quick1
 239 \endcode
 240
 241 Required header files can be included from the QtQuick 1 module:
 242
 243 \code
 244 #include <QtQuick1/QDeclarativeView>
 245 #include <QtQuick1/QDeclarativeItem>
 246 \endcode
 247
 248 */