1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page qml-changes-qt6.html
6 \title Changes to Qt QML
7 \ingroup changes-qt-5-to-6
8 \brief Migrate Qt QML to Qt 6.
10 Qt 6 is a result of the conscious effort to make the framework more
11 efficient and easy to use.
13 We try to maintain binary and source compatibility for all the public
14 APIs in each release. But some changes were inevitable in an effort to
15 make Qt a better framework.
17 In this topic we summarize those changes in Qt QML, and provide
18 guidance to handle them.
20 \section1 QML language
22 \section2 URL resolution
24 In Qt 5, relative urls were often, albeit inconsistently, directly resolved, especially when
25 assigned to an url property. In Qt 6 this is no longer the case.
27 If you had a QML file stored under "/home/qml/example.qml", and "example.qml" contained
29 property url imageFolder: "./images"
31 then the url property would store the URL "/home/qml/images". This made it impossible to use
32 relative URLs in QML in this way, so in Qt 6, the URL stays relative, and only gets resolved
33 when this is required (e.g. when it is used as the source of an Image component).
34 If you depend on the old behavior, you can use \c Qt.resolvedUrl
36 For example, if you have code like
39 property url imageFolder: "./images"
45 property url imageFolder: Qt.resolvedUrl("./images")
48 Qt.resolvedUrl can be used in both Qt 5 and 6.
50 \section2 Variant Properties
52 \c variant properties, which have been marked as obsolete since Qt 5, are now treated in exactly
53 the same way as \c var properties.
54 Code that relied on implicit string conversion triggered on assignment to variant properties
55 should be updated to explicitly create an object of the correct type.
57 For example, if you have code like
60 property variant myColor: "red"
66 property variant myColor: Qt.color("red")
69 Implicit conversions were done for strings that could be parsed as
71 \li color (use Qt.color instead),
72 \li date (use the Date object instead),
73 \li rect (use Qt.rect instead) and
74 \li size (use Qt.size instead)
77 \c variant still remains a deprecated keyword in Qt 6, though new code is strongly encouraged to
78 use \c var properties instead.
80 \note If the type of the property is known not to change, use a property of the concrete type,
81 instead of a \c var property.
83 \note These conversions were also applied to \c QVariant properties of classes registered with
84 the engine. As with \c variant properties, code that relied on implicit string conversions need
85 to use the corresponding functions of the Qt object.
87 \section1 Source Incompatible API Changes
91 \c QQmlListProperty's \c CountFunction and \c AtFunction have been changed to use \c qsizetype
92 instead of \c int to align with the corresponding changes in Qt's containers.
94 For example, if you have code like
97 int myCountFunction(QQmlListProperty<MyType> *);
98 MyType *myAtFunction(QQmlListProperty<MyType> *, int);
100 QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction,
104 you can rewrite it as
107 qsizetype myCountFunction(QQmlListProperty<MyType> *);
108 MyType *myAtFunction(QQmlListProperty<MyType> *, qsizetype);
110 QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction,
114 Code which needs to supports both Qt 5 and Qt 6 can either use a typedef which is \c int in Qt 5
115 and \c qsizetype in Qt 6, or use \c QList::size_type, which already is such a type alias.
117 \section2 Removed API
119 Various deprecated functions have been removed.
122 \li The QQmlListProperty constructor taking a reference has been removed.
124 For example, if you have code like
127 QQmlListProperty<QObject>(owner, owner->objectList);
130 you can rewrite it as
133 QQmlListProperty<QObject>(owner, &owner->objectList);
136 \li The functions \c qmlDebug, \c qmlInfo, \c qmlWarning, \c qmlContext and \c qmlEngine used
137 to exist both in the global namespace (or Qt namespace in namespaced builds), and in the \c
138 QtQml namespace. These functions now exist only in the global namespace.
140 For example, if you have code like
143 QQmlEngine *engine = QtQml::qmlEngine(qmlObject);
146 you can rewrite it as
149 QQmlEngine *engine = qmlEngine(qmlObject);
152 \li The \c qmlRegisterType overload taking no arguments has been removed. Use
153 \c qmlRegisterAnonymousType instead, or switch to declarative type registration with
156 For example, if you have code like
159 class AnonymousType : public QObject {
163 qmlRegisterType<AnonymousType>();
166 you can rewrite it as
169 class AnonymousType : public QObject {
173 qmlRegisterAnonymousType<AnonymousType>("MyModule", 1);
178 class AnonymousType : public QObject {
184 \li The overloads of \c qmlRegisterExtendedType and \c qmlRegisterInterface
185 which take no version argument have been removed. Use the overloads providing a
186 version, or switch to declarative type registration with QML_EXTENDED
189 For example, if you have code like
192 struct GreetInterface
194 virtual ~GreetInterface();
195 virtual void greet();
197 Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
199 qmlRegisterInterface<GreetInterface>("Greeter");
202 you can rewrite it as
205 struct GreetInterface
207 virtual ~GreetInterface();
208 virtual void greet();
210 Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
212 qmlRegisterInterface<GreetInterface>("Greeter", 1);
218 struct GreetInterface
220 QML_INTERFACE(Greeter)
221 virtual ~GreetInterface();
222 virtual void greet();
224 Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
227 \note In new code, declarative type registration should be preferred.
229 \li The function \c QJSValue::engine has been removed. If access to the engine is required, a
230 reference to it must be stored instead.
232 \li \c qmlAttachedPropertiesObjectById and \c qmlAttachedPropertiesObject(int *, const QObject *,
233 const QMetaObject *, bool) have been removed. Use the
234 \c qmlAttachedPropertiesObject(QObject *, QQmlAttachedPropertiesFunc, bool) overload of
235 \c qmlAttachedPropertiesObject instead.
237 \li \c QJSEngine::installTranslatorFunctions has been removed. \c QJSEngine::installExtensions
238 is available as a replacement.
240 For example, if you have code like
244 engine.installTranslatorFunctions();
247 you can rewrite it as
251 engine.installExtensions(QJSEngine::TranslationExtension);