path: root/src/qml/doc/src/qmlfunctions.qdoc

// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
  \macro QML_ELEMENT
  \relates QQmlEngine

  Declares the enclosing type or namespace to be available in QML, using its
  class or namespace name as the QML element name.

  For example, this makes the C++ class \c Slider available as a QML type
  named \c Slider. All its properties, invokable methods and enums are exposed.

  \code
  class Slider : public QObject
  {
      Q_OBJECT
      QML_ELEMENT
      Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged FINAL)
      // ...
  public:
      enum Slippiness {
          Dry, Wet, Icy
      };
      Q_ENUM(Slippiness)

      Q_INVOKABLE void slide(Slippiness slippiness);

      // ...
  }
  \endcode

  You can use the build system to register the type in the type namespace
  \e {com.mycompany.qmlcomponents} with major version \c 1.
  For qmake, specify the following in your project file:

  \badcode
  CONFIG += qmltypes
  QML_IMPORT_NAME = com.mycompany.qmlcomponents
  QML_IMPORT_MAJOR_VERSION = 1
  \endcode

  With CMake, you pass the URI and version to qt_add_qml_module

  \badcode
  qt6_add_qml_module(myapp
    URI com.mycompany.qmlcomponents
    VERSION 1.0
  )
  \endcode

  Once registered, the type can be used in QML by importing the
  same type namespace and version number:

  \qml
  import com.mycompany.qmlcomponents 1.0

  Slider {
      value: 12
      Component.onCompleted: slide(Slider.Icy)

      // ...
  }
  \endqml

  You can also make namespaces tagged with Q_NAMESPACE available this way, in
  order to expose any enums tagged with Q_ENUM_NS they contain:

  \code
  namespace MyNamespace {
    Q_NAMESPACE
    QML_ELEMENT

    enum MyEnum {
        Key1,
        Key2,
    };
    Q_ENUM_NS(MyEnum)
  }
  \endcode

  In QML, you can then use the enums:

  \qml
  Component.onCompleted: console.log(MyNamespace.Key2)
  \endqml

  \b{NOTE:} When classes have the same name but are located in different namespaces using
  \l QML_ELEMENT on both of them will cause a conflict.
  Make sure to use \l QML_NAMED_ELEMENT() for one of them instead.

  \include {qualified-class-name.qdocinc} {class name must be qualified}

  \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT(),
      Q_REVISION(), QML_ADDED_IN_VERSION()
*/

/*!
  \macro QML_NAMED_ELEMENT(name)
  \relates QQmlEngine

  Declares the enclosing type or namespace to be available in QML, using \a name
  as the element name. Otherwise behaves the same as QML_ELEMENT.

  \code
  class SqlEventDatabase : public QObject
  {
      Q_OBJECT
      QML_NAMED_ELEMENT(EventDatabase)

      // ...
  };
  \endcode

  \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_ELEMENT
*/

/*!
  \macro QML_ANONYMOUS
  \relates QQmlEngine

  Declares the enclosing type to be available, but anonymous in QML. The type
  cannot be created or used to declare properties in QML, but when passed from
  C++, it is recognized. In QML, you can use properties of this type if they
  are declared in C++.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_INTERFACE
*/

/*!
  \macro QML_INTERFACE
  \relates QQmlEngine

  This macro registers the enclosing C++ type in the QML system as an interface.

  Types registered as an interface in QML should also declare themselves as an
  interface with the \l {The Meta-Object System}{meta object system}. For
  example:

  \code
  struct FooInterface
  {
      QML_INTERFACE
  public:
      virtual ~FooInterface();
      virtual void doSomething() = 0;
  };

  Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")
  \endcode

  When registered with QML in this way, they can be used as property types:

  Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

  When you assign a \l QObject sub-class to this property, the QML engine does
  the interface cast to \c FooInterface* automatically.

  Interface types are implicitly anonymous and uncreatable in QML.

  \b{NOTE:} When inheriting from types using QML_INTERFACE, use \l QML_IMPLEMENTS_INTERFACES
  instead of \l Q_INTERFACES.

  \sa  QML_IMPLEMENTS_INTERFACES(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_ANONYMOUS
*/

/*!
  \macro QML_IMPLEMENTS_INTERFACES(interfaces)
  \relates QQmlEngine

  This macro tells Qt which QML \a interfaces the class implements.
  This macro should only be used for interfacing with classes using \l QML_INTERFACE, use \l Q_INTERFACES otherwise.
  It's required in order for declarative registration via \l QML_ELEMENT to
  function properly.

  \sa QML_INTERFACE, Q_INTERFACES
*/

/*!
  \macro QML_UNCREATABLE(reason)
  \relates QQmlEngine

  Declares that the enclosing type shall not be creatable from QML. This takes
  effect if the type is available in QML, by having a \l QML_ELEMENT or
  \l QML_NAMED_ELEMENT() macro. The \a reason will be emitted as error message if an
  attempt to create the type from QML is detected.

  Some QML types are implicitly uncreatable, in particular types exposed with
  \l QML_ANONYMOUS or namespaces exposed with \l QML_ELEMENT or
  \l QML_NAMED_ELEMENT().

  Since Qt 6.0 you can use "" instead of a reason to use a standard message
  instead.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS
*/

/*!
  \macro QML_SINGLETON
  \relates QQmlEngine

  Declares the enclosing type to be a singleton in QML. This only takes effect
  if the type is a \l Q_OBJECT and is available in QML (by having a
  \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro). By default, each QQmlEngine
  will try to create a singleton instance using either the type's default
  constructor or a static factory function of the signature
  \c{T *create(QQmlEngine *, QJSEngine *)} when the type is first accessed.
  If both do exist and are accessible, the default constructor is preferred.
  If there is no default constructor and no factory function the singleton is
  inaccessible. The QML engine generally assumes ownership of the singleton and
  will delete it when the engine itself is destroyed. You can prevent this by
  calling QJSEngine::setObjectOwnership() on the singleton.

  In order to declare a default-constructible class as singleton, all you have
  to do is add \l QML_SINGLETON:

  \code
  class MySingleton : public QObject
  {
      Q_OBJECT
      QML_ELEMENT
      QML_SINGLETON
      // Q_PROPERTY( ... )
  public:
      // members, Q_INVOKABLE functions, etc.
  };
  \endcode

  If the singleton class is not default-constructible, but you can modify it,
  you can add a factory function to it, in order to make it accessible:

  \code
  class MySingleton : public QObject
  {
      Q_OBJECT
      QML_ELEMENT
      QML_SINGLETON
      // Q_PROPERTY( ... )

  public:
      static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
      {
          MySingleton *result = nullptr;
          // Create the object using some custom constructor or factory.
          // The QML engine will assume ownership and delete it, eventually.
          return result;
      }

      // members, Q_INVOKABLE functions, etc
  };
  \endcode

  If you cannot modify the class and it does not have a default constructor or a
  suitable factory function, you can provide a \l QML_FOREIGN wrapper to define
  the factory function:

  \code
  struct SingletonForeign
  {
      Q_GADGET
      QML_FOREIGN(MySingleton)
      QML_SINGLETON
      QML_NAMED_ELEMENT(MySingleton)
  public:

      static MySingleton *create(QQmlEngine *, QJSEngine *engine)
      {
          MySingleton *result = nullptr;
          // Create the instance using some custom constructor or factory.
          // The QML engine will assume ownership and delete it, eventually.
          return result;
      }
  };
  \endcode

  Finally, if you want to provide one specific singleton object, the creation of
  which you cannot control, you can return that from a factory function. This is
  a replacement for the \l qmlRegisterSingletonInstance function.
  If you were calling

  \code
  qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject);
  \endcode

  with myObject being of type \c{MySingleton *}, you can do the following
  instead:

  \code
  struct SingletonForeign
  {
      Q_GADGET
      QML_FOREIGN(MySingleton)
      QML_SINGLETON
      QML_NAMED_ELEMENT(MySingleton)
  public:

      // Initialize this using myObject where you would previously
      // call qmlRegisterSingletonInstance().
      inline static MySingleton *s_singletonInstance = nullptr;

      static MySingleton *create(QQmlEngine *, QJSEngine *engine)
      {
          // The instance has to exist before it is used. We cannot replace it.
          Q_ASSERT(s_singletonInstance);

          // The engine has to have the same thread affinity as the singleton.
          Q_ASSERT(engine->thread() == s_singletonInstance->thread());

          // There can only be one engine accessing the singleton.
          if (s_engine)
              Q_ASSERT(engine == s_engine);
          else
              s_engine = engine;

          // Explicitly specify C++ ownership so that the engine doesn't delete
          // the instance.
          QJSEngine::setObjectOwnership(s_singletonInstance,
                                        QJSEngine::CppOwnership);
          return s_singletonInstance;
      }

  private:
      inline static QJSEngine *s_engine = nullptr;
  };
  \endcode

  This way, the pre-existing class \c MySingleton is declared to be a QML
  singleton, called \c MySingleton. You can specify an instance for it any time
  before it is used by setting the \c s_singletonInstance member. None of this
  requires modification of \c MySingleton itself.

  \note This pattern doesn't work if either the singleton is accessed by
  multiple QML engines, or if the QML engine accessing it has a different thread
  affinity than the singleton object itself. As shown above, you can check the
  parameters to the \c create() method for identity and thread affinity of the
  engine in order to assert on that.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(),
      qmlRegisterSingletonInstance(), QQmlEngine::singletonInstance(), {Singletons in QML}
*/

/*!
  \macro QML_ADDED_IN_VERSION(MAJOR, MINOR)
  \relates QQmlEngine

  Declares that the enclosing type or namespace was added in the specified
  \a{MAJOR}.\a{MINOR} version. The version is assumed to be in line with any
  revisions given by \l Q_REVISION() macros on methods, slots, or signals,
  and any REVISION() attributes on properties declared with \l Q_PROPERTY().

  \l QML_ADDED_IN_VERSION() only takes effect if the type or namespace is
  available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
  \l QML_ANONYMOUS, or \l QML_INTERFACE macro.

  If the QML module the type belongs to is imported with a lower version than
  the one determined this way, the QML type is invisible.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT
*/

/*!
  \macro QML_ADDED_IN_MINOR_VERSION(VERSION)
  \relates QQmlEngine
  \deprecated [6.7] Use QML_ADDED_IN_VERSION and specify the full version

  Declares that the enclosing type or namespace was added in the specified minor
  \a VERSION, relative to the module major version. The minor version is assumed
  to be in line with any revisions given by \l Q_REVISION() macros on methods,
  slots, or signals, and any REVISION() attributes on properties declared with
  \l Q_PROPERTY().

  \l QML_ADDED_IN_MINOR_VERSION() only takes effect if the type or namespace is
  available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
  \l QML_ANONYMOUS, or \l QML_INTERFACE macro.

  If the QML module the type belongs to is imported with a lower version than
  the one determined this way, the QML type is invisible.

  \sa QML_ADDED_IN_VERSION, QML_ELEMENT, QML_NAMED_ELEMENT
*/

/*!
  \macro QML_REMOVED_IN_VERSION(MAJOR, MINOR)
  \relates QQmlEngine

  Declares that the enclosing type or namespace was removed in the specified
  \a{MAJOR}.\a{MINOR} version. This is primarily useful when replacing the
  implementation of a QML type. If a corresponding \l QML_ADDED_IN_VERSION()
  is present on a different type or namespace of the same QML name, then the
  removed type is used when importing versions of the module lower than
  \a{MAJOR}.\a{MINOR}, and the added type is used when importing
  versions of the module greater or equal \a{MAJOR}.\a{MINOR}.

  \l QML_REMOVED_IN_VERSION() only takes effect if type or namespace is
  available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
  \l QML_ANONYMOUS, or \l QML_INTERFACE macro.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT
*/

/*!
  \macro QML_REMOVED_IN_MINOR_VERSION(VERSION)
  \relates QQmlEngine
  \deprecated [6.7] Use QML_REMOVED_IN_VERSION and specify the full version

  Declares that the enclosing type or namespace was removed in the specified
  minor \a VERSION, relative to the module major version. This is primarily
  useful when replacing the implementation of a QML type. If a corresponding
  \l QML_ADDED_IN_VERSION() is present on a different type or namespace of
  the same QML name, then the removed type is used when importing versions of
  the module lower than \a VERSION, and the added type is used when importing
  versions of the module greater or equal \a VERSION.

  \l QML_REMOVED_IN_MINOR_VERSION() only takes effect if type or namespace is
  available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
  \l QML_ANONYMOUS, or \l QML_INTERFACE macro.

  \sa QML_REMOVED_IN_VERSION, QML_ELEMENT, QML_NAMED_ELEMENT
*/

/*!
  \macro QML_EXTRA_VERSION(MAJOR, MINOR)
  \relates QQmlEngine

  Declare that the type should also be available in version \a{MAJOR}.\a{MINOR}.
  This can be helpful if a type should be available in multiple major versions.

  Types are automatically registered for:
  \list
  \li The major version they were introduced in, see \l{QML_ADDED_IN_VERSION}.
  \li Any major versions any their members were introduced in.
  \li The current major version of their module, unless they were
      \l{QML_REMOVED_IN_VERSION} before that.
  \endlist

  Notably, they are not automatically registered in any \l{PAST_MAJOR_VERSIONS}
  between the above. You can use QML_EXTRA_VERSION to manually register your
  types in further major versions.

  \note Keeping multiple \l{PAST_MAJOR_VERSIONS} around is computationally
        expensive.

  \sa QML_ELEMENT, QML_ADDED_IN_VERSION
*/

/*!
  \macro QML_ATTACHED(ATTACHED_TYPE)
  \relates QQmlEngine

  Declares that the enclosing type attaches \a ATTACHED_TYPE as an
  \l {Attached Properties and Attached Signal Handlers}
  {attached property} to other types. This takes effect if the type
  is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro.

  \include {qualified-class-name.qdocinc} {class name must be qualified}

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(),
      {Providing Attached Properties}
*/

/*!
  \macro QML_EXTENDED(EXTENDED_TYPE)
  \relates QQmlEngine

  Declares that the enclosing type uses \a EXTENDED_TYPE as an extension to
  provide further properties, methods, and enumerations in QML. This takes
  effect if the type is exposed to QML using a \l QML_ELEMENT or
  \l QML_NAMED_ELEMENT() macro.

  \warning Members of \a EXTENDED_TYPE are implicitly treated as FINAL.

  \include {qualified-class-name.qdocinc} {class name must be qualified}

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED_NAMESPACE(),
      {Registering Extension Objects}
*/

/*!
  \macro QML_EXTENDED_NAMESPACE(EXTENDED_NAMESPACE)
  \relates QQmlEngine

  Declares that the enclosing type uses \a EXTENDED_NAMESPACE as an extension to
  provide further enumerations in QML. This takes effect if the type
  is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro.
  The enumerations need to be exposed to the metaobject system for this to work.

  For example, give the following C++ code
  \code
  namespace MyNamespace {
      Q_NAMESPACE
      enum MyEnum { MyEnumerator = 10 };
      Q_ENUM_NS(MyEnum)
  }

  class QmlType : public QObject
  {
      Q_OBJECT
      QML_ELEMENT
      QML_EXTENDED_NAMESPACE(MyNamespace)
  }
  \endcode

  we can access the enum in QML:
  \qml
  QmlType {
      property int i: QmlType.MyEnumerator // i will be 10
  }
  \endqml

  \note EXTENDED_NAMESPACE can also be a QObject or QGadget; in that case - and in contrast to
  QML_EXTENDED, which also exposes methods and properties - only its enumerations
  are exposed.

  \note \a EXTENDED_NAMESPACE must have a metaobject; i.e. it must either be a namespace which
  contains the Q_NAMESPACE macro or a QObject/QGadget.

  \include {qualified-class-name.qdocinc} {class name must be qualified}

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED(),
      {Registering Extension Objects}, Q_ENUM, Q_ENUM_NS
*/

/*!
  \macro QML_FOREIGN(FOREIGN_TYPE)
  \relates QQmlEngine

  Declares that any \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), \l QML_ANONYMOUS,
  \l QML_INTERFACE, \l QML_UNCREATABLE(), \l QML_SINGLETON,
  \l QML_ADDED_IN_VERSION(), \l QML_REMOVED_IN_VERSION(),
  \l QML_ADDED_IN_MINOR_VERSION(), \l QML_REMOVED_IN_MINOR_VERSION(),
  \l QML_EXTENDED(), or \l  QML_EXTENDED_NAMESPACE() macros
  in the enclosing C++ type do not apply to the enclosing type but instead to
  \a FOREIGN_TYPE. The enclosing type still needs to be registered with the
  \l {The Meta-Object System}{meta object system} using a \l Q_GADGET or
  \l Q_OBJECT macro.

  This is useful for registering types that cannot be amended to add the macros,
  for example because they belong to 3rdparty libraries.
  To register a namespace, see \l QML_FOREIGN_NAMESPACE().

  \note You may want to use \l QML_NAMED_ELEMENT() instead of \l QML_ELEMENT.
  With QML_ELEMENT, the element is named after the struct it is contained in,
  not the foreign type. The \l {Foreign objects integration} chapter in
  \l {Writing advanced QML Extensions with C++} demonstrates this.

  \note QML_ATTACHED() can currently not be redirected like this. It has to be
  specificed in the same type that implements qmlAttachedProperties().

  \include {qualified-class-name.qdocinc} {class name must be qualified}

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_FOREIGN_NAMESPACE()
*/

/*!
  \macro QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)
  \relates QQmlEngine

  Declares that any \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), \l QML_ANONYMOUS,
  \l QML_INTERFACE, \l QML_UNCREATABLE(), \l QML_SINGLETON,
  \l QML_ADDED_IN_VERSION(), \l QML_REMOVED_IN_VERSION(),
  \l QML_ADDED_IN_MINOR_VERSION(), or \l QML_REMOVED_IN_MINOR_VERSION()
  macros in the enclosing C++ namespace do not apply to the enclosing type but
  instead to \a FOREIGN_NAMESPACE. The enclosing namespace still needs to be
  registered with the \l {The Meta-Object System}{meta object system} using a
  \l Q_NAMESPACE macro.

  This is useful for registering namespaces that cannot be amended to add the macros,
  for example because they belong to 3rdparty libraries.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_FOREIGN()
*/

/*!
  \macro QML_UNAVAILABLE
  \relates QQmlEngine

  This macro declares the enclosing type to be unavailable in QML. It registers
  an internal dummy type called \c QQmlTypeNotAvailable as \l QML_FOREIGN()
  type, using any further QML macros you specify.

  Normally, the types exported by a module should be fixed. However, if a C++
  type is not available, you should at least "reserve" the QML type name, and
  give the user of the unavailable type a meaningful error message.

  Example:

  \code
  #ifdef NO_GAMES_ALLOWED
  struct MinehuntGame
  {
      Q_GADGET
      QML_NAMED_ELEMENT(Game)
      QML_UNAVAILABLE
      QML_UNCREATABLE("Get back to work, slacker!");
  };
  #else
  class MinehuntGame : public QObject
  {
      Q_OBJECT
      QML_NAMED_ELEMENT(Game)
      // ...
  };
  #endif
  \endcode

  This will cause any QML which attempts to use the "Game" type to produce an
  error message:

  \badcode
  fun.qml: Get back to work, slacker!
     Game {
     ^
  \endcode

  Using this technique, you only need a \l Q_GADGET struct to customize the error
  message, not a full-blown \l QObject. Without \l QML_UNCREATABLE(),
  \l QML_UNAVAILABLE still results in a more specific error message than the usual
  "is not a type" for completely unknown types.

  \include {qualified-class-name.qdocinc} {class name must be qualified}

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_FOREIGN()
*/

/*!
  \macro QML_SEQUENTIAL_CONTAINER(VALUE_TYPE)
  \relates QQmlEngine

  This macro declares the enclosing or referenced type as a sequential container
  managing a sequence of \a VALUE_TYPE elements. \a VALUE_TYPE can be an actual
  \l{QML Value Types}{value type} or a pointer to an
  \l{QML Object Types}{object type}. You will rarely be able to add this macro
  to the actual container declaration since containers are usually templates.
  You should use \l{QML_FOREIGN} to attach the type registration to a template
  instantiation. Using this technique you can, for example, declare sequential
  containers like this:

  \code
  class IntDequeRegistration
  {
    Q_GADGET
    QML_FOREIGN(std::deque<int>)
    QML_ANONYMOUS
    QML_SEQUENTIAL_CONTAINER(int)
  };
  \endcode

  After this, you can use the container like a JavaScript array in QML.

  \code
  class Maze
  {
    Q_OBJECT
    Q_ELEMENT
    // 0: North, 1: East, 2: South, 3: West
    Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL)
    [...]
  }
  \endcode

  \code
  Item {
    Maze {
      id: maze
    }

    function showSolution() {
        maze.solution.forEach([...])
    }
  }
  \endcode

  \note For \l{QML Value Types} \l{QList} is automatically registered as
  sequential container. For \l{QML Object Types} \l{QQmlListProperty} is.
  You don't have to add these registrations.

  \note You cannot currently give the container a custom name. Any argument
  passed to \l{QML_NAMED_ELEMENT} is ignored. The automatically registered
  sequential containers are available under the familiar \e{list<...>} names,
  for example \e{list<QtObject>} or \e{list<font>}.

  \include {qualified-class-name.qdocinc} {class name must be qualified}

  \sa QML_ANONYMOUS, QML_FOREIGN()
*/

/*!
  \macro QML_DECLARE_TYPE()
  \relates QQmlEngine

  Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)
*/

/*!
  \macro QML_DECLARE_TYPEINFO(Type,Flags)
  \relates QQmlEngine

  Declares additional properties of the given \a Type as described by the
  specified \a Flags.

  Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which
  declares that the \a Type supports \l {Attached Properties and Attached Signal Handlers}
  {attached properties}. QML_DECLARE_TYPEINFO() is not necessary if \a Type contains the
  QML_ATTACHED macro.
*/

/*!
  \fn void qmlClearTypeRegistrations()
  \relates QQmlEngine

  Clears all stored type registrations, such as those produced with \l qmlRegisterType().

  Do not call this function while a QQmlEngine exists or behavior will be undefined.
  Any existing QQmlEngines must be deleted before calling this function.  This function
  only affects the application global cache. Delete the QQmlEngine to clear all cached
  data relating to that engine.
*/


/*!
  \fn template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
  \relates QQmlEngine

  This template function registers the C++ type in the QML system with
  the name \a qmlName, in the library imported from \a uri having the
  version number composed from \a versionMajor and \a versionMinor.

  Returns the QML type id.

  There are two forms of this template function:

  \code
  template<typename T>
  int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);

  template<typename T, int metaObjectRevision>
  int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
  \endcode

  The former is the standard form which registers the type \e T as a new type.
  The latter allows a particular revision of a class to be registered in
  a specified version (see \l {Type Revisions and Versions}).


  For example, this registers a C++ class \c MySliderItem as a QML type
  named \c Slider for version 1.0 of a type namespace called
  "com.mycompany.qmlcomponents":

  \code
  qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");
  \endcode

  Once this is registered, the type can be used in QML by importing the
  specified type namespace and version number:

  \qml
  import com.mycompany.qmlcomponents 1.0

  Slider {
      // ...
  }
  \endqml

  Note that it's perfectly reasonable for a library to register types to older versions
  than the actual version of the library. Indeed, it is normal for the new library to allow
  QML written to previous versions to continue to work, even if more advanced versions of
  some of its types are available.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(),
      {Choosing the Correct Integration Method Between C++ and QML}
*/

/*!
  \fn template<typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
  \relates QQmlEngine

  This template function registers the specified revision of a C++ type in the QML system with
  the library imported from \a uri having the version number composed
  from \a versionMajor and \a versionMinor.

  Returns the QML type id.

  \code
  template<typename T, int metaObjectRevision>
  int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);
  \endcode

  This function is typically used to register the revision of a base class to
  use for the specified version of the type (see \l {Type Revisions and Versions}).
*/

/*!
  \fn template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
  \relates QQmlEngine

  This template function registers the C++ type in the QML system with
  the name \a qmlName, in the library imported from \a uri having the
  version number composed from \a versionMajor and \a versionMinor.

  While the type has a name and a type, it cannot be created, and the
  given error \a message will result if creation is attempted.

  This is useful where the type is only intended for providing attached properties or enum values.

  Returns the QML type id.

  \sa QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(),
      {Choosing the Correct Integration Method Between C++ and QML}
*/

/*!
  \fn template <typename T, typename E> int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
  \relates QQmlEngine

  This template function registers the C++ type and its extension object in the
  QML system with the name \a qmlName in the library imported from \a uri having
  version number composed from \a versionMajor and \a versionMinor. Properties
  not available in the main type will be searched for in the extension object.

  Returns the QML type id.

  \sa QML_EXTENDED(), qmlRegisterType(), {Registering Extension Objects}
*/


/*!
  \fn template <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason)
  \relates QQmlEngine

  This template function registers the C++ type and its extension
  in the QML system with the name \a qmlName in the library imported
  from \a uri having version number composed from \a versionMajor and
  \a versionMinor.

  While the type has a name and a type, it cannot be created. An error
  message with the given \a reason is printed if the user attempts to
  create an instance of this type.

  This is useful where the type is only intended for providing attached
  properties, enum values or an abstract base class with its extension.

  Returns the QML type id.

  \sa QML_EXTENDED(), QML_UNCREATABLE(), qmlRegisterUncreatableType()
*/

/*!
  \fn static inline int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason)
  \relates QQmlEngine
  \since 5.8

  This function registers the \a staticMetaObject and its extension
  in the QML system with the name \a qmlName in the library imported
  from \a uri having version number composed from \a versionMajor and
  \a versionMinor.

  An instance of the meta object cannot be created. An error message with
  the given \a reason is printed if the user attempts to create it.

  This function is useful for registering Q_NAMESPACE namespaces.

  Returns the QML type id.

  For example:

  \code
  namespace MyNamespace {
    Q_NAMESPACE
    enum MyEnum {
        Key1,
        Key2,
    };
    Q_ENUM_NS(MyEnum)
  }

  //...
  qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");
  \endcode

  On the QML side, you can now use the registered enums:
  \code
  Component.onCompleted: console.log(MyNamespace.Key2)
  \endcode

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE()
*/

/*!
  \fn int qmlRegisterCustomExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, QQmlCustomParser *parser)
  \relates QQmlEngine
  \internal

  This template function registers the C++ type and its extension
  in the QML system with the name \a qmlName in the library imported
  from \a uri having version number composed from \a versionMajor and
  \a versionMinor. Properties from the C++ type or its extension that
  cannot be resolved directly by the QML system will be resolved using
  the \a parser provided.

  Returns the QML type id.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED()
*/

/*!
  \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
  \relates QQmlEngine

  This function registers a type in the QML system with the name \a qmlName, in the type namespace imported from \a uri having the
  version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type
  will produce the given error \a message.

  Normally, the types exported by a plugin should be fixed. However, if a C++ type is not available, you should
  at least "reserve" the QML type name, and give the user of the unavailable type a meaningful error message.

  Returns the QML type id.

  Example:

  \code
  #ifdef NO_GAMES_ALLOWED
  qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
  #else
  qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
  #endif
  \endcode

  This will cause any QML which imports the "MinehuntCore" type namespace and attempts to use the type to produce an error message:
  \code
  fun.qml: Get back to work, slacker!
     Game {
     ^
  \endcode

  Without this, a generic "Game is not a type" message would be given.

  \sa QML_UNAVAILABLE, qmlRegisterUncreatableType(),
      {Choosing the Correct Integration Method Between C++ and QML}
*/

/*!
  \fn template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)
  \relates QQmlEngine

  This template function registers the C++ type in the QML system as an anonymous type. The
  resulting QML type does not have a name. Therefore, instances of this type cannot be created from
  the QML system. You can, however, access instances of the type when they are exposed as properties
  of other types.

  Use this function when the type will not be referenced by name, specifically for C++ types that
  are used on the left-hand side of a property binding. To indicate to which module the type belongs
  use \a uri and \a versionMajor.

  For example, consider the following two classes:

    \code
    class Bar : public QObject
    {
        Q_OBJECT
        Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)

    public:
        Bar() {}

        QString baz() const { return mBaz; }

        void setBaz(const QString &baz)
        {
            if (baz == mBaz)
                return;

            mBaz = baz;
            emit bazChanged();
        }

    signals:
        void bazChanged();

    private:
        QString mBaz;
    };

    class Foo : public QObject
    {
        Q_OBJECT
        Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)

    public:
        Foo() {}

        Bar *bar() { return &mBar; }

    private:
        Bar mBar;
    };
    \endcode

  In QML, we assign a string to the \c baz property of \c bar:

    \code
    Foo {
        bar.baz: "abc"
        Component.onCompleted: print(bar.baz)
    }
    \endcode

  For the QML engine to know that the \c Bar type has a \c baz property,
  we have to make \c Bar known:

    \code
    qmlRegisterType<Foo>("App", 1, 0, "Foo");
    qmlRegisterAnonymousType<Bar>("App", 1);
    \endcode

  As the \c Foo type is instantiated in QML, it must be registered
  with the version of \l qmlRegisterType() that takes an element name.

  Returns the QML type id.

  \since 5.14
  \sa QML_ANONYMOUS, {Choosing the Correct Integration Method Between C++ and QML}
*/

/*!
    \fn int qmlRegisterInterface(const char *typeName)
    \relates QQmlEngine

    This template function registers the C++ type in the QML system
    under the name \a typeName.

    Types registered as an interface with the engine should also
    declare themselves as an interface with the
    \l {The Meta-Object System}{meta object system}. For example:

    \code
    struct FooInterface
    {
    public:
        virtual ~FooInterface();
        virtual void doSomething() = 0;
    };

    Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")
    \endcode

    When registered with the QML engine in this way, they can be used as
    property types:

    Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)

    When you assign a \l QObject sub-class to this property, the QML engine does
    the interface cast to \c FooInterface* automatically.

    Returns the QML type id.

    \sa QML_INTERFACE
*/

/*!
   \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue(QQmlEngine *, QJSEngine *)> callback)
   \relates QQmlEngine

   This function may be used to register a singleton type provider \a callback in a particular \a uri
   and \a typeName with a version specified in \a versionMajor and \a versionMinor.

   Installing a singleton type allows developers to provide arbitrary functionality
   (methods and properties) to a client without requiring individual instances of the type to
   be instantiated by the client.

   A singleton type may be either a QObject or a QJSValue.
   This function should be used to register a singleton type provider function which returns a QJSValue as a singleton type.

   \b{NOTE:} QJSValue singleton type properties will \b{not} trigger binding re-evaluation if changed.

   Usage:
   \code
   // First, define the singleton type provider function (callback).
   static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
   {
       Q_UNUSED(engine)

       static int seedValue = 5;
       QJSValue example = scriptEngine->newObject();
       example.setProperty("someProperty", seedValue++);
       return example;
   }

   // Second, register the singleton type provider with QML by calling this function in an initialization function.
   qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);
   \endcode

   Alternatively, you can use a C++11 lambda:

   \code
   qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue {
       Q_UNUSED(engine)

       static int seedValue = 5;
       QJSValue example = scriptEngine->newObject();
       example.setProperty("someProperty", seedValue++);
       return example;
   });
   \endcode

   In order to use the registered singleton type in QML, you must import the singleton type.
   \qml
   import QtQuick 2.0
   import Qt.example.qjsvalueApi 1.0 as ExampleApi
   Item {
       id: root
       property int someValue: ExampleApi.MyApi.someProperty
   }
   \endqml

   \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML}
*/

/*!
    \fn template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create)
    \relates QQmlEngine

    The form of this template function is:

    \code
    template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)
    \endcode

    This returns the attached object instance that has been attached to the specified
    \a attachee by the attaching type \e T.

    If \a create is true and type \e T is a valid attaching type, this creates and returns a new
    attached object instance.

    Returns \nullptr if type \e T is not a valid attaching type, or if \a create is false and no
    attachment object instance has previously been created for \a attachee.

    \sa QML_ATTACHED(), {Providing Attached Properties}
*/

/*!
    \fn QObject *qmlExtendedObject(const QObject *base)
    \relates QQmlEngine

    This function returns the extension object that belongs to \a base, if there is any.
    Otherwise it returns \c nullptr.

    \sa QML_EXTENDED
*/

/*!
   \fn template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject*(QQmlEngine *, QJSEngine *)> callback)
   \relates QQmlEngine

   This function may be used to register a singleton type provider \a callback in a particular \a uri
   and \a typeName with a version specified in \a versionMajor and \a versionMinor.

   Installing a singleton type into a uri allows developers to provide arbitrary functionality
   (methods and properties) to clients without requiring individual instances ot the type to be
   instantiated by the client.

   A singleton type may be either a QObject or a QJSValue.
   This function should be used to register a singleton type provider function which returns a QObject
   of the given type T as a singleton type.

   A QObject singleton type may be referenced via the type name with which it was registered, and this
   typename may be used as the target in a \l Connections type or otherwise used as any other type id would.
   One exception to this is that a QObject singleton type property may not be aliased.

   \b{NOTE:} A QObject singleton type instance returned from a singleton type provider is owned by
   the QML engine unless the object has explicit QQmlEngine::CppOwnership flag set.

   Usage:
   \code
   // First, define your QObject which provides the functionality.
   class SingletonTypeExample : public QObject
   {
       Q_OBJECT
       Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

   public:
       SingletonTypeExample(QObject *parent = nullptr)
           : QObject(parent), m_someProperty(0)
       {
       }

       ~SingletonTypeExample() {}

       Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }

       int someProperty() const { return m_someProperty; }
       void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }

   signals:
       void somePropertyChanged(int newValue);

   private:
       int m_someProperty;
   };

   // Second, define the singleton type provider function (callback).
   static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
   {
       Q_UNUSED(engine)
       Q_UNUSED(scriptEngine)

       SingletonTypeExample *example = new SingletonTypeExample();
       return example;
   }

   // Third, register the singleton type provider with QML by calling this function in an initialization function.
   qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);
   \endcode

   Alternatively, you can use a C++11 lambda:

   \code
   qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * {
       Q_UNUSED(engine)
       Q_UNUSED(scriptEngine)

       SingletonTypeExample *example = new SingletonTypeExample();
       return example;
   });
   \endcode

   In order to use the registered singleton type in QML, you must import the singleton type.
   \qml
   import QtQuick 2.0
   import Qt.example.qobjectSingleton 1.0
   Item {
       id: root
       property int someValue: MyApi.someProperty

       Component.onCompleted: {
           someValue = MyApi.doSomething()
       }
   }
   \endqml

   \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML}
*/

/*!
   \fn int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
   \relates QQmlEngine

   This function may be used to register a singleton type with the name \a qmlName, in the library imported from \a uri having
   the version number composed from \a versionMajor and \a versionMinor. The type is defined by the QML file located at \a url.
   The url must be an absolute URL, i.e. url.isRelative() == false.

   In addition the type's QML file must have pragma Singleton statement among its import statements.

   A singleton type may be referenced via the type name with which it was registered, and this typename may be used as the
   target in a \l Connections type or otherwise used as any other type id would. One exception to this is that a singleton
   type property may not be aliased (because the singleton type name does not identify an object within the same component
   as any other item).

   Usage:
   \qml
   // First, define your QML singleton type which provides the functionality.
   pragma Singleton
   import QtQuick 2.0
   Item {
       property int testProp1: 125
   }
   \endqml

   \code
   // Second, register the QML singleton type by calling this function in an initialization function.
   qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");
   \endcode

   In order to use the registered singleton type in QML, you must import the singleton type.
   \qml
   import QtQuick 2.0
   import Qt.example.qobjectSingleton 1.0
   Item {
       id: root
       property int someValue: RegisteredSingleton.testProp1
   }
   \endqml

   It is also possible to have QML singleton types registered without using the qmlRegisterSingletonType function.
   That can be done by adding a pragma Singleton statement among the imports of the type's QML file. In addition
   the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML
   files using the singleton.

   \sa QML_SINGLETON
*/

/*!
   \fn int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)
   \relates QQmlEngine
   \since 5.14

   This function is used to register a singleton object \a cppObject, with a
   particular \a uri and \a typeName. Its version is a combination of \a
   versionMajor and \a versionMinor.

   Installing a singleton type into a URI allows you to provide arbitrary
   functionality (methods and properties) to QML code without requiring
   individual instances of the type to be instantiated by the client.

   Use this function to register an object of the given type T as a singleton
   type.

   A QObject singleton type may be referenced via the type name with which it
   was registered; in turn this type name may be used as the target in a \l
   Connections type, or like any other type ID. However, there's one
   exception: a QObject singleton type property can't be aliased because the
   singleton type name does not identify an object within the same component
   as any other item.

   \note \a cppObject must outlive the QML engine in which it is used.
   Moreover, \cppObject must have the same thread affinity as the engine. If
   you want separate singleton instances for multiple engines, you need to use
   \l {qmlRegisterSingletonType}.  See \l{Threads and QObjects} for more
   information about thread safety.

   \b{NOTE:} qmlRegisterSingleton can only be used when all types of that module are registered procedurally.

    Usage:
    \code
    // First, define your QObject which provides the functionality.
    class SingletonTypeExample : public QObject
    {
        Q_OBJECT
        Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)

    public:
        explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {}

        Q_INVOKABLE int doSomething()
        {
            setSomeProperty(5);
            return m_someProperty;
        }

        int someProperty() const { return m_someProperty; }
        void setSomeProperty(int val) {
            if (m_someProperty != val) {
                m_someProperty = val;
                emit somePropertyChanged(val);
            }
        }

    signals:
        void somePropertyChanged(int newValue);

    private:
        int m_someProperty = 0;
    };
    \endcode

    \code
    // Second, create an instance of the object

    // allocate example before the engine to ensure that it outlives it
    QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample);
    QQmlEngine engine;

    // Third, register the singleton type provider with QML by calling this
    // function in an initialization function.
    qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());
    \endcode


    In order to use the registered singleton type in QML, you must import the
    URI with the corresponding version.
    \qml
    import QtQuick 2.0
    import Qt.example.qobjectSingleton 1.0
    Item {
        id: root
        property int someValue: MyApi.someProperty

        Component.onCompleted: {
            console.log(MyApi.doSomething())
        }
    }
    \endqml

   \sa QML_SINGLETON, qmlRegisterSingletonType
 */

/*!
  \fn int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName);
  \relates QQmlEngine

  This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the
  version number composed from \a versionMajor and \a versionMinor. The type is defined by the QML file located at \a url. The
  url must be an absolute URL, i.e. url.isRelative() == false.

  Normally QML files can be loaded as types directly from other QML files, or using a qmldir file. This function allows
  registration of files to types from C++ code, such as when the type mapping needs to be procedurally determined at startup.

  Returns -1 if the registration was not successful.
*/

/*!
  \fn bool qmlProtectModule(const char* uri, int majVersion);
  \relates QQmlEngine

  This function protects a module from further modification. This can be used
  to prevent other plugins from injecting types into your module. It can also
  be a performance improvement, as it allows the engine to skip checking for
  the possibility of new types or plugins when this import is reached.

  Once qmlProtectModule has been called, a QML engine will not search for a new
  \c qmldir file to load the module anymore. It will re-use any \c qmldir files
  it has loaded before, though. Therefore, types present at this point continue
  to work. Mind that different QML engines may load different modules. The
  module protection, however, is global and affects all engines. The overhead
  of locating \c qmldir files and loading plugins may be noticeable with slow file
  systems. Therefore, protecting a module once you are sure you won't need to
  load it anymore can be a good optimization. Mind also that the module lock
  not only affects plugins but also any other qmldir directives, like \c import
  or \c prefer, as well as any composite types or scripts declared in a \c qmldir
  file.

  In addition, after this function is called, any attempt to register C++ types
  into this uri, major version combination will lead to a runtime error.

  Returns true if the module with \a uri as a \l{Identified Modules}
  {module identifier} and \a majVersion as a major version number was found
  and locked, otherwise returns false. The module must contain exported types
  in order to be found.
*/

/*!
  \since 5.9
  \fn void qmlRegisterModule(const char* uri, int versionMajor, int versionMinor);
  \relates QQmlEngine

  This function registers a module in a particular \a uri with a version specified
  in \a versionMajor and \a versionMinor.

  This can be used to make a certain module version available, even if no types
  are registered for that version. This is particularly useful for keeping the
  versions of related modules in sync.
*/

/*!
  \since 5.12
  \fn int qmlTypeId(const char* uri, int versionMajor, int versionMinor, const char *qmlName);
  \relates QQmlEngine

  Returns the QML type id of a type that was registered with the
  name \a qmlName in a particular \a uri and a version specified in \a
  versionMajor and \a versionMinor.

  This function returns the same value as the QML type registration functions
  such as qmlRegisterType() and qmlRegisterSingletonType().

  If \a qmlName, \a uri and \a versionMajor match a registered type, but the
  specified minor version in \a versionMinor is higher, then the id of the type
  with the closest minor version is returned.

  Returns -1 if no matching type was found or one of the given parameters
  was invalid.

  \sa QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), qmlRegisterSingletonType()
*/

/*!
  \macro QML_VALUE_TYPE(name)
  \relates QQmlEngine

  Declares the enclosing type or namespace to be available in QML, using \a name
  as the name. The type has to be a value type and the name has to be lower case.

  \code
  class MyValueType
  {
      Q_GADGET
      QML_VALUE_TYPE(myValueType)

      // ...
  };
  \endcode

  \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT
*/

/*!
  \macro QML_CONSTRUCTIBLE_VALUE
  \since 6.5
  \relates QQmlEngine

  Marks the surrounding value type as constructible. That is, any \l Q_INVOKABLE
  constructors of the type that take exactly one argument can be used when
  assigning a JavaScript value to a property of this type.

  You can declare a constructible value type as follows:

  \code
  class MyValueType
  {
      Q_GADGET
      QML_VALUE_TYPE(myValueType)
      QML_CONSTRUCTIBLE_VALUE
  public:
      Q_INVOKABLE MyValueType(double d);

      // ...
  };
  \endcode

  With the above type, the following QML code will produce a \c MyValueType
  value using the given constructor and assign it to the property.

  \qml
  QtObject {
      property myValueType v: 5.4
  }
  \endqml

  You can also construct lists of values this way:

  \qml
  QtObject {
      property list<myValueType> v: [5.4, 4.5, 3.3]
  }
  \endqml

  If you make value types \l{ValueTypeBehavior}{addressable}, you can
  use such a type in a \l{Type annotations and assertions}{type assertion}
  to explicitly construct it:

  \qml
  pragma ValueTypeBehavior: Addressable

  QtObject {
      function process(d: real) {
          let v = d as myValueType;
          // v is a myValueType now, not a number
      }
  }
  \endqml

  \sa QML_VALUE_TYPE
*/

/*!
  \macro QML_STRUCTURED_VALUE
  \since 6.5
  \relates QQmlEngine

  Marks the surrounding value type as structured. Structured value types can
  and will preferably be constructed property-by-property from a JavaScript
  object. A structured value type, however is always \l QML_CONSTRUCTIBLE_VALUE,
  too. This means, you can still provide \l Q_INVOKABLE constructors in order to
  handle construction from primitive types.

  You can declare a structured value type as follows:

  \code
  class MyValueType
  {
      Q_GADGET
      QML_VALUE_TYPE(myValueType)
      QML_STRUCTURED_VALUE
      Q_PROPERTY(double d READ d WRITE setD)
      Q_PROPERTY(string e READ e WRITE setE)

      // ...
  };
  \endcode

  Then you can populate a property of this type as follows:

  \qml
  QtObject {
      property myValueType v: ({d: 4.4, e: "a string"})
  }
  \endqml

  The extra parentheses are necessary to disambiguate the JavaScript object
  from what might be interpreted as a JavaScript code block.

  You can also construct lists of values this way:

  \qml
  QtObject {
      property list<myValueType> v: [
          {d: 4.4, e: "a string"},
          {d: 7.1, e: "another string"}
      ]
  }
  \endqml

  If you make value types \l{ValueTypeBehavior}{addressable}, you can
  use such a type in a \l{Type annotations and assertions}{type assertion}
  to explicitly construct it:

  \qml
  pragma ValueTypeBehavior: Addressable

  QtObject {
      function process(d: real) {
          let v = {d: d, e: objectName} as myValueType;
          // v is a myValueType now
      }
  }
  \endqml

  \sa QML_VALUE_TYPE QML_CONSTRUCTIBLE_VALUE
*/