From 0b33c6ebc9a6aa82ef385246b3b5083d0414a3d9 Mon Sep 17 00:00:00 2001 From: Ulf Hermann Date: Wed, 12 Feb 2020 15:36:21 +0100 Subject: Add documentation for the QML_* macros Task-number: QTBUG-81615 Change-Id: Ida02001803230d7daed9352e27689b417f3ac15c Reviewed-by: Mitch Curtis --- src/qml/doc/src/qmlfunctions.qdoc | 302 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 289 insertions(+), 13 deletions(-) (limited to 'src/qml/doc/src/qmlfunctions.qdoc') diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index 67c0f6bb25..63c28d7aa7 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -25,6 +25,273 @@ ** ****************************************************************************/ +/*! + \macro QML_ELEMENT + \related 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 + "com.mycompany.qmlcomponents" with major version \c 1 by specifying the + following in your project file: + + \code + 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. + + \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) + \related 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. + + \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. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE(), QML_ANONYMOUS +*/ + +/*! + \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. + + \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 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 the type's default constructor when the type is first + accessed. If there is no default constructor the singleton is initially + inaccessible. This behavior can be overridden by calling + \l qmlRegisterSingletonType() with a specific factory function or + \l qmlRegisterSingletonInstance() with a specific instance for the same class + and the same type namespace and version. + + \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(), qmlAtachedPropertiesObject(), + {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 and methods 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(), {Registering Extension Objects} +*/ + +/*! + \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(), or \l QML_EXTENDED() 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 G_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. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT() +*/ + +/*! + \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: + \code + fun.qml: Get back to work, slacker! + Game { + ^ + \endcode + + Using this technique, you only need a \l G_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 @@ -41,7 +308,8 @@ 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}. + {attached properties}. QML_DECLARE_TYPEINFO() is not necessary if \a Type contains the + QML_ATTACHED macro. */ /*! @@ -106,7 +374,8 @@ QML written to previous versions to continue to work, even if more advanced versions of some of its types are available. - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), + {Choosing the Correct Integration Method Between C++ and QML} */ /*! @@ -143,7 +412,7 @@ Returns the QML type id. - \sa qmlRegisterTypeNotAvailable(), + \sa QML_UNCREATABLE(), qmlRegisterTypeNotAvailable(), {Choosing the Correct Integration Method Between C++ and QML} */ @@ -158,7 +427,7 @@ Returns the QML type id. - \sa qmlRegisterType(), {Registering Extension Objects} + \sa QML_EXTENDED(), qmlRegisterType(), {Registering Extension Objects} */ @@ -180,7 +449,7 @@ Returns the QML type id. - \sa qmlRegisterUncreatableType() + \sa QML_EXTENDED(), QML_UNCREATABLE(), qmlRegisterUncreatableType() */ /*! @@ -220,6 +489,8 @@ \code Component.onCompleted: console.log(MyNamespace.Key2) \endcode + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_UNCREATABLE() */ /*! @@ -235,6 +506,8 @@ the \a parser provided. Returns the QML type id. + + \sa QML_ELEMENT, QML_NAMED_ELEMENT(), QML_EXTENDED() */ /*! @@ -269,7 +542,7 @@ Without this, a generic "Game is not a type" message would be given. - \sa qmlRegisterUncreatableType(), + \sa QML_UNAVAILABLE, qmlRegisterUncreatableType(), {Choosing the Correct Integration Method Between C++ and QML} */ @@ -353,7 +626,7 @@ Returns the QML type id. \since 5.14 - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_ANONYMOUS, {Choosing the Correct Integration Method Between C++ and QML} */ /*! @@ -397,6 +670,8 @@ the interface cast to \c FooInterface* automatically. Returns the QML type id. + + \sa QML_INTERFACE */ /*! @@ -455,7 +730,7 @@ } \endqml - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML} */ /*! @@ -477,8 +752,7 @@ 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 {Providing Attached Properties} - + \sa QML_ATTACHED(), {Providing Attached Properties} */ /*! @@ -571,7 +845,7 @@ } \endqml - \sa {Choosing the Correct Integration Method Between C++ and QML} + \sa QML_SINGLETON, {Choosing the Correct Integration Method Between C++ and QML} */ @@ -626,6 +900,8 @@ 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 */ /*! @@ -718,7 +994,7 @@ } \endqml - \sa qmlRegisterSingletonType + \sa QML_SINGLETON, qmlRegisterSingletonType */ /*! @@ -792,5 +1068,5 @@ Returns -1 if no matching type was found or one of the given parameters was invalid. - \sa qmlRegisterType(), qmlRegisterSingletonType() + \sa QML_ELEMENT, QML_NAMED_ELEMENT, QML_SINGLETON, qmlRegisterType(), qmlRegisterSingletonType() */ -- cgit v1.2.3