1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the documentation of the Qt Toolkit.
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.
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.
26 ****************************************************************************/
29 \page qtquick-porting-qt5.html
30 \title QML Applications in Qt 5
31 \brief Lists the Qt 5.0 changes that affect the existing QML applications
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. The sections below describe
35 these changes and the impact they have on your existing code.
37 This article describes the changes that affect your existing code. If you are
38 interested in the summary of all new features in Qt 5 for QML application development, see
39 \l{qtqml-releasenotes.html}{QtQml Release Notes} and \l{qtquick-releasenotes.html}{QtQuick Release Notes}.
41 \section1 QtQuick Module
43 The QtQuick module has been updated to version 2.0. All QML applications should update their import
44 statements to use the new version:
51 \section2 Property and Method Changes
54 \li ListView's \c highlightMoveSpeed and \c highlightResizeSpeed properties have been renamed to
55 \l{ListView::}{highlightMoveVelocity} and \l{ListView::}{highlightResizeVelocity}, respectively.
56 \li TextInput and TextEdit's \c openSoftwareInputPanel() and \c closeSoftwareInputPanel() methods
57 have been removed. Use the new Qt.inputMethod property and call Qt.inputMethod.show()
58 Qt.inputMethod.hide() to show and hide the virtual keyboard.
61 \section2 Type and API Changes
64 \li XmlListModel has moved into its own module, QtQuick.XmlListModel. Any code that uses the
65 XmlListModel and XmlRole types must import \e {QtQuick.XmlListModel} instead.
66 \li The local storage API that enables SQL support has been moved from the \l {QML Global Object}
67 into a \c QtQuick.LocalStorage singleton type. Any code that requires the local storage API must import
68 \e {QtQuick.LocalStorage} instead. See the \l {QtQuick.LocalStorage 2}{QtQuick.LocalStorage} documentation
70 \li The \c LayoutItem type has been removed from the \c QtQuick module as it was specific to the
71 Graphics View framework backend used in QtQuick 1.
74 \section2 Behavioral Changes
76 QtQuick 2.0 includes a number of behavioral changes and you should thoroughly test your applications after
77 porting. These changes will not necessarily lead to run-time errors, but may break certain assumptions in your code.
78 Below are the prominent changes to be aware of when porting your applications.
80 Item opacity and visibility:
83 \li The input handling details of \l{Item::}{opacity} and \l{Item::}{visible} have changed. An opacity of zero no
84 longer affects input handling, where previously it stopped mouse input. A visibility of false no longer affects
85 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
86 the item is rendered. A workaround for applying the old behavior in most cases is to bind enabled to
87 \tt {(visible && opacity > 0.0)}.
88 \li Previously, if an item was in a positioner (i.e. a \l Row, \l Column, \l Grid and \l Flow)
89 and the item's \c opacity changed to 0, or its \c visible value became \c false, the positioner
90 would remove the item from its layout and collapse the space for that item. In QtQuick 2.0, this
91 now only happens when an item's \c visible is \c false; the item opacity no longer affects whether
92 the item is laid out. (This is consistent with the existing behavior of ListView and GridView).
98 \li The TextEdit::textFormat property now defaults to \c PlainText instead of \c AutoText.
99 \li When Text::textFormat is set to \c Text.AutoText format, the text object will automatically
100 switch to \c Text.StyledText instead of \c Text.RichText.
106 \li Modifying the Image::sourceSize now fits the image to the size, maintaining aspect
108 \li For ListView and GridView, the \c cacheBuffer property now has a non-zero default and
109 delegates in the cache buffer are created asynchronously. Also, using a \c RightToLeft layout
110 now also reverses the \c preferredHighlightBegin and \c preferredHighlightEnd.
111 \li For \l Loader, the \c sourceChanged and \c sourceComponentChanged signals are now only emitted
112 when their respective properties change value. (Previously \l Loader emitted both of these signals
113 when either of the relevant properties had changed.)
117 \section2 Changes to experimental Qt.labs modules
120 \li The \c Qt.labs.particles module has been removed. It is replaced by the fully-fledged \l
121 QtQuick.particles module which is an enormous improvement on its predecessor.
122 \li The \c Qt.labs.shaders module has been removed as the \c ShaderEffectItem and \l
123 ShaderEffectSource types from this module have been moved into the \l QtQuick module. Note the \c
124 ShaderEffectItem type has been renamed to \l ShaderEffect.
130 In Qt 5, all QML applications are rendered with an OpenGL scenegraph architecture rather than the
131 Graphics View framework used in Qt 4. Due to the scale of this architectural change, the C++ API has
132 been extensively restructured and the \c QtDeclarative module has been deprecated in favour of two
133 new modules: \l QtQml, which implements the QML engine and language infrastructure, and \l QtQuick,
134 which implements the visual canvas and scenegraph backend.
136 All classes that were previously in the \c QtDeclarative module have been moved into the \l QtQml
137 and \l QtQuick modules, and their class names have been changed to reflect their new module
138 locations. The class name changes are as follows:
147 \li QDeclarativeComponent -> QQmlComponent
148 \li QDeclarativeContext -> QQmlContext
149 \li QDeclarativeEngine -> QQmlEngine
150 \li QDeclarativeError -> QQmlError
151 \li QDeclarativeExpression -> QQmlExpression
152 \li QDeclarativeExtensionPlugin -> QQmlExtensionPlugin
153 \li QDeclarativeInfo -> QQmlInfo
154 \li QDeclarativeListReference -> QQmlListReference
155 \li QDeclarativeNetworkAccessManagerFactory -> QQmlNetworkAccessManagerFactory
156 \li QDeclarativeParserStatus -> QQmlParserStatus
157 \li QDeclarativeProperty -> QQmlProperty
158 \li QDeclarativePropertyMap -> QQmlPropertyMap
159 \li QDeclarativePropertyValueSource -> QQmlPropertyValueSource
160 \li QDeclarativeScriptString -> QQmlScriptString
164 \li QDeclarativeItem -> QQuickItem
165 \li QDeclarativeView -> QQuickView
166 \li QDeclarativeImageProvider -> QQuickImageProvider
170 To use the new \c QtQml* and \c QtQuick* classes in Qt 5, link against the approprate module from
171 your qmake \c .pro file. For example the following will link against both the QtQml and QtQuick
178 Required header files can then be included:
181 #include <QtQml/QQmlEngine>
182 #include <QtQuick/QQuickView>
185 (The \c QtDeclarative module is still available to developers as the \l QtQuick1 module, as
186 discussed in \l{Using the QtDeclarative module in Qt 5}{below}. However, it should not be used for
190 \section3 QDeclarativeItem and QDeclarativeView
192 When porting to QQuickItem, note that QDeclarativeItem inherited from QGraphicsItem; in contrast,
193 QQuickItem inherits directly from QObject, and any QGraphicsItem-specific functionality is no longer
194 available. In particular, QQuickItem does not have a \c paint() method for performing custom
195 rendering through the QPainter API. Instead, in Qt 5, custom rendering should be performed through
196 the new \c QSG* classes to take full advantage of the scene graph. See the \l {Qt Quick Scene Graph}
197 documentation details on using these classes.
199 Alternatively, the QQuickPaintedItem provides a \c paint() method and can be used as
200 a convenient way to port QDeclarativeItem-based classes that use the QPainter API. Note this method
201 is less performant than using the \c QSG* classes.
203 When porting from QDeclarativeView to QQuickView, note that QDeclarativeItem inherited from
204 QGraphicsView. In contrast, QQuickView inherits from QQuickWindow and uses the QWindow
205 infrastructure introduced in Qt 5; any QGraphicsView-specific functionality is no longer available.
208 \section3 qmlscene Utility
210 The \c qmlviewer tool provided for prototyping and testing QML applications in Qt 4.x has been
211 replaced with the \c qmlscene tool which integrates with the new scenegraph features in Qt 5.
214 \section2 QML plugins
216 All QML plugins should extend QQmlExtensionPlugin in Qt 5.
218 Additionally, plugins should use the new Qt plugin infrastructure introduced in Qt 5. QML plugins no
219 longer require the Q_EXPORT_PLUGIN2() macro. Instead, they should use the Q_PLUGIN_METADATA() macro
220 within the plugin class declaration.
222 See the updated \l {qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} documentation for
223 an overview of creating QML plugins in Qt 5.
226 \section2 QtDeclarative module in Qt 5
228 For the purposes of porting older applications, the \c QtDeclarative module is still available in Qt
229 5 but has been renamed to \c QtQuick1. Applications that required QtQuick 1 specific API (e.g.
230 QDeclarativeView or QDeclarativeItem and the Graphics View integration) can use this module. Note
231 that new applications should use the new \l QtQml and \l QtQuick modules instead.
233 To use the \c QtQuick1 module, add “quick1” module to your qmake \c .pro file:
239 Required header files can be included from the QtQuick 1 module:
242 #include <QtQuick1/QDeclarativeView>
243 #include <QtQuick1/QDeclarativeItem>