/**************************************************************************** ** ** Copyright (C) 2017 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** 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 The Qt Company. For licensing terms ** and conditions see https://www.qt.io/terms-conditions. For further ** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html. ** $QT_END_LICENSE$ ** ****************************************************************************/ /*! \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. \code class Slider : public QObject { Q_OBJECT QML_ELEMENT ... } \endcode You can use the build system to register the type in the type namespace \e {com.mycompany.qmlcomponents} with major version \c 1 by specifying the following in your project file: \badcode CONFIG += qmltypes QML_IMPORT_NAME = com.mycompany.qmlcomponents QML_IMPORT_MAJOR_VERSION = 1 \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 { // ... } \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. \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. \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT(), Q_REVISION(), QML_ADDED_IN_MINOR_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 as property type, but when passed from C++, it is recognized. \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(). For such types, \l QML_UNCREATABLE() can be used to provide a custom error message. 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 initially inaccessible. \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlRegisterSingletonInstance(). */ /*! \macro QML_ADDED_IN_MINOR_VERSION(VERSION) \relates QQmlEngine 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 tags 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_ELEMENT, QML_NAMED_ELEMENT() */ /*! \macro QML_REMOVED_IN_MINOR_VERSION(VERSION) \relates QQmlEngine 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_MINOR_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_ELEMENT, QML_NAMED_ELEMENT() */ /*! \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. \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. \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. \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_MINOR_VERSION(), \l QML_REMOVED_IN_MINOR_VERSION(), \l QML_ATTACHED(), \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(). \b{NOTE:} You may want to use \l QML_NAMED_ELEMENT() instead of \l QML_ELEMENT due to the fact that the element will be named like the struct it is contained in, not the foreign type. See \l {Extending QML - Extension Objects Example} for an example. \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_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. \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_FOREIGN() */ /*! \macro QML_DECLARE_TYPE() \relates QQmlEngine Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty) */ /*! \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 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 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); template 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("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 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 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 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 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 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_ENUMS(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("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 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("App", 1, 0, "Foo"); qmlRegisterAnonymousType("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, QJSValue (*callback)(QQmlEngine *, QJSEngine *)) \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 QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create) \relates QQmlEngine The form of this template function is: \code template 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 0 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 int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *(*callback)(QQmlEngine *, QJSEngine *)) \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 = 0) : 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("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider); \endcode Alternatively, you can use a C++11 lambda: \code qmlRegisterSingletonType("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 char *uri, int versionMajor, int versionMinor, const char *typeName, std::function callback) \relates QQmlEngine \overload qmlRegisterSingletonType \since 5.14 */ /*! \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 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 having types registered into it. 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. The performance benefit is primarily seen when registering application specific types from within the application instead of through a plugin. Using qmlProtectModule allows the engine to skip checking for a plugin when that uri is imported, which can be noticeable with slow file systems. After this function is called, any attempt to register C++ types into this uri, major version combination will lead to a runtime error. Call this after you have registered all of your types with the engine. 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() */