From 1b0bcbbe749529c9b3c37f79f9535293544c4fbb Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 27 Mar 2012 15:20:42 +0200 Subject: [PATCH] Doc: Fixing the Qt QML module page. Change-Id: I0efffbab650423a78de437459c9060594f895f37 Reviewed-by: Alan Alpert --- doc/src/qml/qtdeclarative.qdoc | 371 ---------------------------------------- doc/src/qml/qtqml.qdoc | 371 ++++++++++++++++++++++++++++++++++++++++ src/qml/qml/qqmllist.cpp | 2 +- 3 files changed, 372 insertions(+), 372 deletions(-) delete mode 100644 doc/src/qml/qtdeclarative.qdoc create mode 100644 doc/src/qml/qtqml.qdoc diff --git a/doc/src/qml/qtdeclarative.qdoc b/doc/src/qml/qtdeclarative.qdoc deleted file mode 100644 index 5ad637a..0000000 --- a/doc/src/qml/qtdeclarative.qdoc +++ /dev/null @@ -1,371 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtQml - \title Qt Qml Module - \ingroup modules - - \brief The Qt Qml module provides a declarative framework - for building highly dynamic, custom user interfaces. - - To include the definitions of the module's classes, use the - following directive: - - \code - #include - \endcode - - To link against the module, add this line to your \l qmake \c - .pro file: - - \code - QT += qml - \endcode - - For more information on the Qt Qml module (including the visual - elements which are implemented on top of the Qt Qml module) see the - \l{Qt Quick} documentation. -*/ - - -/*! - \macro QML_DECLARE_TYPE() - \relates QQmlEngine - - Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty) - - #include to use this macro. -*/ - -/*! - \macro QML_DECLARE_TYPEINFO(Type,Flags) - \relates QQmlEngine - - Declares additional properties of the given \a Type as described by the - specified \a Flags. - - Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which - declares that the \a Type supports \l {Attached Properties}. - - #include to use this macro. -*/ - - -/*! - \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) - \relates QQmlEngine - - This template function registers the C++ type in the QML system with - the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor. - - Returns the QML type id. - - There are two forms of this template function: - - \code - template - int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); - - template - int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); - \endcode - - The former is the standard form which registers the type \e T as a new type. - The latter allows a particular revision of a class to be registered in - a specified version (see \l {QML Type Versioning}). - - - For example, this registers a C++ class \c MySliderItem as a QML type - named \c Slider for version 1.0 of a \l{QML Modules}{module} called - "com.mycompany.qmlcomponents": - - \code - #include - - ... - - qmlRegisterType("com.mycompany.qmlcomponents", 1, 0, "Slider"); - \endcode - - Once this is registered, the type can be used in QML by importing the - specified module name and version number: - - \qml - import com.mycompany.qmlcomponents 1.0 - - Slider { - // ... - } - \endqml - - Note that it's perfectly reasonable for a library to register types to older versions - than the actual version of the library. Indeed, it is normal for the new library to allow - QML written to previous versions to continue to work, even if more advanced versions of - some of its types are available. -*/ - -/*! - \fn int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) - \relates QQmlEngine - - This template function registers the specified revision of a C++ type in the QML system with - the library imported from \a uri having the version number composed - from \a versionMajor and \a versionMinor. - - Returns the QML type id. - - \code - template - int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor); - \endcode - - This function is typically used to register the revision of a base class to - use for the specified module version (see \l {QML Type Versioning}). -*/ - -/*! - \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) - \relates QQmlEngine - - This template function registers the C++ type in the QML system with - the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor. - - While the type has a name and a type, it cannot be created, and the - given error \a message will result if creation is attempted. - - This is useful where the type is only intended for providing attached properties or enum values. - - Returns the QML type id. - - #include to use this function. - - \sa qmlRegisterTypeNotAvailable() -*/ - -/*! - \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) - \relates QQmlEngine - - This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type - will produce the given error \a message. - - Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should - at least "reserve" the QML type name, and give the user of your module a meaningful error message. - - Returns the QML type id. - - Example: - - \code - #ifdef NO_GAMES_ALLOWED - qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!"); - #else - qmlRegisterType("MinehuntCore", 0, 1, "Game"); - #endif - \endcode - - This will cause any QML which uses this module and attempts to use the type to produce an error message: - \code - fun.qml: Get back to work, slacker! - Game { - ^ - \endcode - - Without this, a generic "Game is not a type" message would be given. - - #include to use this function. - - \sa qmlRegisterUncreatableType() -*/ - -/*! - \fn int qmlRegisterType() - \relates QQmlEngine - \overload - - This template function registers the C++ type in the QML - system. Instances of this type cannot be created from the QML - system. - - #include to use this function. - - Returns the QML type id. -*/ - -/*! - \fn int qmlRegisterInterface(const char *typeName) - \relates QQmlEngine - - This template function registers the C++ type in the QML system - under the name \a typeName. - - #include to use this function. - - Returns the QML type id. -*/ - -/*! - \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QQmlEngine *, QJSEngine *)) - \relates QQmlEngine - - 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. - - \b{NOTE:} QJSValue module API properties will \b{not} trigger binding re-evaluation if changed. - - Usage: - \code - // first, define the module API provider function (callback). - static QJSValue *example_qjsvalue_module_api_provider(QQmlEngine *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 - */ - -/*! - \internal - \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *)) - \deprecated - - Any uses of a module API in a binding where that module API was registered with this - function instead of the template version will result in suboptimal binding generation. - */ - -/*! - \fn template int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *)) - \relates QQmlEngine - - 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 - of the given type T 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). - - \b{NOTE:} A QObject module API instance returned from a module API provider is owned by the QML - engine. For this reason, the module API provider function should \b{not} be implemented as a - singleton factory. - - 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(QQmlEngine *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/doc/src/qml/qtqml.qdoc b/doc/src/qml/qtqml.qdoc new file mode 100644 index 0000000..7bd797e --- /dev/null +++ b/doc/src/qml/qtqml.qdoc @@ -0,0 +1,371 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtQml + \title Qt QML Module + \ingroup modules + + \brief The Qt QML module provides a declarative framework + for building highly dynamic, custom user interfaces. + + To include the definitions of the module's classes, use the + following directive: + + \code + #include + \endcode + + To link against the module, add this line to your \l qmake \c + .pro file: + + \code + QT += qml + \endcode + + For more information on the Qt QML module (including the visual + elements which are implemented on top of the Qt QML module) see the + \l{Qt Quick} documentation. +*/ + + +/*! + \macro QML_DECLARE_TYPE() + \relates QQmlEngine + + Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty) + + #include to use this macro. +*/ + +/*! + \macro QML_DECLARE_TYPEINFO(Type,Flags) + \relates QQmlEngine + + Declares additional properties of the given \a Type as described by the + specified \a Flags. + + Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which + declares that the \a Type supports \l {Attached Properties}. + + #include to use this macro. +*/ + + +/*! + \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + \relates QQmlEngine + + This template function registers the C++ type in the QML system with + the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor. + + Returns the QML type id. + + There are two forms of this template function: + + \code + template + int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); + + template + int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); + \endcode + + The former is the standard form which registers the type \e T as a new type. + The latter allows a particular revision of a class to be registered in + a specified version (see \l {QML Type Versioning}). + + + For example, this registers a C++ class \c MySliderItem as a QML type + named \c Slider for version 1.0 of a \l{QML Modules}{module} called + "com.mycompany.qmlcomponents": + + \code + #include + + ... + + qmlRegisterType("com.mycompany.qmlcomponents", 1, 0, "Slider"); + \endcode + + Once this is registered, the type can be used in QML by importing the + specified module name and version number: + + \qml + import com.mycompany.qmlcomponents 1.0 + + Slider { + // ... + } + \endqml + + Note that it's perfectly reasonable for a library to register types to older versions + than the actual version of the library. Indeed, it is normal for the new library to allow + QML written to previous versions to continue to work, even if more advanced versions of + some of its types are available. +*/ + +/*! + \fn int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) + \relates QQmlEngine + + This template function registers the specified revision of a C++ type in the QML system with + the library imported from \a uri having the version number composed + from \a versionMajor and \a versionMinor. + + Returns the QML type id. + + \code + template + int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor); + \endcode + + This function is typically used to register the revision of a base class to + use for the specified module version (see \l {QML Type Versioning}). +*/ + +/*! + \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \relates QQmlEngine + + This template function registers the C++ type in the QML system with + the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor. + + While the type has a name and a type, it cannot be created, and the + given error \a message will result if creation is attempted. + + This is useful where the type is only intended for providing attached properties or enum values. + + Returns the QML type id. + + #include to use this function. + + \sa qmlRegisterTypeNotAvailable() +*/ + +/*! + \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \relates QQmlEngine + + This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type + will produce the given error \a message. + + Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should + at least "reserve" the QML type name, and give the user of your module a meaningful error message. + + Returns the QML type id. + + Example: + + \code + #ifdef NO_GAMES_ALLOWED + qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!"); + #else + qmlRegisterType("MinehuntCore", 0, 1, "Game"); + #endif + \endcode + + This will cause any QML which uses this module and attempts to use the type to produce an error message: + \code + fun.qml: Get back to work, slacker! + Game { + ^ + \endcode + + Without this, a generic "Game is not a type" message would be given. + + #include to use this function. + + \sa qmlRegisterUncreatableType() +*/ + +/*! + \fn int qmlRegisterType() + \relates QQmlEngine + \overload + + This template function registers the C++ type in the QML + system. Instances of this type cannot be created from the QML + system. + + #include to use this function. + + Returns the QML type id. +*/ + +/*! + \fn int qmlRegisterInterface(const char *typeName) + \relates QQmlEngine + + This template function registers the C++ type in the QML system + under the name \a typeName. + + #include to use this function. + + Returns the QML type id. +*/ + +/*! + \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QQmlEngine *, QJSEngine *)) + \relates QQmlEngine + + 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. + + \b{NOTE:} QJSValue module API properties will \b{not} trigger binding re-evaluation if changed. + + Usage: + \code + // first, define the module API provider function (callback). + static QJSValue *example_qjsvalue_module_api_provider(QQmlEngine *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 + */ + +/*! + \internal + \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *)) + \deprecated + + Any uses of a module API in a binding where that module API was registered with this + function instead of the template version will result in suboptimal binding generation. + */ + +/*! + \fn template int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *)) + \relates QQmlEngine + + 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 + of the given type T 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). + + \b{NOTE:} A QObject module API instance returned from a module API provider is owned by the QML + engine. For this reason, the module API provider function should \b{not} be implemented as a + singleton factory. + + 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(QQmlEngine *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/qml/qml/qqmllist.cpp b/src/qml/qml/qqmllist.cpp index ad28e38..c3537da 100644 --- a/src/qml/qml/qqmllist.cpp +++ b/src/qml/qml/qqmllist.cpp @@ -88,7 +88,7 @@ void QQmlListReferencePrivate::release() /*! \class QQmlListReference \since 5.0 -\module QtQml +\inmodule QtQml \brief The QQmlListReference class allows the manipulation of QQmlListProperty properties. QQmlListReference allows C++ programs to read from, and assign values to a QML list property in a -- 1.7.2.5