diff options
Diffstat (limited to 'src/qml/doc/src/cppintegration/definetypes.qdoc')
| -rw-r--r-- | src/qml/doc/src/cppintegration/definetypes.qdoc | 143 |
1 files changed, 114 insertions, 29 deletions
diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index e6a6dbfe36..feb9053632 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -16,7 +16,7 @@ as an instantiable \l{qtqml-typesystem-objecttypes.html}{QML object type} from QML, or enabling a singleton instance of the class to be imported and used from QML. -Additionally, the \l {Qt QML} module provides mechanisms for implementing QML-specific +Additionally, the \l {Qt Qml} module provides mechanisms for implementing QML-specific features such as \e{attached properties} and \e{default properties} in C++. (Note that a number of the important concepts covered in this document are @@ -77,15 +77,18 @@ Types to QML} explains, the properties, methods and signals of any QObject-derived class are accessible from QML code. To register a QObject-derived class as an instantiable QML object type, add -\c QML_ELEMENT or \c QML_NAMED_ELEMENT(<name>) to the class declaration and +\c QML_ELEMENT or \c QML_NAMED_ELEMENT(<name>) to the class declaration. You +also need to make adjustments in the build system. For qmake, add \c {CONFIG += qmltypes}, a \c {QML_IMPORT_NAME}, and a -\c QML_IMPORT_MAJOR_VERSION to your project file. This will register the class -into the type namespace under the given major version, using either the class -name or an explicitly given name as QML type name. The minor version(s) will -be derived from any revisions attached to properties, methods, or signals. The -default minor version is \c 0. You can explicitly restrict the type to be -available only from specific minor versions by adding the -\c QML_ADDED_IN_MINOR_VERSION() macro to the class declaration. Clients can +\c QML_IMPORT_MAJOR_VERSION to your project file. For CMake, the file containing +the class should be part of a target set-up with +\l{qt_add_qml_module}{qt_add_qml_module()}. +This will register the class into the type namespace under the given major version, +using either the class name or an explicitly given name as QML type name. The +minor version(s) will be derived from any revisions attached to properties, +methods, or signals. The default minor version is \c 0. You can explicitly +restrict the type to be available only from specific minor versions by adding +the \c QML_ADDED_IN_VERSION() macro to the class declaration. Clients can import suitable versions of the namespace in order to use the type. For example, suppose there is a \c Message class with \c author and @@ -107,26 +110,52 @@ This type can be registered by adding an appropriate type namespace and version number to the project file. For example, to make the type available in the \c com.mycompany.messaging namespace with version 1.0: -\code -CONFIG += qmltypes -QML_IMPORT_NAME = com.mycompany.messaging -QML_IMPORT_MAJOR_VERSION = 1 -\endcode +\if defined(onlinedocs) + \tab {build-qt-app}{tab-cmake}{CMake}{selected} + \tab {build-qt-app}{tab-qmake}{qmake}{} + \tabcontent {tab-cmake} + \else + \section3 Using CMake +\endif + \badcode + qt_add_qml_module(messaging + URI com.mycompany.messaging + VERSION 1.0 + SOURCES + message.cpp message.h + ) + \endcode +\if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmake} +\else + \section3 Using QMake +\endif + \code + CONFIG += qmltypes + QML_IMPORT_NAME = com.mycompany.messaging + QML_IMPORT_MAJOR_VERSION = 1 + \endcode + + If the header the class is declared in is not accessible from your project's + include path, you may have to amend the include path so that the generated + registration code can be compiled. + + \code + INCLUDEPATH += com/mycompany/messaging + \endcode +\if defined(onlinedocs) + \endtabcontent +\endif -If the header the class is declared in is not accessible from your project's -include path, you may have to amend the include path so that the generated -registration code can be compiled: -\code -INCLUDEPATH += com/mycompany/messaging -\endcode The type can be used in an \l{qtqml-syntax-basics.html#object-declarations} {object declaration} from QML, and its properties can be read and written to, as per the example below: \qml -import com.mycompany.messaging 1.0 +import com.mycompany.messaging Message { author: "Amelie" @@ -137,7 +166,7 @@ Message { \section2 Registering Value Types Any type with a \l{Q_GADGET} macro can the registered as a -\l{qtqml-typesystem-valuetypes.html}{QML value type}}. Once such a type is +\l{qtqml-typesystem-valuetypes.html}{QML value type}. Once such a type is registered with the QML type system it can be used as property type in QML code. Such an instance can be manipulated from QML; as \l{qtqml-cppintegration-exposecppattributes.html}{Exposing Attributes of C++ @@ -177,6 +206,60 @@ There are some further limitations on what you can do with value types: and subject to future changes. \endlist +\section2 Value Types with Enumerations + +Exposing enumerations from a value type to QML requires some extra steps. + +Value types have lower case names in QML and types with lower case +names are generally not addressable in JavaScript code (unless you specify +\l{ValueTypeBehavior}{pragma ValueTypeBehavior: Addressable}). If you have +a value type in C++ with an enumeration you want to expose to QML, you +need to expose the enumeration separately. + +This can be solved by using \l{QML_FOREIGN_NAMESPACE}. First, derive from +your value type to create a separate C++ type: + +\code +class Person +{ + Q_GADGET + Q_PROPERTY(QString firstName READ firstName WRITE setFirstName) + Q_PROPERTY(QString lastName READ lastName WRITE setLastName) + QML_VALUE_TYPE(person) +public: + enum TheEnum { A, B, C }; + Q_ENUM(TheEnum) + //... +}; + +class PersonDerived: public Person +{ + Q_GADGET +}; +\endcode + +Then expose the derived type as a foreign namespace: + +\code +namespace PersonDerivedForeign +{ + Q_NAMESPACE + QML_NAMED_ELEMENT(Person) + QML_FOREIGN_NAMESPACE(PersonDerived) +} +\endcode + +This produces a \l{qtqml-typesystem-namespaces.html}{QML Namespace} +called \c Person (upper case) with an enumeration called \c TheEnum and +values \c{A}, \c{B}, and \c{C}. Then you can write the following in QML: + +\qml + someProperty: Person.A +\endqml + +At the same time you can still use your value type called \c person +(lower case) exactly as before. + \section2 Registering Non-Instantiable Types Sometimes a QObject-derived class may need to be registered with the QML type @@ -192,7 +275,7 @@ not be instantiable should not be instantiable from QML \endlist -The \l {Qt QML} module provides several macros for registering non-instantiable +The \l {Qt Qml} module provides several macros for registering non-instantiable types: \list @@ -256,6 +339,7 @@ be aware that properties of such a singleton type cannot be bound to. See \l{QML_SINGLETON} for more information on how implement and register a new singleton type, and how to use an existing singleton type. +See \l{Singletons in QML} for more in-depth information about singletons. \note Enum values for registered types in QML should start with a capital. @@ -331,7 +415,7 @@ available when \c MyTypes version 1.1 or higher is imported. Imports of \c MyTypes version 1.0 remain unaffected. For the same reason, new types introduced in later versions should be tagged -with the QML_ADDED_IN_MINOR_VERSION macro. +with the QML_ADDED_IN_VERSION macro. This feature of the language allows for behavioural changes to be made without breaking existing applications. Consequently QML module authors @@ -361,7 +445,11 @@ type definition allows the programmer to supply an additional type, known as the \e{extension type}, when registering the class. Its members are transparently merged with the original target class when used from within QML. For example: -\snippet referenceexamples/extended/example.qml 0 +\qml +QLineEdit { + leftMargin: 20 +} +\endqml The \c leftMargin property is a new property added to an existing C++ type, \l QLineEdit, without modifying its source code. @@ -380,9 +468,6 @@ extended property is accessed. The extension class is created and the target object is passed in as the parent. When the property on the original is accessed, the corresponding property on the extension object is used instead. -The \l{Extending QML - Extension Objects Example}{Extension Objects Example} -demonstrates a usage of extension objects. - \section2 Registering Foreign Types There may be C++ types that cannot be modified to hold the above mentioned @@ -861,7 +946,7 @@ its properties have been set. For example, this may be the case if the initialization is costly, or if the initialization should not be performed until all property values have been initialized. -The \l {Qt QML} module provides the QQmlParserStatus to be subclassed for these +The \l {Qt Qml} module provides the QQmlParserStatus to be subclassed for these purposes. It defines a number of virtual methods that are invoked at various stages during component instantiation. To receive these notifications, a C++ class should inherit QQmlParserStatus and also notify the Qt meta system |