1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtquick-porting-qt5.html
\title QML Applications in Qt 5
\brief Lists the Qt 5.0 changes that affect the existing 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. The sections below describe
these changes and the impact they have on your existing code.
This article describes the changes that affect your existing code. If you are
interested in the summary of all new features in Qt 5 for QML application development, see
\l{qtqml-releasenotes.html}{QtQml Release Notes} and \l{qtquick-releasenotes.html}{QtQuick Release Notes}.
\section1 QtQuick Module
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 singleton type. Any code that requires the local storage API must import
\e {QtQuick.LocalStorage} instead. See the \l {QtQuick.LocalStorage 2}{QtQuick.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 Behavioral Changes
QtQuick 2.0 includes a number of behavioral changes and you should thoroughly test your applications after
porting. These changes will not necessarily lead to run-time errors, but may break certain assumptions in your code.
Below are the prominent changes to be aware of when porting your applications.
Item opacity and visibility:
\list
\li The input handling details of \l{Item::}{opacity} and \l{Item::}{visible} have changed. An opacity of zero no
longer affects input handling, where previously it stopped mouse input. A visibility of false no longer affects
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
the item is rendered. A workaround for applying the old behavior in most cases is to bind enabled to
\tt {(visible && opacity > 0.0)}.
\li Previously, if an item was in a positioner (i.e. a \l Row, \l Column, \l Grid and \l Flow)
and the item's \c opacity changed to 0, or its \c visible value became \c false, the positioner
would remove the item from its layout and collapse the space for that item. In QtQuick 2.0, this
now only happens when an item's \c visible is \c false; the item opacity no longer affects whether
the item is laid out. (This is consistent with the existing behavior of ListView and GridView).
\endlist
Text:
\list
\li The TextEdit::textFormat property now defaults to \c PlainText instead of \c AutoText.
\li When Text::textFormat is set to \c Text.AutoText format, the text object will automatically
switch to \c Text.StyledText instead of \c Text.RichText.
\endlist
Other:
\list
\li Modifying the Image::sourceSize now fits the image to the size, maintaining aspect
ratio.
\li For ListView and GridView, the \c cacheBuffer property now has a non-zero default and
delegates in the cache buffer are created asynchronously. Also, using a \c RightToLeft layout
now also reverses the \c preferredHighlightBegin and \c preferredHighlightEnd.
\li For \l Loader, the \c sourceChanged and \c sourceComponentChanged signals are now only emitted
when their respective properties change value. (Previously \l Loader emitted both of these signals
when either of the relevant properties had changed.)
\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 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 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 no 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 QQuickWindow and uses the QWindow
infrastructure introduced in Qt 5; any QGraphicsView-specific functionality is no longer available.
\section3 qmlscene Utility
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 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 declaration.
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 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
*/
|
