From fb21b2bdde09b2cb49316073ac47518245b6d481 Mon Sep 17 00:00:00 2001 From: Chris Adams Date: Fri, 4 Nov 2011 11:51:53 +1000 Subject: [PATCH] Fix module API provider registration function documentation Previously, the documentation was not able to be linked correctly by qdoc3. This commit moves the documentation to the correct file and ensures that the links work correctly. It also fixes a typo in the QQuickLoader documentation. Change-Id: Id675954dd3009fafe6e0cfeb81342c947302ffcb Reviewed-by: Martin Jones --- doc/src/declarative/extending.qdoc | 4 + doc/src/declarative/qtdeclarative.qdoc | 124 ++++++++++++++++++++++++++++++++ src/declarative/items/qquickloader.cpp | 2 +- src/declarative/qml/qdeclarative.h | 116 ----------------------------- 4 files changed, 129 insertions(+), 117 deletions(-) diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index bed31ab..d26549a 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -116,6 +116,10 @@ Person { \l {Extending QML - Adding Types Example} shows the complete code used to create the \c Person type. +If you wish to provide functionality to clients without requiring them to +instantiate an element, consider providing a module API instead of registering +a type; see qmlRegisterModuleApi() for more information. + \section1 QML Type Versioning In C++ adding a new method or property cannot break old applications. diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index e83641d..1570ed7 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -211,3 +211,127 @@ Returns the QML type id. */ + +/*! + \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QDeclarativeEngine *, QJSEngine *)) + \relates QDeclarativeEngine + + This function may be used to register a module API provider \a callback in a particular \a uri + with a version specified in \a versionMajor and \a versionMinor. + + Installing a module API into a uri allows developers to provide arbitrary functionality + (methods and properties) in a namespace that doesn't necessarily contain elements. + + A module API may be either a QObject or a QJSValue. Only one module API provider + may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor). + This function should be used to register a module API provider function which returns a QJSValue as a module API. + + \bold{NOTE:} QJSValue module API properties will \bold{not} trigger binding re-evaluation if changed. + + Usage: + \code + // first, define the module API provider function (callback). + static QJSValue *example_qjsvalue_module_api_provider(QDeclarativeEngine *engine, QJSEngine *scriptEngine) + { + Q_UNUSED(engine) + + static int seedValue = 5; + QJSValue example = scriptEngine->newObject(); + example.setProperty("someProperty", seedValue++); + return example; + } + + // second, register the module API provider with QML by calling this function in an initialization function. + ... + qmlRegisterModuleApi("Qt.example.qjsvalueApi", 1, 0, example_qjsvalue_module_api_provider); + ... + \endcode + + In order to use the registered module API in QML, you must import the module API. + \qml + import QtQuick 2.0 + import Qt.example.qjsvalueApi 1.0 as ExampleApi + Item { + id: root + property int someValue: ExampleApi.someProperty + } + \endqml + */ + +/*! + \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QDeclarativeEngine *, QJSEngine *)) + \relates QDeclarativeEngine + + This function may be used to register a module API provider \a callback in a particular \a uri + with a version specified in \a versionMajor and \a versionMinor. + + Installing a module API into a uri allows developers to provide arbitrary functionality + (methods and properties) in a namespace that doesn't necessarily contain elements. + + A module API may be either a QObject or a QJSValue. Only one module API provider + may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor). + This function should be used to register a module API provider function which returns a QObject as a module API. + + A QObject module API must be imported with a qualifier, and that qualifier may be used as + the target in a \l Connections element or otherwise used as any other element id would. + One exception to this is that a QObject module API property may not be aliased (because the + module API qualifier does not identify an object within the same component as any other item). + + Usage: + \code + // first, define your QObject which provides the functionality. + class ModuleApiExample : public QObject + { + Q_OBJECT + Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) + + public: + ModuleApiExample(QObject* parent = 0) + : QObject(parent), m_someProperty(0) + { + } + + ~ModuleApiExample() {} + + Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; } + + int someProperty() const { return m_someProperty; } + void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); } + + signals: + void somePropertyChanged(int newValue); + + private: + int m_someProperty; + }; + + // second, define the module API provider function (callback). + static QObject *example_qobject_module_api_provider(QDeclarativeEngine *engine, QJSEngine *scriptEngine) + { + Q_UNUSED(engine) + Q_UNUSED(scriptEngine) + + ModuleApiExample *example = new ModuleApiExample(); + return example; + } + + // third, register the module API provider with QML by calling this function in an initialization function. + ... + qmlRegisterModuleApi("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider); + ... + \endcode + + In order to use the registered module API in QML, you must import the module API. + \qml + import QtQuick 2.0 + import Qt.example.qobjectApi 1.0 as ExampleApi + Item { + id: root + property int someValue: ExampleApi.someProperty + + Component.onCompleted: { + someValue = ExampleApi.doSomething() + } + } + \endqml + */ diff --git a/src/declarative/items/qquickloader.cpp b/src/declarative/items/qquickloader.cpp index cef98a6..73f5707 100644 --- a/src/declarative/items/qquickloader.cpp +++ b/src/declarative/items/qquickloader.cpp @@ -428,7 +428,7 @@ void QQuickLoader::loadFromSourceComponent() the \a source component will be created with the initial \a properties set. Setting the initial property values of an instance of a component in this manner - will \e not trigger any associated \l{Behavior}s. + will \bold{not} trigger any associated \l{Behavior}s. Note that the cached \a properties will be cleared if the \l source or \l sourceComponent is changed after calling this function but prior to setting the loader \l active. diff --git a/src/declarative/qml/qdeclarative.h b/src/declarative/qml/qdeclarative.h index 566a420..b98899b 100644 --- a/src/declarative/qml/qdeclarative.h +++ b/src/declarative/qml/qdeclarative.h @@ -413,48 +413,6 @@ QObject *qmlAttachedPropertiesObject(const QObject *obj, bool create = true) // For the use of QtQuick1 module Q_DECLARATIVE_EXPORT void qmlRegisterBaseTypes(const char *uri, int versionMajor, int versionMinor); -/*! - This function may be used to register a module API provider \a callback in a particular \a uri - with a version specified in \a versionMajor and \a versionMinor. - - Installing a module API into a uri allows developers to provide arbitrary functionality - (methods and properties) in a namespace that doesn't necessarily contain elements. - - A module API may be either a QObject or a QJSValue. Only one module API provider - may be registered into any given namespace (combination of \a uri, \a majorVersion and \a minorVersion). - This function should be used to register a module API provider function which returns a QJSValue as a module API. - - \e NOTE: QJSValue module API properties will \e not trigger binding re-evaluation if changed. - - Usage: - \code - // first, define the module API provider function (callback). - static QJSValue *example_qjsvalue_module_api_provider(QDeclarativeEngine *engine, QJSEngine *scriptEngine) - { - Q_UNUSED(engine) - - static int seedValue = 5; - QJSValue example = scriptEngine->newObject(); - example.setProperty("someProperty", seedValue++); - return example; - } - - // second, register the module API provider with QML by calling this function in an initialization function. - ... - qmlRegisterModuleApi("Qt.example.qjsvalueApi", 1, 0, example_qjsvalue_module_api_provider); - ... - \endcode - - In order to use the registered module API in QML, you must import the module API. - \qml - import QtQuick 2.0 - import Qt.example.qjsvalueApi 1.0 as ExampleApi - Item { - id: root - property int someValue: ExampleApi.someProperty - } - \endqml - */ inline int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QDeclarativeEngine *, QJSEngine *)) { @@ -469,80 +427,6 @@ inline int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMi return QDeclarativePrivate::qmlregister(QDeclarativePrivate::ModuleApiRegistration, &api); } -/*! - This function may be used to register a module API provider \a callback in a particular \a uri - with a version specified in \a versionMajor and \a versionMinor. - - Installing a module API into a uri allows developers to provide arbitrary functionality - (methods and properties) in a namespace that doesn't necessarily contain elements. - - A module API may be either a QObject or a QJSValue. Only one module API provider - may be registered into any given namespace (combination of \a uri, \a majorVersion and \a minorVersion). - This function should be used to register a module API provider function which returns a QObject as a module API. - - A QObject module API must be imported with a qualifier, and that qualifier may be used as - the target in a \l Connections element or otherwise used as any other element id would. - One exception to this is that a QObject module API property may not be aliased (because the - module API qualifier does not identify an object within the same component as any other item). - - Usage: - \code - // first, define your QObject which provides the functionality. - class ModuleApiExample : public QObject - { - Q_OBJECT - Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) - - public: - ModuleApiExample(QObject* parent = 0) - : QObject(parent), m_someProperty(0) - { - } - - ~ModuleApiExample() {} - - Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; } - - int someProperty() const { return m_someProperty; } - void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); } - - signals: - void somePropertyChanged(int newValue); - - private: - int m_someProperty; - }; - - // second, define the module API provider function (callback). - static QObject *example_qobject_module_api_provider(QDeclarativeEngine *engine, QJSEngine *scriptEngine) - { - Q_UNUSED(engine) - Q_UNUSED(scriptEngine) - - ModuleApiExample *example = new ModuleApiExample(); - return example; - } - - // third, register the module API provider with QML by calling this function in an initialization function. - ... - qmlRegisterModuleApi("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider); - ... - \endcode - - In order to use the registered module API in QML, you must import the module API. - \qml - import QtQuick 2.0 - import Qt.example.qobjectApi 1.0 as ExampleApi - Item { - id: root - property int someValue: ExampleApi.someProperty - - Component.onCompleted: { - someValue = ExampleApi.doSomething() - } - } - \endqml - */ inline int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QDeclarativeEngine *, QJSEngine *)) { -- 1.7.2.5