From 2c6312bcb2a80431e6f0cf16d6c4c1d016d40b03 Mon Sep 17 00:00:00 2001 From: Bea Lam Date: Wed, 21 Jul 2010 15:27:32 +1000 Subject: Expand QDeclarativeExtensionPlugin docs --- .../declarative/cppextensions/plugins/plugin.cpp | 6 ++ .../declarative/cppextensions/plugins/plugins.qml | 3 +- .../qml/qdeclarativeextensionplugin.cpp | 77 ++++++++++++++++++---- 3 files changed, 73 insertions(+), 13 deletions(-) diff --git a/examples/declarative/cppextensions/plugins/plugin.cpp b/examples/declarative/cppextensions/plugins/plugin.cpp index 355ca3f..01d5361 100644 --- a/examples/declarative/cppextensions/plugins/plugin.cpp +++ b/examples/declarative/cppextensions/plugins/plugin.cpp @@ -96,11 +96,13 @@ private: QBasicTimer timer; }; +//![0] class TimeModel : public QObject { Q_OBJECT Q_PROPERTY(int hour READ hour NOTIFY timeChanged) Q_PROPERTY(int minute READ minute NOTIFY timeChanged) +//![0] public: TimeModel(QObject *parent=0) : QObject(parent) @@ -135,6 +137,7 @@ private: int TimeModel::instances=0; MinuteTimer *TimeModel::timer=0; +//![plugin] class QExampleQmlPlugin : public QDeclarativeExtensionPlugin { Q_OBJECT @@ -145,7 +148,10 @@ public: qmlRegisterType(uri, 1, 0, "Time"); } }; +//![plugin] #include "plugin.moc" +//![export] Q_EXPORT_PLUGIN2(qmlqtimeexampleplugin, QExampleQmlPlugin); +//![export] diff --git a/examples/declarative/cppextensions/plugins/plugins.qml b/examples/declarative/cppextensions/plugins/plugins.qml index 1832017..8d1085c 100644 --- a/examples/declarative/cppextensions/plugins/plugins.qml +++ b/examples/declarative/cppextensions/plugins/plugins.qml @@ -37,7 +37,7 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - +//![0] import com.nokia.TimeExample 1.0 // import types from the plugin Clock { // this class is defined in QML (com/nokia/TimeExample/Clock.qml) @@ -49,3 +49,4 @@ Clock { // this class is defined in QML (com/nokia/TimeExample/Clock.qml) hours: time.hour minutes: time.minute } +//![0] diff --git a/src/declarative/qml/qdeclarativeextensionplugin.cpp b/src/declarative/qml/qdeclarativeextensionplugin.cpp index 0660599..448fde2 100644 --- a/src/declarative/qml/qdeclarativeextensionplugin.cpp +++ b/src/declarative/qml/qdeclarativeextensionplugin.cpp @@ -50,23 +50,76 @@ QT_BEGIN_NAMESPACE \ingroup plugins - QDeclarativeExtensionPlugin is a plugin interface that makes it - possible to offer extensions that can be loaded dynamically into - applications using the QDeclarativeEngine class. - - Writing a QML extension plugin is achieved by subclassing this - base class, reimplementing the pure virtual registerTypes() - function, and exporting the class using the Q_EXPORT_PLUGIN2() - macro. + QDeclarativeExtensionPlugin is a plugin interface that makes it possible to + create QML extensions that can be loaded dynamically into QML applications. + These extensions allow custom QML types to be made available to the QML engine. + + To write a QML extension plugin: + + \list + \o Subclass QDeclarativeExtensionPlugin, implement registerTypes() method + to register types using qmlRegisterType(), and export the class using the Q_EXPORT_PLUGIN2() macro + \o Write an appropriate project file for the plugin + \o Create a \l{The qmldir file}{qmldir file} to describe the plugin + \endlist QML extension plugins can be used to provide either application-specific or library-like plugins. Library plugins should limit themselves to registering types, as any manipulation of the engine's root context may cause conflicts or other issues in the library user's code. - See \l {Tutorial: Writing QML extensions with C++} for details on creating - QML extensions, including how to build a plugin with with QDeclarativeExtensionPlugin. - For a simple overview, see the \l{declarative/cppextensions/plugins}{plugins} example. + + \section1 An example + + Suppose there is a new \c TimeModel C++ class that should be made available + as a new QML element. It provides the current time through \c hour and \c minute + properties, like this: + + \snippet examples/declarative/cppextensions/plugins/plugin.cpp 0 + \dots + + To make this class available as a QML type, create a plugin that registers + this type using qmlRegisterType(). For this example the plugin + module will be named \c com.nokia.TimeExample (as defined in the project + file further below). + + \snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin + \codeline + \snippet examples/declarative/cppextensions/plugins/plugin.cpp export + + This registers the \c TimeModel class with the 1.0 version of this + plugin library, as a QML type called \c Time. The Q_ASSERT statement + ensures the module is imported correctly by any QML components that use this plugin. + + The project file defines the project as a plugin library and specifies + it should be built into the \c com/nokia/TimeExample directory: + + \code + TEMPLATE = lib + CONFIG += qt plugin + QT += declarative + + DESTDIR = com/nokia/TimeExample + TARGET = qmlqtimeexampleplugin + ... + \endcode + + Finally, a \l{The qmldir file}{qmldir file} is required in the \c com/nokia/TimeExample directory + that describes the plugin. This directory includes a \c Clock.qml file that + should be bundled with the plugin, so it needs to be specified in the \c qmldir + file: + + \quotefile examples/declarative/cppextensions/plugins/com/nokia/TimeExample/qmldir + + Once the project is built and installed, the new \c Time element can be + used by any QML component that imports the \c com.nokia.TimeExample module: + + \snippet examples/declarative/cppextensions/plugins/plugins.qml 0 + + The full source code is available in the \l {declarative/cppextensions/plugins}{plugins example}. + + The \l {Tutorial: Writing QML extensions with C++} also contains a chapter + on creating QML plugins. \sa QDeclarativeEngine::importPlugin(), {How to Create Qt Plugins} */ @@ -95,7 +148,7 @@ QDeclarativeExtensionPlugin::QDeclarativeExtensionPlugin(QObject *parent) } /*! - Destroys the plugin. + \internal */ QDeclarativeExtensionPlugin::~QDeclarativeExtensionPlugin() { -- cgit v0.12