diff options
Diffstat (limited to 'doc/src/declarative/extending.qdoc')
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 62 |
1 files changed, 33 insertions, 29 deletions
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 5aaa7bd..0ae4f7d 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -41,7 +41,7 @@ /*! \page qml-extending.html -\title Extending QML +\title Extending QML in C++ The QML syntax declaratively describes how to construct an in memory object tree. In Qt, QML is mainly used to describe a visual scene graph, but it is @@ -67,21 +67,23 @@ that derive from QObject. The QML engine has no intrinsic knowledge of any class types. Instead the programmer must define the C++ types, and their corresponding QML name. -Custom C++ types are made available to QML using these two macros: +Custom C++ types are declared QML types using a macro and a template function: \quotation + \code #define QML_DECLARE_TYPE(T) -#define QML_REGISTER_TYPE(URI,VMAJ,VMIN,QDeclarativeName,T) +template<typename T> +int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) \endcode -Register the C++ type \a T with the QML system, and make it available in QML -under the name \a QDeclarativeName in library URI version VMAJ.VMIN. -\a T and \a QDeclarativeName may be the same. +Calling qmlRegisterType() registers the C++ type \a T with the QML system, and makes it available in QML +under the name \a qmlName in library \a uri version \a versionMajor.versionMinor. +The \a qmlName can be the same as the C++ type name. Generally the QML_DECLARE_TYPE() macro should be included immediately following -the type declaration (usually in its header file), and the QML_REGISTER_TYPE() -macro called by the implementation. +the type declaration (usually in its header file), and the template function qmlRegisterType() +called by the implementation. Type \a T must be a concrete type that inherits QObject and has a default constructor. @@ -147,19 +149,20 @@ property can be assigned. QML also supports assigning Qt interfaces. To assign to a property whose type is a Qt interface pointer, the interface must also be registered with QML. As they cannot be instantiated directly, registering a Qt interface is different -from registering a new QML type. The following macros are used instead: +from registering a new QML type. The following macro and function are used instead: \quotation \code - #define QML_DECLARE_INTERFACE(T) - #define QML_REGISTER_INTERFACE(T) +#define QML_DECLARE_INTERFACE(T) +template<typename T> +int qmlRegisterInterface(const char *typeName) \endcode -Register the C++ interface \a T with the QML system. +Registers the C++ interface \a T with the QML system as \a typeName. Generally the QML_DECLARE_INTERFACE() macro should be included immediately following the interface declaration (usually in its header file), and the -QML_REGISTER_INTERFACE() macro called by the implementation. +qmlRegisterInterface() template function called by the implementation. Following registration, QML can coerce objects that implement this interface for assignment to appropriately typed properties. @@ -174,7 +177,7 @@ The guest property declaration looks like this: \snippet examples/declarative/extending/properties/birthdayparty.h 2 -\l {Extending QML - Object and List Property Types Example} shows the complete +\l {Extending QML in C++ - Object and List Property Types Example} shows the complete code used to create the \c BirthdayParty type. \section1 Inheritance and Coercion @@ -192,25 +195,26 @@ type used in the previous section, but the assignment is valid as both the Boy and Girl objects inherit from Person. To assign to a property, the property's type must have been registered with QML. -Both the QML_REGISTER_TYPE() and QML_REGISTER_INTERFACE() macros already shown can -be used to register a type with QML. Additionally, if a type that acts purely +Both the qmlRegisterType() and qmlRegisterInterface() template functions already +shown can be used to register a type with QML. Additionally, if a type that acts purely as a base class that cannot be instantiated from QML needs to be -registered these macros can be used: +registered these macro and function can be used: \quotation \code #define QML_DECLARE_TYPE(T) - #define QML_REGISTER_NOCREATE_TYPE(T) + template<typename T> + int qmlRegisterType() \endcode -Register the C++ type \a T with the QML system. QML_REGISTER_NOCREATE_TYPE() -differs from QML_REGISTER_TYPE() in that it does not define a mapping between the +Registers the C++ type \a T with the QML system. The parameterless call to the template +function qmlRegisterType() does not define a mapping between the C++ class and a QML element name, so the type is not instantiable from QML, but it is available for type coercion. Generally the QML_DECLARE_TYPE() macro should be included immediately following the type declaration (usually in its header file), and the -QML_REGISTER_NOCREATE_TYPE() macro called from the implementation. +qmlRegisterType() template function called from the implementation. Type \a T must inherit QObject, but there are no restrictions on whether it is concrete or the signature of its constructor. @@ -220,7 +224,7 @@ QML will automatically coerce C++ types when assigning to either an object property, or to a list property. Only if coercion fails does an assignment error occur. -\l {Extending QML - Inheritance and Coercion Example} shows the complete +\l {Extending QML in C++ - Inheritance and Coercion Example} shows the complete code used to create the \c Boy and \c Girl types. \section1 Default Property @@ -252,7 +256,7 @@ refer to a property declared in the class itself, or a property inherited from a base class. \endquotation -\l {Extending QML - Default Property Example} shows the complete code used to +\l {Extending QML in C++ - Default Property Example} shows the complete code used to specify a default property. \section1 Grouped Properties @@ -277,7 +281,7 @@ property block - in this case the size, color, brand and price properties. Grouped property blocks may declared and accessed be recusively. -\l {Extending QML - Grouped Properties Example} shows the complete code used to +\l {Extending QML in C++ - Grouped Properties Example} shows the complete code used to implement the \c shoe property grouping. \section1 Attached Properties @@ -369,7 +373,7 @@ creating it if it does not already exist. If \a create is false, the attachment object will only be returned if it has previously been created. \endquotation -\l {Extending QML - Attached Properties Example} shows the complete code used to +\l {Extending QML in C++ - Attached Properties Example} shows the complete code used to implement the rsvp attached property. \section1 Memory Management and QVariant types @@ -431,7 +435,7 @@ listed in \l {Adding Types}, as well registered object types are permitted as signal parameter types. Using other types is not an error, but the parameter value will not be accessible from script. -\l {Extending QML - Signal Support Example} shows the complete code used to +\l {Extending QML in C++ - Signal Support Example} shows the complete code used to implement the onPartyStarted signal property. \section1 Property Value Sources @@ -478,7 +482,7 @@ to assign it normally, as though it were a regular QML type. Only if this assignment fails does the engine call the setTarget() method. This allows the type to also be used in contexts other than just as a value source. -\l {Extending QML - Property Value Source Example} shows the complete code used +\l {Extending QML in C++ - Property Value Source Example} shows the complete code used implement the HappyBirthday property value source. \section1 Property Binding @@ -550,7 +554,7 @@ The CONSTANT attribute should only be used for properties whose value is set, and finalized, only in the class constructor. All other properties that want to be used in bindings should have a NOTIFY signal instead. -\l {Extending QML - Binding Example} shows the BirthdayParty example updated to +\l {Extending QML in C++ - Binding Example} shows the BirthdayParty example updated to include NOTIFY signals for use in binding. \section1 Extension Objects @@ -623,7 +627,7 @@ public: \title Extending types from QML Many of the elements available for use in QML are implemented in -\l {Extending QML}{C++}. These types are know as "core types". QML +\l {Extending QML in C++}{C++}. These types are know as "core types". QML allows programmers to build new, fully functional elements without using C++. Existing core types can be extended, and new types defined entirely in the QML language. |