diff options
author | Chris Adams <christopher.adams@nokia.com> | 2012-06-27 17:28:32 +1000 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2012-06-29 04:33:35 +0200 |
commit | 1398d616754a2dd1618a2b31a43a86cc078af8a2 (patch) | |
tree | 4be64f6bd79e1a9b7b6a58739888bcefbde991db /src/qml/doc | |
parent | 5796f88d544a59c507356a8830d72957104d73db (diff) |
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 <bea.lam@nokia.com>
Diffstat (limited to 'src/qml/doc')
-rw-r--r-- | src/qml/doc/src/cppintegration/functions.qdoc | 6 | ||||
-rw-r--r-- | src/qml/doc/src/cppintegration/registercpptypes.qdoc | 39 |
2 files changed, 43 insertions, 2 deletions
diff --git a/src/qml/doc/src/cppintegration/functions.qdoc b/src/qml/doc/src/cppintegration/functions.qdoc index e1318b5bee..10a943434e 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<T>()} +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 0e1188310b..5020b68033 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<T>()} 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 |