diff options
| -rw-r--r-- | examples/qml/doc/src/qml-extending.qdoc | 19 | ||||
| -rw-r--r-- | src/qml/doc/src/cppintegration/definetypes.qdoc | 46 | ||||
| -rw-r--r-- | src/qml/doc/src/qmlfunctions.qdoc | 23 |
3 files changed, 85 insertions, 3 deletions
diff --git a/examples/qml/doc/src/qml-extending.qdoc b/examples/qml/doc/src/qml-extending.qdoc index 8f44e4f506..f25b75ed29 100644 --- a/examples/qml/doc/src/qml-extending.qdoc +++ b/examples/qml/doc/src/qml-extending.qdoc @@ -63,6 +63,25 @@ loads and runs the QML snippet shown at the beginning of this page. */ /*! +\example referenceexamples/extended +\title Extending QML - Extension Objects Example +\brief Extension Objects +\ingroup qmlextendingexamples + +This example builds on: +\list +\li \l {Extending QML - Adding Types Example} +\endlist + +Shows how to use \l qmlRegisterExtendedType() to provide an \l {Registering +Extension Objects}{extension object} to a \l QLineEdit without modifying or +subclassing. The QML engine instantiates a \l QLineEdit and sets a property that +only exists on the extension type. The extension type performs calls on the \l +QLineEdit that otherwise will not be accessible to the QML engine. + +*/ + +/*! \example referenceexamples/properties \title Extending QML - Object and List Property Types Example \brief Exporting C++ Properties diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc index 03607df2e5..2f780503b2 100644 --- a/src/qml/doc/src/cppintegration/definetypes.qdoc +++ b/src/qml/doc/src/cppintegration/definetypes.qdoc @@ -294,6 +294,52 @@ This is useful when deriving from base classes provided by other authors, e.g. when extending classes from the Qt Quick module. +\section2 Registering Extension Objects + +When integrating existing classes and technology into QML, APIs will +often need tweaking to fit better into the declarative environment. +Although the best results are usually obtained by modifying the original +classes directly, if this is either not possible or is complicated by some +other concerns, extension objects allow limited extension possibilities +without direct modifications. + +\e{Extension objects} add additional properties to an existing type. Extension +objects can only add properties, not signals or methods. An extended type +definition allows the programmer to supply an additional type, known as the +\e{extension type}, when registering the class. The properties are transparently +merged with the original target class when used from within QML. For example: + +\snippet referenceexamples/extended/example.qml 0 + +The \c leftMargin property is a new property added to an existing C++ type, \l +QLineEdit, without modifying its source code. + +The \l qmlRegisterExtendedType() function is for registering extended types. +Note that it has two forms. + +\code +template<typename T, typename ExtendedT> +int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + +template<typename T, typename ExtendedT> +int qmlRegisterExtendedType() +\endcode + +This functions should be used instead of the regular \c qmlRegisterType() +variations. The arguments are identical to the corresponding non-extension +registration functions, except for the ExtendedT parameter which is the type of +the extension object. + +An extension class is a regular QObject, with a constructor that takes a QObject +pointer. However, the extension class creation is delayed until the first +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. + + \section1 Defining QML-Specific Types and Attributes diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc index e95784dc5c..6b0f9dba10 100644 --- a/src/qml/doc/src/qmlfunctions.qdoc +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -157,8 +157,25 @@ */ /*! - \fn int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) - \relates QQmlEgine + \fn int qmlRegisterExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + \relates QQmlEngine + + This template function registers the C++ type and its extension object in the + QML system with the name \a qmlName in the library imported from \a uri having + version number composed from \a versionMajor and \a versionMinor. Properties + not available in the main type will be searched for in the extension object. + + Returns the QML type id. + + #include <QtQml> to use this function. + + \sa qmlRegisterType(), {Registering Extension Objects} +*/ + + +/*! + \fn int qmlRegisterExtendedUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& reason) + \relates QQmlEngine This template function registers the C++ type and its extension in the QML system with the name \a qmlName in the library imported @@ -180,7 +197,7 @@ /*! \fn int qmlRegisterCustomExtendedType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, QQmlCustomParser *parser) - \relates QQmlEgine + \relates QQmlEngine This template function registers the C++ type and its extension in the QML system with the name \a qmlName in the library imported |