1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
8 Declares the enclosing type or namespace to be available in QML, using its
9 class or namespace name as the QML element name.
11 For example, this makes the C++ class \c Slider available as a QML type
12 named \c Slider. All its properties, invokable methods and enums are exposed.
15 class Slider : public QObject
19 Q_PROPERTY(int value READ value WRITE setValue NOTIFY valueChanged FINAL)
27 Q_INVOKABLE void slide(Slippiness slippiness);
33 You can use the build system to register the type in the type namespace
34 \e {com.mycompany.qmlcomponents} with major version \c 1.
35 For qmake, specify the following in your project file:
39 QML_IMPORT_NAME = com.mycompany.qmlcomponents
40 QML_IMPORT_MAJOR_VERSION = 1
43 With CMake, you pass the URI and version to qt_add_qml_module
46 qt6_add_qml_module(myapp
47 URI com.mycompany.qmlcomponents
52 Once registered, the type can be used in QML by importing the
53 same type namespace and version number:
56 import com.mycompany.qmlcomponents 1.0
60 Component.onCompleted: slide(Slider.Icy)
66 You can also make namespaces tagged with Q_NAMESPACE available this way, in
67 order to expose any enums tagged with Q_ENUM_NS they contain:
70 namespace MyNamespace {
82 In QML, you can then use the enums:
85 Component.onCompleted: console.log(MyNamespace.Key2)
88 \b{NOTE:} When classes have the same name but are located in different namespaces using
89 \l QML_ELEMENT on both of them will cause a conflict.
90 Make sure to use \l QML_NAMED_ELEMENT() for one of them instead.
92 \include {qualified-class-name.qdocinc} {class name must be qualified}
94 \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT(),
95 Q_REVISION(), QML_ADDED_IN_VERSION()
99 \macro QML_NAMED_ELEMENT(name)
102 Declares the enclosing type or namespace to be available in QML, using \a name
103 as the element name. Otherwise behaves the same as QML_ELEMENT.
106 class SqlEventDatabase : public QObject
109 QML_NAMED_ELEMENT(EventDatabase)
115 \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_ELEMENT
122 Declares the enclosing type to be available, but anonymous in QML. The type
123 cannot be created or used to declare properties in QML, but when passed from
124 C++, it is recognized. In QML, you can use properties of this type if they
127 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_INTERFACE
134 This macro registers the enclosing C++ type in the QML system as an interface.
136 Types registered as an interface in QML should also declare themselves as an
137 interface with the \l {The Meta-Object System}{meta object system}. For
145 virtual ~FooInterface();
146 virtual void doSomething() = 0;
149 Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")
152 When registered with QML in this way, they can be used as property types:
154 Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)
156 When you assign a \l QObject sub-class to this property, the QML engine does
157 the interface cast to \c FooInterface* automatically.
159 Interface types are implicitly anonymous and uncreatable in QML.
161 \b{NOTE:} When inheriting from types using QML_INTERFACE, use \l QML_IMPLEMENTS_INTERFACES
162 instead of \l Q_INTERFACES.
164 \sa QML_IMPLEMENTS_INTERFACES(), QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_ANONYMOUS
168 \macro QML_IMPLEMENTS_INTERFACES(interfaces)
171 This macro tells Qt which QML \a interfaces the class implements.
172 This macro should only be used for interfacing with classes using \l QML_INTERFACE, use \l Q_INTERFACES otherwise.
173 It's required in order for declarative registration via \l QML_ELEMENT to
176 \sa QML_INTERFACE, Q_INTERFACES
180 \macro QML_UNCREATABLE(reason)
183 Declares that the enclosing type shall not be creatable from QML. This takes
184 effect if the type is available in QML, by having a \l QML_ELEMENT or
185 \l QML_NAMED_ELEMENT() macro. The \a reason will be emitted as error message if an
186 attempt to create the type from QML is detected.
188 Some QML types are implicitly uncreatable, in particular types exposed with
189 \l QML_ANONYMOUS or namespaces exposed with \l QML_ELEMENT or
190 \l QML_NAMED_ELEMENT().
192 Since Qt 6.0 you can use "" instead of a reason to use a standard message
195 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_ANONYMOUS
202 Declares the enclosing type to be a singleton in QML. This only takes effect
203 if the type is a \l Q_OBJECT and is available in QML (by having a
204 \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro). By default, each QQmlEngine
205 will try to create a singleton instance using either the type's default
206 constructor or a static factory function of the signature
207 \c{T *create(QQmlEngine *, QJSEngine *)} when the type is first accessed.
208 If both do exist and are accessible, the default constructor is preferred.
209 If there is no default constructor and no factory function the singleton is
210 inaccessible. The QML engine generally assumes ownership of the singleton and
211 will delete it when the engine itself is destroyed. You can prevent this by
212 calling QJSEngine::setObjectOwnership() on the singleton.
214 In order to declare a default-constructible class as singleton, all you have
215 to do is add \l QML_SINGLETON:
218 class MySingleton : public QObject
225 // members, Q_INVOKABLE functions, etc.
229 If the singleton class is not default-constructible, but you can modify it,
230 you can add a factory function to it, in order to make it accessible:
233 class MySingleton : public QObject
241 static MySingleton *create(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
243 MySingleton *result = nullptr;
244 // Create the object using some custom constructor or factory.
245 // The QML engine will assume ownership and delete it, eventually.
249 // members, Q_INVOKABLE functions, etc
253 If you cannot modify the class and it does not have a default constructor or a
254 suitable factory function, you can provide a \l QML_FOREIGN wrapper to define
255 the factory function:
258 struct SingletonForeign
261 QML_FOREIGN(MySingleton)
263 QML_NAMED_ELEMENT(MySingleton)
266 static MySingleton *create(QQmlEngine *, QJSEngine *engine)
268 MySingleton *result = nullptr;
269 // Create the instance using some custom constructor or factory.
270 // The QML engine will assume ownership and delete it, eventually.
276 Finally, if you want to provide one specific singleton object, the creation of
277 which you cannot control, you can return that from a factory function. This is
278 a replacement for the \l qmlRegisterSingletonInstance function.
282 qmlRegisterSingletonInstance("MyModule", 1, 0, "MySingleton", myObject);
285 with myObject being of type \c{MySingleton *}, you can do the following
289 struct SingletonForeign
292 QML_FOREIGN(MySingleton)
294 QML_NAMED_ELEMENT(MySingleton)
297 // Initialize this using myObject where you would previously
298 // call qmlRegisterSingletonInstance().
299 inline static MySingleton *s_singletonInstance = nullptr;
301 static MySingleton *create(QQmlEngine *, QJSEngine *engine)
303 // The instance has to exist before it is used. We cannot replace it.
304 Q_ASSERT(s_singletonInstance);
306 // The engine has to have the same thread affinity as the singleton.
307 Q_ASSERT(engine->thread() == s_singletonInstance->thread());
309 // There can only be one engine accessing the singleton.
311 Q_ASSERT(engine == s_engine);
315 // Explicitly specify C++ ownership so that the engine doesn't delete
317 QJSEngine::setObjectOwnership(s_singletonInstance,
318 QJSEngine::CppOwnership);
319 return s_singletonInstance;
323 inline static QJSEngine *s_engine = nullptr;
327 This way, the pre-existing class \c MySingleton is declared to be a QML
328 singleton, called \c MySingleton. You can specify an instance for it any time
329 before it is used by setting the \c s_singletonInstance member. None of this
330 requires modification of \c MySingleton itself.
332 \note This pattern doesn't work if either the singleton is accessed by
333 multiple QML engines, or if the QML engine accessing it has a different thread
334 affinity than the singleton object itself. As shown above, you can check the
335 parameters to the \c create() method for identity and thread affinity of the
336 engine in order to assert on that.
338 \sa QML_ELEMENT, QML_NAMED_ELEMENT(),
339 qmlRegisterSingletonInstance(), QQmlEngine::singletonInstance(), {Singletons in QML}
343 \macro QML_ADDED_IN_VERSION(MAJOR, MINOR)
346 Declares that the enclosing type or namespace was added in the specified
347 \a{MAJOR}.\a{MINOR} version. The version is assumed to be in line with any
348 revisions given by \l Q_REVISION() macros on methods, slots, or signals,
349 and any REVISION() attributes on properties declared with \l Q_PROPERTY().
351 \l QML_ADDED_IN_VERSION() only takes effect if the type or namespace is
352 available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
353 \l QML_ANONYMOUS, or \l QML_INTERFACE macro.
355 If the QML module the type belongs to is imported with a lower version than
356 the one determined this way, the QML type is invisible.
358 \sa QML_ELEMENT, QML_NAMED_ELEMENT
362 \macro QML_ADDED_IN_MINOR_VERSION(VERSION)
364 \deprecated [6.7] Use QML_ADDED_IN_VERSION and specify the full version
366 Declares that the enclosing type or namespace was added in the specified minor
367 \a VERSION, relative to the module major version. The minor version is assumed
368 to be in line with any revisions given by \l Q_REVISION() macros on methods,
369 slots, or signals, and any REVISION() attributes on properties declared with
372 \l QML_ADDED_IN_MINOR_VERSION() only takes effect if the type or namespace is
373 available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
374 \l QML_ANONYMOUS, or \l QML_INTERFACE macro.
376 If the QML module the type belongs to is imported with a lower version than
377 the one determined this way, the QML type is invisible.
379 \sa QML_ADDED_IN_VERSION, QML_ELEMENT, QML_NAMED_ELEMENT
383 \macro QML_REMOVED_IN_VERSION(MAJOR, MINOR)
386 Declares that the enclosing type or namespace was removed in the specified
387 \a{MAJOR}.\a{MINOR} version. This is primarily useful when replacing the
388 implementation of a QML type. If a corresponding \l QML_ADDED_IN_VERSION()
389 is present on a different type or namespace of the same QML name, then the
390 removed type is used when importing versions of the module lower than
391 \a{MAJOR}.\a{MINOR}, and the added type is used when importing
392 versions of the module greater or equal \a{MAJOR}.\a{MINOR}.
394 \l QML_REMOVED_IN_VERSION() only takes effect if type or namespace is
395 available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
396 \l QML_ANONYMOUS, or \l QML_INTERFACE macro.
398 \sa QML_ELEMENT, QML_NAMED_ELEMENT
402 \macro QML_REMOVED_IN_MINOR_VERSION(VERSION)
404 \deprecated [6.7] Use QML_REMOVED_IN_VERSION and specify the full version
406 Declares that the enclosing type or namespace was removed in the specified
407 minor \a VERSION, relative to the module major version. This is primarily
408 useful when replacing the implementation of a QML type. If a corresponding
409 \l QML_ADDED_IN_VERSION() is present on a different type or namespace of
410 the same QML name, then the removed type is used when importing versions of
411 the module lower than \a VERSION, and the added type is used when importing
412 versions of the module greater or equal \a VERSION.
414 \l QML_REMOVED_IN_MINOR_VERSION() only takes effect if type or namespace is
415 available in QML, by having a \l QML_ELEMENT, \l QML_NAMED_ELEMENT(),
416 \l QML_ANONYMOUS, or \l QML_INTERFACE macro.
418 \sa QML_REMOVED_IN_VERSION, QML_ELEMENT, QML_NAMED_ELEMENT
422 \macro QML_EXTRA_VERSION(MAJOR, MINOR)
425 Declare that the type should also be available in version \a{MAJOR}.\a{MINOR}.
426 This can be helpful if a type should be available in multiple major versions.
428 Types are automatically registered for:
430 \li The major version they were introduced in, see \l{QML_ADDED_IN_VERSION}.
431 \li Any major versions any their members were introduced in.
432 \li The current major version of their module, unless they were
433 \l{QML_REMOVED_IN_VERSION} before that.
436 Notably, they are not automatically registered in any \l{PAST_MAJOR_VERSIONS}
437 between the above. You can use QML_EXTRA_VERSION to manually register your
438 types in further major versions.
440 \note Keeping multiple \l{PAST_MAJOR_VERSIONS} around is computationally
443 \sa QML_ELEMENT, QML_ADDED_IN_VERSION
447 \macro QML_ATTACHED(ATTACHED_TYPE)
450 Declares that the enclosing type attaches \a ATTACHED_TYPE as an
451 \l {Attached Properties and Attached Signal Handlers}
452 {attached property} to other types. This takes effect if the type
453 is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro.
455 \include {qualified-class-name.qdocinc} {class name must be qualified}
457 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), qmlAttachedPropertiesObject(),
458 {Providing Attached Properties}
462 \macro QML_EXTENDED(EXTENDED_TYPE)
465 Declares that the enclosing type uses \a EXTENDED_TYPE as an extension to
466 provide further properties, methods, and enumerations in QML. This takes
467 effect if the type is exposed to QML using a \l QML_ELEMENT or
468 \l QML_NAMED_ELEMENT() macro.
470 \warning Members of \a EXTENDED_TYPE are implicitly treated as FINAL.
472 \include {qualified-class-name.qdocinc} {class name must be qualified}
474 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED_NAMESPACE(),
475 {Registering Extension Objects}
479 \macro QML_EXTENDED_NAMESPACE(EXTENDED_NAMESPACE)
482 Declares that the enclosing type uses \a EXTENDED_NAMESPACE as an extension to
483 provide further enumerations in QML. This takes effect if the type
484 is exposed to QML using a \l QML_ELEMENT or \l QML_NAMED_ELEMENT() macro.
485 The enumerations need to be exposed to the metaobject system for this to work.
487 For example, give the following C++ code
489 namespace MyNamespace {
491 enum MyEnum { MyEnumerator = 10 };
495 class QmlType : public QObject
499 QML_EXTENDED_NAMESPACE(MyNamespace)
503 we can access the enum in QML:
506 property int i: QmlType.MyEnumerator // i will be 10
510 \note EXTENDED_NAMESPACE can also be a QObject or QGadget; in that case - and in contrast to
511 QML_EXTENDED, which also exposes methods and properties - only its enumerations
514 \note \a EXTENDED_NAMESPACE must have a metaobject; i.e. it must either be a namespace which
515 contains the Q_NAMESPACE macro or a QObject/QGadget.
517 \include {qualified-class-name.qdocinc} {class name must be qualified}
519 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED(),
520 {Registering Extension Objects}, Q_ENUM, Q_ENUM_NS
524 \macro QML_FOREIGN(FOREIGN_TYPE)
527 Declares that any \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), \l QML_ANONYMOUS,
528 \l QML_INTERFACE, \l QML_UNCREATABLE(), \l QML_SINGLETON,
529 \l QML_ADDED_IN_VERSION(), \l QML_REMOVED_IN_VERSION(),
530 \l QML_ADDED_IN_MINOR_VERSION(), \l QML_REMOVED_IN_MINOR_VERSION(),
531 \l QML_EXTENDED(), or \l QML_EXTENDED_NAMESPACE() macros
532 in the enclosing C++ type do not apply to the enclosing type but instead to
533 \a FOREIGN_TYPE. The enclosing type still needs to be registered with the
534 \l {The Meta-Object System}{meta object system} using a \l Q_GADGET or
537 This is useful for registering types that cannot be amended to add the macros,
538 for example because they belong to 3rdparty libraries.
539 To register a namespace, see \l QML_FOREIGN_NAMESPACE().
541 \note You may want to use \l QML_NAMED_ELEMENT() instead of \l QML_ELEMENT.
542 With QML_ELEMENT, the element is named after the struct it is contained in,
543 not the foreign type. The \l {Foreign objects integration} chapter in
544 \l {Writing advanced QML Extensions with C++} demonstrates this.
546 \note QML_ATTACHED() can currently not be redirected like this. It has to be
547 specificed in the same type that implements qmlAttachedProperties().
549 \include {qualified-class-name.qdocinc} {class name must be qualified}
551 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_FOREIGN_NAMESPACE()
555 \macro QML_FOREIGN_NAMESPACE(FOREIGN_NAMESPACE)
558 Declares that any \l QML_ELEMENT, \l QML_NAMED_ELEMENT(), \l QML_ANONYMOUS,
559 \l QML_INTERFACE, \l QML_UNCREATABLE(), \l QML_SINGLETON,
560 \l QML_ADDED_IN_VERSION(), \l QML_REMOVED_IN_VERSION(),
561 \l QML_ADDED_IN_MINOR_VERSION(), or \l QML_REMOVED_IN_MINOR_VERSION()
562 macros in the enclosing C++ namespace do not apply to the enclosing type but
563 instead to \a FOREIGN_NAMESPACE. The enclosing namespace still needs to be
564 registered with the \l {The Meta-Object System}{meta object system} using a
565 \l Q_NAMESPACE macro.
567 This is useful for registering namespaces that cannot be amended to add the macros,
568 for example because they belong to 3rdparty libraries.
570 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_FOREIGN()
574 \macro QML_UNAVAILABLE
577 This macro declares the enclosing type to be unavailable in QML. It registers
578 an internal dummy type called \c QQmlTypeNotAvailable as \l QML_FOREIGN()
579 type, using any further QML macros you specify.
581 Normally, the types exported by a module should be fixed. However, if a C++
582 type is not available, you should at least "reserve" the QML type name, and
583 give the user of the unavailable type a meaningful error message.
588 #ifdef NO_GAMES_ALLOWED
592 QML_NAMED_ELEMENT(Game)
594 QML_UNCREATABLE("Get back to work, slacker!");
597 class MinehuntGame : public QObject
600 QML_NAMED_ELEMENT(Game)
606 This will cause any QML which attempts to use the "Game" type to produce an
610 fun.qml: Get back to work, slacker!
615 Using this technique, you only need a \l Q_GADGET struct to customize the error
616 message, not a full-blown \l QObject. Without \l QML_UNCREATABLE(),
617 \l QML_UNAVAILABLE still results in a more specific error message than the usual
618 "is not a type" for completely unknown types.
620 \include {qualified-class-name.qdocinc} {class name must be qualified}
622 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_FOREIGN()
626 \macro QML_SEQUENTIAL_CONTAINER(VALUE_TYPE)
629 This macro declares the enclosing or referenced type as a sequential container
630 managing a sequence of \a VALUE_TYPE elements. \a VALUE_TYPE can be an actual
631 \l{QML Value Types}{value type} or a pointer to an
632 \l{QML Object Types}{object type}. You will rarely be able to add this macro
633 to the actual container declaration since containers are usually templates.
634 You should use \l{QML_FOREIGN} to attach the type registration to a template
635 instantiation. Using this technique you can, for example, declare sequential
636 containers like this:
639 class IntDequeRegistration
642 QML_FOREIGN(std::deque<int>)
644 QML_SEQUENTIAL_CONTAINER(int)
648 After this, you can use the container like a JavaScript array in QML.
655 // 0: North, 1: East, 2: South, 3: West
656 Q_PROPERTY(std::deque<int> solution READ solution CONSTANT FINAL)
667 function showSolution() {
668 maze.solution.forEach([...])
673 \note For \l{QML Value Types} \l{QList} is automatically registered as
674 sequential container. For \l{QML Object Types} \l{QQmlListProperty} is.
675 You don't have to add these registrations.
677 \note You cannot currently give the container a custom name. Any argument
678 passed to \l{QML_NAMED_ELEMENT} is ignored. The automatically registered
679 sequential containers are available under the familiar \e{list<...>} names,
680 for example \e{list<QtObject>} or \e{list<font>}.
682 \include {qualified-class-name.qdocinc} {class name must be qualified}
684 \sa QML_ANONYMOUS, QML_FOREIGN()
688 \macro QML_DECLARE_TYPE()
691 Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty<TYPE>)
695 \macro QML_DECLARE_TYPEINFO(Type,Flags)
698 Declares additional properties of the given \a Type as described by the
701 Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which
702 declares that the \a Type supports \l {Attached Properties and Attached Signal Handlers}
703 {attached properties}. QML_DECLARE_TYPEINFO() is not necessary if \a Type contains the
708 \fn void qmlClearTypeRegistrations()
711 Clears all stored type registrations, such as those produced with \l qmlRegisterType().
713 Do not call this function while a QQmlEngine exists or behavior will be undefined.
714 Any existing QQmlEngines must be deleted before calling this function. This function
715 only affects the application global cache. Delete the QQmlEngine to clear all cached
716 data relating to that engine.
721 \fn template <typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
724 This template function registers the C++ type in the QML system with
725 the name \a qmlName, in the library imported from \a uri having the
726 version number composed from \a versionMajor and \a versionMinor.
728 Returns the QML type id.
730 There are two forms of this template function:
734 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
736 template<typename T, int metaObjectRevision>
737 int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName);
740 The former is the standard form which registers the type \e T as a new type.
741 The latter allows a particular revision of a class to be registered in
742 a specified version (see \l {Type Revisions and Versions}).
745 For example, this registers a C++ class \c MySliderItem as a QML type
746 named \c Slider for version 1.0 of a type namespace called
747 "com.mycompany.qmlcomponents":
750 qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider");
753 Once this is registered, the type can be used in QML by importing the
754 specified type namespace and version number:
757 import com.mycompany.qmlcomponents 1.0
764 Note that it's perfectly reasonable for a library to register types to older versions
765 than the actual version of the library. Indeed, it is normal for the new library to allow
766 QML written to previous versions to continue to work, even if more advanced versions of
767 some of its types are available.
769 \sa QML_ELEMENT, QML_NAMED_ELEMENT(),
770 {Choosing the Correct Integration Method Between C++ and QML}
774 \fn template<typename T, int metaObjectRevision> int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor)
777 This template function registers the specified revision of a C++ type in the QML system with
778 the library imported from \a uri having the version number composed
779 from \a versionMajor and \a versionMinor.
781 Returns the QML type id.
784 template<typename T, int metaObjectRevision>
785 int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor);
788 This function is typically used to register the revision of a base class to
789 use for the specified version of the type (see \l {Type Revisions and Versions}).
793 \fn template <typename T> int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
796 This template function registers the C++ type in the QML system with
797 the name \a qmlName, in the library imported from \a uri having the
798 version number composed from \a versionMajor and \a versionMinor.
800 While the type has a name and a type, it cannot be created, and the
801 given error \a message will result if creation is attempted.
803 This is useful where the type is only intended for providing attached properties or enum values.
805 Returns the QML type id.
807 \sa QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(),
808 {Choosing the Correct Integration Method Between C++ and QML}
812 \fn template <typename T, typename E> int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName)
815 This template function registers the C++ type and its extension object in the
816 QML system with the name \a qmlName in the library imported from \a uri having
817 version number composed from \a versionMajor and \a versionMinor. Properties
818 not available in the main type will be searched for in the extension object.
820 Returns the QML type id.
822 \sa QML_EXTENDED(), qmlRegisterType(), {Registering Extension Objects}
827 \fn template <typename T, typename E> int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason)
830 This template function registers the C++ type and its extension
831 in the QML system with the name \a qmlName in the library imported
832 from \a uri having version number composed from \a versionMajor and
835 While the type has a name and a type, it cannot be created. An error
836 message with the given \a reason is printed if the user attempts to
837 create an instance of this type.
839 This is useful where the type is only intended for providing attached
840 properties, enum values or an abstract base class with its extension.
842 Returns the QML type id.
844 \sa QML_EXTENDED(), QML_UNCREATABLE(), qmlRegisterUncreatableType()
848 \fn static inline int qmlRegisterUncreatableMetaObject(const QMetaObject &staticMetaObject, const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason)
852 This function registers the \a staticMetaObject and its extension
853 in the QML system with the name \a qmlName in the library imported
854 from \a uri having version number composed from \a versionMajor and
857 An instance of the meta object cannot be created. An error message with
858 the given \a reason is printed if the user attempts to create it.
860 This function is useful for registering Q_NAMESPACE namespaces.
862 Returns the QML type id.
867 namespace MyNamespace {
877 qmlRegisterUncreatableMetaObject(MyNamespace::staticMetaObject, "io.qt", 1, 0, "MyNamespace", "Access to enums & flags only");
880 On the QML side, you can now use the registered enums:
882 Component.onCompleted: console.log(MyNamespace.Key2)
885 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE()
889 \fn int qmlRegisterCustomExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, QQmlCustomParser *parser)
893 This template function registers the C++ type and its extension
894 in the QML system with the name \a qmlName in the library imported
895 from \a uri having version number composed from \a versionMajor and
896 \a versionMinor. Properties from the C++ type or its extension that
897 cannot be resolved directly by the QML system will be resolved using
898 the \a parser provided.
900 Returns the QML type id.
902 \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED()
906 \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message)
909 This function registers a type in the QML system with the name \a qmlName, in the type namespace imported from \a uri having the
910 version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type
911 will produce the given error \a message.
913 Normally, the types exported by a plugin should be fixed. However, if a C++ type is not available, you should
914 at least "reserve" the QML type name, and give the user of the unavailable type a meaningful error message.
916 Returns the QML type id.
921 #ifdef NO_GAMES_ALLOWED
922 qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!");
924 qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game");
928 This will cause any QML which imports the "MinehuntCore" type namespace and attempts to use the type to produce an error message:
930 fun.qml: Get back to work, slacker!
935 Without this, a generic "Game is not a type" message would be given.
937 \sa QML_UNAVAILABLE, qmlRegisterUncreatableType(),
938 {Choosing the Correct Integration Method Between C++ and QML}
942 \fn template <typename T> int qmlRegisterAnonymousType(const char *uri, int versionMajor)
945 This template function registers the C++ type in the QML system as an anonymous type. The
946 resulting QML type does not have a name. Therefore, instances of this type cannot be created from
947 the QML system. You can, however, access instances of the type when they are exposed as properties
950 Use this function when the type will not be referenced by name, specifically for C++ types that
951 are used on the left-hand side of a property binding. To indicate to which module the type belongs
952 use \a uri and \a versionMajor.
954 For example, consider the following two classes:
957 class Bar : public QObject
960 Q_PROPERTY(QString baz READ baz WRITE setBaz NOTIFY bazChanged)
965 QString baz() const { return mBaz; }
967 void setBaz(const QString &baz)
983 class Foo : public QObject
986 Q_PROPERTY(Bar *bar READ bar CONSTANT FINAL)
991 Bar *bar() { return &mBar; }
998 In QML, we assign a string to the \c baz property of \c bar:
1003 Component.onCompleted: print(bar.baz)
1007 For the QML engine to know that the \c Bar type has a \c baz property,
1008 we have to make \c Bar known:
1011 qmlRegisterType<Foo>("App", 1, 0, "Foo");
1012 qmlRegisterAnonymousType<Bar>("App", 1);
1015 As the \c Foo type is instantiated in QML, it must be registered
1016 with the version of \l qmlRegisterType() that takes an element name.
1018 Returns the QML type id.
1021 \sa QML_ANONYMOUS, {Choosing the Correct Integration Method Between C++ and QML}
1025 \fn int qmlRegisterInterface(const char *typeName)
1028 This template function registers the C++ type in the QML system
1029 under the name \a typeName.
1031 Types registered as an interface with the engine should also
1032 declare themselves as an interface with the
1033 \l {The Meta-Object System}{meta object system}. For example:
1039 virtual ~FooInterface();
1040 virtual void doSomething() = 0;
1043 Q_DECLARE_INTERFACE(FooInterface, "org.foo.FooInterface")
1046 When registered with the QML engine in this way, they can be used as
1049 Q_PROPERTY(FooInterface *foo READ foo WRITE setFoo)
1051 When you assign a \l QObject sub-class to this property, the QML engine does
1052 the interface cast to \c FooInterface* automatically.
1054 Returns the QML type id.
1060 \fn int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QJSValue(QQmlEngine *, QJSEngine *)> callback)
1063 This function may be used to register a singleton type provider \a callback in a particular \a uri
1064 and \a typeName with a version specified in \a versionMajor and \a versionMinor.
1066 Installing a singleton type allows developers to provide arbitrary functionality
1067 (methods and properties) to a client without requiring individual instances of the type to
1068 be instantiated by the client.
1070 A singleton type may be either a QObject or a QJSValue.
1071 This function should be used to register a singleton type provider function which returns a QJSValue as a singleton type.
1073 \b{NOTE:} QJSValue singleton type properties will \b{not} trigger binding re-evaluation if changed.
1077 // First, define the singleton type provider function (callback).
1078 static QJSValue example_qjsvalue_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
1082 static int seedValue = 5;
1083 QJSValue example = scriptEngine->newObject();
1084 example.setProperty("someProperty", seedValue++);
1088 // Second, register the singleton type provider with QML by calling this function in an initialization function.
1089 qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", example_qjsvalue_singletontype_provider);
1092 Alternatively, you can use a C++11 lambda:
1095 qmlRegisterSingletonType("Qt.example.qjsvalueApi", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QJSValue {
1098 static int seedValue = 5;
1099 QJSValue example = scriptEngine->newObject();
1100 example.setProperty("someProperty", seedValue++);
1105 In order to use the registered singleton type in QML, you must import the singleton type.
1108 import Qt.example.qjsvalueApi 1.0 as ExampleApi
1111 property int someValue: ExampleApi.MyApi.someProperty
1115 \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML}
1119 \fn template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create)
1122 The form of this template function is:
1125 template<typename T> QObject *qmlAttachedPropertiesObject(const QObject *attachee, bool create = true)
1128 This returns the attached object instance that has been attached to the specified
1129 \a attachee by the attaching type \e T.
1131 If \a create is true and type \e T is a valid attaching type, this creates and returns a new
1132 attached object instance.
1134 Returns \nullptr if type \e T is not a valid attaching type, or if \a create is false and no
1135 attachment object instance has previously been created for \a attachee.
1137 \sa QML_ATTACHED(), {Providing Attached Properties}
1141 \fn QObject *qmlExtendedObject(const QObject *base)
1144 This function returns the extension object that belongs to \a base, if there is any.
1145 Otherwise it returns \c nullptr.
1151 \fn template <typename T> int qmlRegisterSingletonType(const char *uri, int versionMajor, int versionMinor, const char *typeName, std::function<QObject*(QQmlEngine *, QJSEngine *)> callback)
1154 This function may be used to register a singleton type provider \a callback in a particular \a uri
1155 and \a typeName with a version specified in \a versionMajor and \a versionMinor.
1157 Installing a singleton type into a uri allows developers to provide arbitrary functionality
1158 (methods and properties) to clients without requiring individual instances ot the type to be
1159 instantiated by the client.
1161 A singleton type may be either a QObject or a QJSValue.
1162 This function should be used to register a singleton type provider function which returns a QObject
1163 of the given type T as a singleton type.
1165 A QObject singleton type may be referenced via the type name with which it was registered, and this
1166 typename may be used as the target in a \l Connections type or otherwise used as any other type id would.
1167 One exception to this is that a QObject singleton type property may not be aliased.
1169 \b{NOTE:} A QObject singleton type instance returned from a singleton type provider is owned by
1170 the QML engine unless the object has explicit QQmlEngine::CppOwnership flag set.
1174 // First, define your QObject which provides the functionality.
1175 class SingletonTypeExample : public QObject
1178 Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)
1181 SingletonTypeExample(QObject *parent = nullptr)
1182 : QObject(parent), m_someProperty(0)
1186 ~SingletonTypeExample() {}
1188 Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; }
1190 int someProperty() const { return m_someProperty; }
1191 void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); }
1194 void somePropertyChanged(int newValue);
1200 // Second, define the singleton type provider function (callback).
1201 static QObject *example_qobject_singletontype_provider(QQmlEngine *engine, QJSEngine *scriptEngine)
1204 Q_UNUSED(scriptEngine)
1206 SingletonTypeExample *example = new SingletonTypeExample();
1210 // Third, register the singleton type provider with QML by calling this function in an initialization function.
1211 qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", example_qobject_singletontype_provider);
1214 Alternatively, you can use a C++11 lambda:
1217 qmlRegisterSingletonType<SingletonTypeExample>("Qt.example.qobjectSingleton", 1, 0, "MyApi", [](QQmlEngine *engine, QJSEngine *scriptEngine) -> QObject * {
1219 Q_UNUSED(scriptEngine)
1221 SingletonTypeExample *example = new SingletonTypeExample();
1226 In order to use the registered singleton type in QML, you must import the singleton type.
1229 import Qt.example.qobjectSingleton 1.0
1232 property int someValue: MyApi.someProperty
1234 Component.onCompleted: {
1235 someValue = MyApi.doSomething()
1240 \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML}
1244 \fn int qmlRegisterSingletonType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName)
1247 This function may be used to register a singleton type with the name \a qmlName, in the library imported from \a uri having
1248 the version number composed from \a versionMajor and \a versionMinor. The type is defined by the QML file located at \a url.
1249 The url must be an absolute URL, i.e. url.isRelative() == false.
1251 In addition the type's QML file must have pragma Singleton statement among its import statements.
1253 A singleton type may be referenced via the type name with which it was registered, and this typename may be used as the
1254 target in a \l Connections type or otherwise used as any other type id would. One exception to this is that a singleton
1255 type property may not be aliased (because the singleton type name does not identify an object within the same component
1260 // First, define your QML singleton type which provides the functionality.
1264 property int testProp1: 125
1269 // Second, register the QML singleton type by calling this function in an initialization function.
1270 qmlRegisterSingletonType(QUrl("file:///absolute/path/SingletonType.qml"), "Qt.example.qobjectSingleton", 1, 0, "RegisteredSingleton");
1273 In order to use the registered singleton type in QML, you must import the singleton type.
1276 import Qt.example.qobjectSingleton 1.0
1279 property int someValue: RegisteredSingleton.testProp1
1283 It is also possible to have QML singleton types registered without using the qmlRegisterSingletonType function.
1284 That can be done by adding a pragma Singleton statement among the imports of the type's QML file. In addition
1285 the type must be defined in a qmldir file with a singleton keyword and the qmldir must be imported by the QML
1286 files using the singleton.
1292 \fn int qmlRegisterSingletonInstance(const char *uri, int versionMajor, int versionMinor, const char *typeName, QObject *cppObject)
1296 This function is used to register a singleton object \a cppObject, with a
1297 particular \a uri and \a typeName. Its version is a combination of \a
1298 versionMajor and \a versionMinor.
1300 Installing a singleton type into a URI allows you to provide arbitrary
1301 functionality (methods and properties) to QML code without requiring
1302 individual instances of the type to be instantiated by the client.
1304 Use this function to register an object of the given type T as a singleton
1307 A QObject singleton type may be referenced via the type name with which it
1308 was registered; in turn this type name may be used as the target in a \l
1309 Connections type, or like any other type ID. However, there's one
1310 exception: a QObject singleton type property can't be aliased because the
1311 singleton type name does not identify an object within the same component
1314 \note \a cppObject must outlive the QML engine in which it is used.
1315 Moreover, \cppObject must have the same thread affinity as the engine. If
1316 you want separate singleton instances for multiple engines, you need to use
1317 \l {qmlRegisterSingletonType}. See \l{Threads and QObjects} for more
1318 information about thread safety.
1320 \b{NOTE:} qmlRegisterSingleton can only be used when all types of that module are registered procedurally.
1324 // First, define your QObject which provides the functionality.
1325 class SingletonTypeExample : public QObject
1328 Q_PROPERTY(int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged)
1331 explicit SingletonTypeExample(QObject* parent = nullptr) : QObject(parent) {}
1333 Q_INVOKABLE int doSomething()
1336 return m_someProperty;
1339 int someProperty() const { return m_someProperty; }
1340 void setSomeProperty(int val) {
1341 if (m_someProperty != val) {
1342 m_someProperty = val;
1343 emit somePropertyChanged(val);
1348 void somePropertyChanged(int newValue);
1351 int m_someProperty = 0;
1356 // Second, create an instance of the object
1358 // allocate example before the engine to ensure that it outlives it
1359 QScopedPointer<SingletonTypeExample> example(new SingletonTypeExample);
1362 // Third, register the singleton type provider with QML by calling this
1363 // function in an initialization function.
1364 qmlRegisterSingletonInstance("Qt.example.qobjectSingleton", 1, 0, "MyApi", example.get());
1368 In order to use the registered singleton type in QML, you must import the
1369 URI with the corresponding version.
1372 import Qt.example.qobjectSingleton 1.0
1375 property int someValue: MyApi.someProperty
1377 Component.onCompleted: {
1378 console.log(MyApi.doSomething())
1383 \sa QML_SINGLETON, qmlRegisterSingletonType
1387 \fn int qmlRegisterType(const QUrl &url, const char *uri, int versionMajor, int versionMinor, const char *qmlName);
1390 This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the
1391 version number composed from \a versionMajor and \a versionMinor. The type is defined by the QML file located at \a url. The
1392 url must be an absolute URL, i.e. url.isRelative() == false.
1394 Normally QML files can be loaded as types directly from other QML files, or using a qmldir file. This function allows
1395 registration of files to types from C++ code, such as when the type mapping needs to be procedurally determined at startup.
1397 Returns -1 if the registration was not successful.
1401 \fn bool qmlProtectModule(const char* uri, int majVersion);
1404 This function protects a module from further modification. This can be used
1405 to prevent other plugins from injecting types into your module. It can also
1406 be a performance improvement, as it allows the engine to skip checking for
1407 the possibility of new types or plugins when this import is reached.
1409 Once qmlProtectModule has been called, a QML engine will not search for a new
1410 \c qmldir file to load the module anymore. It will re-use any \c qmldir files
1411 it has loaded before, though. Therefore, types present at this point continue
1412 to work. Mind that different QML engines may load different modules. The
1413 module protection, however, is global and affects all engines. The overhead
1414 of locating \c qmldir files and loading plugins may be noticeable with slow file
1415 systems. Therefore, protecting a module once you are sure you won't need to
1416 load it anymore can be a good optimization. Mind also that the module lock
1417 not only affects plugins but also any other qmldir directives, like \c import
1418 or \c prefer, as well as any composite types or scripts declared in a \c qmldir
1421 In addition, after this function is called, any attempt to register C++ types
1422 into this uri, major version combination will lead to a runtime error.
1424 Returns true if the module with \a uri as a \l{Identified Modules}
1425 {module identifier} and \a majVersion as a major version number was found
1426 and locked, otherwise returns false. The module must contain exported types
1427 in order to be found.
1432 \fn void qmlRegisterModule(const char* uri, int versionMajor, int versionMinor);
1435 This function registers a module in a particular \a uri with a version specified
1436 in \a versionMajor and \a versionMinor.
1438 This can be used to make a certain module version available, even if no types
1439 are registered for that version. This is particularly useful for keeping the
1440 versions of related modules in sync.
1445 \fn int qmlTypeId(const char* uri, int versionMajor, int versionMinor, const char *qmlName);
1448 Returns the QML type id of a type that was registered with the
1449 name \a qmlName in a particular \a uri and a version specified in \a
1450 versionMajor and \a versionMinor.
1452 This function returns the same value as the QML type registration functions
1453 such as qmlRegisterType() and qmlRegisterSingletonType().
1455 If \a qmlName, \a uri and \a versionMajor match a registered type, but the
1456 specified minor version in \a versionMinor is higher, then the id of the type
1457 with the closest minor version is returned.
1459 Returns -1 if no matching type was found or one of the given parameters
1462 \sa QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), qmlRegisterSingletonType()
1466 \macro QML_VALUE_TYPE(name)
1469 Declares the enclosing type or namespace to be available in QML, using \a name
1470 as the name. The type has to be a value type and the name has to be lower case.
1476 QML_VALUE_TYPE(myValueType)
1482 \sa {Choosing the Correct Integration Method Between C++ and QML}, QML_NAMED_ELEMENT
1486 \macro QML_CONSTRUCTIBLE_VALUE
1490 Marks the surrounding value type as constructible. That is, any \l Q_INVOKABLE
1491 constructors of the type that take exactly one argument can be used when
1492 assigning a JavaScript value to a property of this type.
1494 You can declare a constructible value type as follows:
1500 QML_VALUE_TYPE(myValueType)
1501 QML_CONSTRUCTIBLE_VALUE
1503 Q_INVOKABLE MyValueType(double d);
1509 With the above type, the following QML code will produce a \c MyValueType
1510 value using the given constructor and assign it to the property.
1514 property myValueType v: 5.4
1518 You can also construct lists of values this way:
1522 property list<myValueType> v: [5.4, 4.5, 3.3]
1526 If you make value types \l{ValueTypeBehavior}{addressable}, you can
1527 use such a type in a \l{Type annotations and assertions}{type assertion}
1528 to explicitly construct it:
1531 pragma ValueTypeBehavior: Addressable
1534 function process(d: real) {
1535 let v = d as myValueType;
1536 // v is a myValueType now, not a number
1545 \macro QML_STRUCTURED_VALUE
1549 Marks the surrounding value type as structured. Structured value types can
1550 and will preferably be constructed property-by-property from a JavaScript
1551 object. A structured value type, however is always \l QML_CONSTRUCTIBLE_VALUE,
1552 too. This means, you can still provide \l Q_INVOKABLE constructors in order to
1553 handle construction from primitive types.
1555 You can declare a structured value type as follows:
1561 QML_VALUE_TYPE(myValueType)
1562 QML_STRUCTURED_VALUE
1563 Q_PROPERTY(double d READ d WRITE setD)
1564 Q_PROPERTY(string e READ e WRITE setE)
1570 Then you can populate a property of this type as follows:
1574 property myValueType v: ({d: 4.4, e: "a string"})
1578 The extra parentheses are necessary to disambiguate the JavaScript object
1579 from what might be interpreted as a JavaScript code block.
1581 You can also construct lists of values this way:
1585 property list<myValueType> v: [
1586 {d: 4.4, e: "a string"},
1587 {d: 7.1, e: "another string"}
1592 If you make value types \l{ValueTypeBehavior}{addressable}, you can
1593 use such a type in a \l{Type annotations and assertions}{type assertion}
1594 to explicitly construct it:
1597 pragma ValueTypeBehavior: Addressable
1600 function process(d: real) {
1601 let v = {d: d, e: objectName} as myValueType;
1602 // v is a myValueType now
1607 \sa QML_VALUE_TYPE QML_CONSTRUCTIBLE_VALUE