diff options
Diffstat (limited to 'doc/src/declarative/extending.qdoc')
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 94 |
1 files changed, 55 insertions, 39 deletions
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 0456f3f..d823bf6 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 @@ -433,8 +461,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 +554,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 +582,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 +597,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() { |