From: Chris Adams Date: Wed, 27 Jun 2012 07:28:32 +0000 (+1000) Subject: Improve documentation for module APIs X-Git-Tag: 071012131707~64 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1398d616754a2dd1618a2b31a43a86cc078af8a2;p=profile%2Fivi%2Fqtdeclarative.git Improve documentation for module APIs Previously, it was not made clear to plugin developers why they might wish to implement a module API. This commit adds documentation which describes how module APIs can be useful, in the same section as the other qml type registration explanatory documentation. Task-number: QTBUG-25731 Change-Id: I2350ce8e5ae90598a65295fb2afb7dbd23eb7da6 Reviewed-by: Bea Lam --- diff --git a/src/qml/doc/src/cppintegration/functions.qdoc b/src/qml/doc/src/cppintegration/functions.qdoc index e1318b5..10a9434 100644 --- a/src/qml/doc/src/cppintegration/functions.qdoc +++ b/src/qml/doc/src/cppintegration/functions.qdoc @@ -198,8 +198,10 @@ must be taken to avoid unwanted ownership changes occurring. One of the simplest ways to expose C++ functionality to clients in QML is by registering a QObject module API. This allows functionality and data to be exposed in a namespace which is accessible from QML. -See the qmlRegisterModuleApi() documentation for more information -about registering module APIs. +See the documentation about +\l{Defining QML Object Types from C++#Module-API-Type-Registration} +for information about module APIs, and see the \l{qmlRegisterModuleApi()} +documentation for details on how to register and use a module API. A module API is instantiated and owned by the engine as a singleton. Thus, it is more performant to implement common functionality in a module diff --git a/src/qml/doc/src/cppintegration/registercpptypes.qdoc b/src/qml/doc/src/cppintegration/registercpptypes.qdoc index 0e11883..5020b68 100644 --- a/src/qml/doc/src/cppintegration/registercpptypes.qdoc +++ b/src/qml/doc/src/cppintegration/registercpptypes.qdoc @@ -189,6 +189,45 @@ int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const c Following registration, QML can \l{qml-c++-coercion}{coerce} objects that implement this interface for assignment to appropriately typed properties. +\section2 Module API Type Registration + + Module APIs allow you to expose properties, signals and slots in a namespace + without requiring the client to manually instantiate an object instance. + QObject module APIs in particular are an efficient and convenient way to + provide functionality or global property values to clients. + + Note that module APIs do not have an associated QQmlContext as they are + shared across all contexts in an engine. QObject module API instances + are constructed and owned by the QQmlEngine, and will be destroyed when + the engine is destroyed. + + A QObject module API can be interacted with in a manner simlar to any + other QObject or instantiated element. That is, Q_PROPERTYs of QObject + module APIs may be bound to, and Q_INVOKABLE functions of QObject module + APIs may be used in signal handler expressions. This makes module APIs + an ideal way to implement styling or theming, and they can also be used + instead of ".pragma library" script imports to store global state or to + provide global functionality. + + Once registered, a QObject module API may be used as any other QObject + instance exposed to QML. The following example assumes that a QObject + module API was registered into the "MyThemeModule" namespace with version + 1.0, where that QObject has a QColor "color" Q_PROPERTY: + + \qml + import MyThemeModule 1.0 as Theme + + Rectangle { + color: Theme.color // binding. + } + \endqml + + A QJSValue may also be exposed as a module API, however clients should + be aware that properties of such a module API cannot be bound to. + + See \l{qmlRegisterModuleApi()} for more information on how implement and + register a new module API, and how to use an existing module API. + \section1 Type Revisions and Versions Type revisions and versions allow new properties or methods to exist in the