Revision control

++ // Copyright (C) 2020 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \page qml-changes-qt6.html
++ \title Changes to Qt Qml
++ \ingroup changes-qt-5-to-6
++ \brief Migrate Qt Qml to Qt 6.
++
++ Qt 6 is a result of the conscious effort to make the framework more
++ efficient and easy to use.
++
++ We try to maintain binary and source compatibility for all the public
++ APIs in each release. But some changes were inevitable in an effort to
++ make Qt a better framework.
++
++ In this topic we summarize those changes in Qt Qml, and provide
++ guidance to handle them.
++
++ \section1 QML language
++
++ \section2 URL resolution
++
++ In Qt 5, relative urls were often, albeit inconsistently, directly resolved, especially when
++ assigned to an url property. In Qt 6 this is no longer the case.
++
++ If you had a QML file stored under "/home/qml/example.qml", and "example.qml" contained
++ \code
++ property url imageFolder: "./images"
++ \endcode
++ then the url property would store the URL "/home/qml/images". This made it impossible to use
++ relative URLs in QML in this way, so in Qt 6, the URL stays relative, and only gets resolved
++ when this is required (e.g. when it is used as the source of an Image component).
++ If you depend on the old behavior, you can use \c Qt.resolvedUrl
++
++ For example, if you have code like
++
++ \code
++ property url imageFolder: "./images"
++ \endcode
++
++ you can rewrite it as
++
++ \code
++ property url imageFolder: Qt.resolvedUrl("./images")
++ \endcode
++
++ Qt.resolvedUrl can be used in both Qt 5 and 6.
++
++ As a porting aid, the \c{QML_COMPAT_RESOLVE_URLS_ON_ASSIGNMENT} environment variable can be set
++ to 1 to obtain the Qt 5 behavior. This is possible since Qt 6.2.2. However, it is recommended
++ to only use this to unblock a port, and to use \c Qt.resolvedUrl as explained above.
++
++ \section2 Variant Properties
++
++ \c variant properties, which have been marked as obsolete since Qt 5, are now treated in exactly
++ the same way as \c var properties.
++ Code that relied on implicit string conversion triggered on assignment to variant properties
++ should be updated to explicitly create an object of the correct type.
++
++ For example, if you have code like
++
++ \code
++ property variant myColor: "red"
++ \endcode
++
++ you can rewrite it as
++
++ \code
++ property variant myColor: Qt.color("red")
++ \endcode
++
++ Implicit conversions were done for strings that could be parsed as
++ \list
++ \li color (use Qt.color instead),
++ \li date (use the Date object instead),
++ \li rect (use Qt.rect instead) and
++ \li size (use Qt.size instead)
++ \endlist
++
++ \c variant still remains a deprecated keyword in Qt 6, though new code is strongly encouraged to
++ use \c var properties instead.
++
++ \note If the type of the property is known not to change, use a property of the concrete type,
++ instead of a \c var property.
++
++ \note These conversions were also applied to \c QVariant properties of classes registered with
++ the engine. As with \c variant properties, code that relied on implicit string conversions need
++ to use the corresponding functions of the Qt object.
++
++ \section1 Source Incompatible API Changes
++
++ \section2 Changed API
++
++ \c QQmlListProperty's \c CountFunction and \c AtFunction have been changed to use \c qsizetype
++ instead of \c int to align with the corresponding changes in Qt's containers.
++
++ For example, if you have code like
++
++ \code
++ int myCountFunction(QQmlListProperty<MyType> *);
++ MyType *myAtFunction(QQmlListProperty<MyType> *, int);
++
++ QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction,
++ &myAtFunction);
++ \endcode
++
++ you can rewrite it as
++
++ \code
++ qsizetype myCountFunction(QQmlListProperty<MyType> *);
++ MyType *myAtFunction(QQmlListProperty<MyType> *, qsizetype);
++
++ QQmlListProperty<MyType> myReadOnlyList(containingObject, container, &myCountFunction,
++ &myAtFunction);
++ \endcode
++
++ Code which needs to supports both Qt 5 and Qt 6 can either use a typedef which is \c int in Qt 5
++ and \c qsizetype in Qt 6, or use \c QList::size_type, which already is such a type alias.
++
++ \section2 Removed API
++
++ Various deprecated functions have been removed.
++
++ \list
++ \li The QQmlListProperty constructor taking a reference has been removed.
++
++ For example, if you have code like
++
++ \code
++ QQmlListProperty<QObject>(owner, owner->objectList);
++ \endcode
++
++ you can rewrite it as
++
++ \code
++ QQmlListProperty<QObject>(owner, &owner->objectList);
++ \endcode
++
++ \li The functions \c qmlDebug, \c qmlInfo, \c qmlWarning, \c qmlContext and \c qmlEngine used
++ to exist both in the global namespace (or Qt namespace in namespaced builds), and in the \c
++ QtQml namespace. These functions now exist only in the global namespace.
++
++ For example, if you have code like
++
++ \code
++ QQmlEngine *engine = QtQml::qmlEngine(qmlObject);
++ \endcode
++
++ you can rewrite it as
++
++ \code
++ QQmlEngine *engine = qmlEngine(qmlObject);
++ \endcode
++
++ \li The \c qmlRegisterType overload taking no arguments has been removed. Use
++ \c qmlRegisterAnonymousType instead, or switch to declarative type registration with
++ \c QML_ANONYMOUS.
++
++ For example, if you have code like
++
++ \code
++ class AnonymousType : public QObject {
++ // ...
++ };
++
++ qmlRegisterType<AnonymousType>();
++ \endcode
++
++ you can rewrite it as
++
++ \code
++ class AnonymousType : public QObject {
++ // ...
++ };
++
++ qmlRegisterAnonymousType<AnonymousType>("MyModule", 1);
++ \endcode
++
++ Or alternatively
++ \code
++ class AnonymousType : public QObject {
++ QML_ANONYMOUS
++ // ...
++ };
++ \endcode
++
++ \li The overloads of \c qmlRegisterExtendedType and \c qmlRegisterInterface
++ which take no version argument have been removed. Use the overloads providing a
++ version, or switch to declarative type registration with QML_EXTENDED
++ and QML_INTERFACE.
++
++ For example, if you have code like
++
++ \code
++ struct GreetInterface
++ {
++ virtual ~GreetInterface();
++ virtual void greet();
++ };
++ Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
++
++ qmlRegisterInterface<GreetInterface>("Greeter");
++ \endcode
++
++ you can rewrite it as
++
++ \code
++ struct GreetInterface
++ {
++ virtual ~GreetInterface();
++ virtual void greet();
++ };
++ Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
++
++ qmlRegisterInterface<GreetInterface>("Greeter", 1);
++ \endcode
++
++ Alternatively
++
++ \code
++ struct GreetInterface
++ {
++ QML_INTERFACE(Greeter)
++ virtual ~GreetInterface();
++ virtual void greet();
++ };
++ Q_DECLARE_INTERFACE(GreetInterface, "org.hi.GreetInterface")
++ \endcode
++
++ \note In new code, declarative type registration should be preferred.
++
++ \li The function \c QJSValue::engine has been removed. If access to the engine is required, a
++ reference to it must be stored instead.
++
++ \li \c qmlAttachedPropertiesObjectById and \c qmlAttachedPropertiesObject(int *, const QObject *,
++ const QMetaObject *, bool) have been removed. Use the
++ \c qmlAttachedPropertiesObject(QObject *, QQmlAttachedPropertiesFunc, bool) overload of
++ \c qmlAttachedPropertiesObject instead.
++
++ \li \c QJSEngine::installTranslatorFunctions has been removed. \c QJSEngine::installExtensions
++ is available as a replacement.
++
++ For example, if you have code like
++
++ \code
++ QJSEngine engine;
++ engine.installTranslatorFunctions();
++ \endcode
++
++ you can rewrite it as
++
++ \code
++ QJSEngine engine;
++ engine.installExtensions(QJSEngine::TranslationExtension);
++ \endcode
++
++ \endlist
++
++ \sa {Modernizing QML Modules}, {Port QML modules to CMake}
++ */