diff options
Diffstat (limited to 'doc/src/declarative/extending.qdoc')
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 99 |
1 files changed, 57 insertions, 42 deletions
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 0456f3f..5aaa7bd 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -72,24 +72,23 @@ Custom C++ types are made available to QML using these two macros: \quotation \code #define QML_DECLARE_TYPE(T) -#define QML_DEFINE_TYPE(URI,VMAJ,VMIN,QmlName,T) +#define QML_REGISTER_TYPE(URI,VMAJ,VMIN,QDeclarativeName,T) \endcode Register the C++ type \a T with the QML system, and make it available in QML -under the name \a QmlName in library URI version VMAJ.VMIN. -\a T and \a QmlName may be the same. +under the name \a QDeclarativeName in library URI version VMAJ.VMIN. +\a T and \a QDeclarativeName may be the same. Generally the QML_DECLARE_TYPE() macro should be included immediately following -the type declaration (usually in its header file), and the QML_DEFINE_TYPE() -macro in the implementation file. QML_DEFINE_TYPE() must not be present in -a header file. +the type declaration (usually in its header file), and the QML_REGISTER_TYPE() +macro called by the implementation. Type \a T must be a concrete type that inherits QObject and has a default constructor. \endquotation Types can be registered by libraries (such as Qt does), application code, -or by plugins (see QmlModulePlugin). +or by plugins (see QDeclarativeExtensionPlugin). Once registered, all of the \l {Qt's Property System}{properties} of a supported type are available for use within QML. QML has intrinsic support for properties @@ -153,15 +152,14 @@ from registering a new QML type. The following macros are used instead: \quotation \code #define QML_DECLARE_INTERFACE(T) - #define QML_DEFINE_INTERFACE(T) + #define QML_REGISTER_INTERFACE(T) \endcode Register the C++ interface \a T with the QML system. Generally the QML_DECLARE_INTERFACE() macro should be included immediately following the interface declaration (usually in its header file), and the -QML_DEFINE_INTERFACE() macro in an implementation file. QML_DEFINE_INTERFACE() -must not be present in a header file. +QML_REGISTER_INTERFACE() macro called by the implementation. Following registration, QML can coerce objects that implement this interface for assignment to appropriately typed properties. @@ -169,7 +167,7 @@ for assignment to appropriately typed properties. The guests property is a list of \c Person objects. Properties that are lists of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just -like other properties. List properties must have the type \c {QmlListProperty<T>}. +like other properties. List properties must have the type \c {QDeclarativeListProperty<T>}. As with object properties, the type \a T must be registered with QML. The guest property declaration looks like this: @@ -194,7 +192,7 @@ 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_DEFINE_TYPE() and QML_DEFINE_INTERFACE() macros already shown can +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 as a base class that cannot be instantiated from QML needs to be registered these macros can be used: @@ -202,18 +200,17 @@ registered these macros can be used: \quotation \code #define QML_DECLARE_TYPE(T) - #define QML_DEFINE_NOCREATE_TYPE(T) + #define QML_REGISTER_NOCREATE_TYPE(T) \endcode -Register the C++ type \a T with the QML system. QML_DEFINE_NOCREATE_TYPE() -differs from QML_DEFINE_TYPE() in that it does not define a mapping between the +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 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_DEFINE_NOCREATE_TYPE() macro in the implementation file. -QML_DEFINE_NOCREATE_TYPE() must not be present in a header file. +QML_REGISTER_NOCREATE_TYPE() macro 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. @@ -375,6 +372,37 @@ object will only be returned if it has previously been created. \l {Extending QML - Attached Properties Example} shows the complete code used to implement the rsvp attached property. +\section1 Memory Management and QVariant types + +It is an elements responsibility to ensure that it does not access or return +pointers to invalid objects. QML makes the following guarentees: + +\list +\o An object assigned to an QObject (or QObject-derived) pointer property will be +valid at the time of assignment. + +Following assignment, it is the responsibility of the class to subsequently guard +this pointer, either through a class specific method or the generic QPointer class. + +\o An object assigned to a QVariant will be valid at the time of assignment. + +When assigning an object to a QVariant property, QML will always use a QMetaType::QObjectStar +typed QVariant. It is the responsibility of the class to guard the pointer. A +general rule when writing a class that uses QVariant properties is to check the +type of the QVariant when it is set and if the type is not handled by your class, +reset it to an invalid variant. + +\o An object assigned to a QObject (or QObject-derived) list property will be +valid at the time of assignment. + +Following assignment, it is the responsibility of the class to subsequently guard +this pointer, either through a class specific method or the generic QPointer class. +\endlist + +Elements should assume that any QML assigned object can be deleted at any time, and +respond accordingly. If documented as such an element need not continue to work in +this situation, but it must not crash. + \section1 Signal Support \snippet examples/declarative/extending/signal/example.qml 0 @@ -393,9 +421,8 @@ C++ signature: \snippet examples/declarative/extending/signal/birthdayparty.h 0 In classes with multiple signals with the same name, only the final signal -is accessible as a signal property. Although QML provides an element, -\l Connection, for accessing the other signals it is less elegant. For the best -QML API, class developers should avoid overloading signal names. +is accessible as a signal property. Note that signals with the same name +but different parameters cannot be distinguished. Signal parameters become accessible by name to the assigned script. An unnamed parameter cannot be accessed, so care should be taken to name all the @@ -433,8 +460,8 @@ itself, the QML engine sets up an association between the value source and the property. Property value sources are special types that derive from the -QmlPropertyValueSource base class. This base class contains a single method, -QmlPropertyValueSource::setTarget(), that the QML engine invokes when +QDeclarativePropertyValueSource base class. This base class contains a single method, +QDeclarativePropertyValueSource::setTarget(), that the QML engine invokes when associating the property value source with a property. The relevant part of the HappyBirthday type declaration looks like this: @@ -526,18 +553,6 @@ to be used in bindings should have a NOTIFY signal instead. \l {Extending QML - Binding Example} shows the BirthdayParty example updated to include NOTIFY signals for use in binding. -\section1 Binding and Script Properties - -While generally no changes are needed to a C++ class to use property -binding, sometimes more advanced interaction between the binding engine and -an object is desirable. To facilitate this, there is a special exception -in the bind engine for allowing an object to access the binding directly. - -If a binding is assigned to a property with a type of QmlBinding -pointer (ie. \c {QmlBinding *}), each time the binding value changes, -a QmlBinding instance is assigned to that property. The QmlBinding instance -allows the object to read the binding and to evaluate the binding's current value. - \section1 Extension Objects \snippet examples/declarative/extending/extended/example.qml 0 @@ -566,11 +581,11 @@ the appropriate property on the extension object is used instead. When an extended type is installed, one of the \code - #define QML_DEFINE_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QmlName,T, ExtendedT) - #define QML_DEFINE_EXTENDED_NOCREATE_TYPE(T, ExtendedT) + #define QML_REGISTER_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QDeclarativeName,T, ExtendedT) + #define QML_REGISTER_EXTENDED_NOCREATE_TYPE(T, ExtendedT) \endcode -macros should be used instead of the regular \c QML_DEFINE_TYPE or -\c QML_DEFINE_NOCREATE_TYPE. The arguments are identical to the corresponding +macros should be used instead of the regular \c QML_REGISTER_TYPE or +\c QML_REGISTER_NOCREATE_TYPE. The arguments are identical to the corresponding non-extension object macro, except for the ExtendedT parameter which is the type of the extension object. @@ -581,18 +596,18 @@ status of the QML engine. For example, it might be beneficial to delay initializing some costly data structures until after all the properties have been set. -The QML engine defines an interface class called QmlParserStatus, which contains a +The QML engine defines an interface class called QDeclarativeParserStatus, which contains a number of virtual methods that are invoked at various stages during component instantiation. To receive these notifications, an element implementation inherits -QmlParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro. +QDeclarativeParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro. For example, \code -class Example : public QObject, public QmlParserStatus +class Example : public QObject, public QDeclarativeParserStatus { Q_OBJECT - Q_INTERFACES(QmlParserStatus) + Q_INTERFACES(QDeclarativeParserStatus) public: virtual void componentComplete() { |