diff options
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc | 85 | ||||
| -rw-r--r-- | src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc | 83 | ||||
| -rw-r--r-- | src/qml/qml/qqmlextensionplugin.cpp | 66 |
3 files changed, 85 insertions, 149 deletions
diff --git a/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc index 90e432a8ef..a2397b6cfb 100644 --- a/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc +++ b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc @@ -38,90 +38,7 @@ A module requires at least one type registered in order to be considered valid. - QQmlExtensionPlugin 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 1 - \li Subclass QQmlExtensionPlugin - \list - \li Use the Q_PLUGIN_METADATA() macro to register the plugin with - the Qt meta object system - \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method - and call qmlRegisterType() to register the types to be exported - by the plugin - \endlist - \li Write a project file for the plugin - \li Create a \l{Module Definition qmldir Files}{qmldir file} to - describe the plugin - \endlist - - QML extension plugins are for 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. - -\section1 Plugin Example - - Suppose there is a new \c TimeModel C++ class that should be made available - as a new QML type. It provides the current time through \c hour and \c minute - properties. - - \snippet qmlextensionplugins/plugin.cpp 0 - \dots - - To make this type available, we create a plugin class named \c QExampleQmlPlugin - which is a subclass of \l QQmlExtensionPlugin. It overrides the - \l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel - type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class - definition to register the plugin with the Qt meta object system using a unique - identifier for the plugin. - - \snippet qmlextensionplugins/plugin.cpp plugin - - The \c TimeModel class receives a \c{1.0} version of this plugin library, as - a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is - imported correctly by any QML components that use this plugin. The - \l{Defining QML Types from C++} article has more information about registering C++ - types into the runtime. - - For this example, the TimeExample source directory is in - \c{imports/TimeExample}. The plugin's type namespace will mirror - this structure, so the types are registered into the namespace - "TimeExample". - - Additionally, the project file, in a \c .pro file, defines the project as a plugin library, - specifies it should be built into the \c imports/TimeExample directory, and registers - the plugin target name and various other details: - - \code - TEMPLATE = lib - CONFIG += qt plugin - QT += qml - - DESTDIR = imports/TimeExample - TARGET = qmlqtimeexampleplugin - SOURCES += qexampleqmlplugin.cpp - \endcode - - Finally, a \l{Module Definition qmldir Files}{qmldir file} is required - in the \c imports/TimeExample directory to describe the plugin and the types that it - exports. The plugin includes a \c Clock.qml file along with the \c qmlqtimeexampleplugin - that is built by the project (as shown above in the \c .pro file) so both of these - need to be specified in the \c qmldir file: - - \quotefile qmlextensionplugins/imports/TimeExample/qmldir - - Once the project is built and installed, the new \c Time component is - accessible by any QML component that imports the \c TimeExample - module - - \snippet qmlextensionplugins/plugins.qml 0 - - The full source code is available in the \l {qmlextensionplugins}{plugins example}. - + \include qqmlextensionplugin.qdocinc \section1 Reference diff --git a/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc new file mode 100644 index 0000000000..9bb863a90b --- /dev/null +++ b/src/qml/doc/src/qmllanguageref/modules/qqmlextensionplugin.qdocinc @@ -0,0 +1,83 @@ +QQmlExtensionPlugin 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 1 +\li Subclass QQmlExtensionPlugin + \list + \li Use the Q_PLUGIN_METADATA() macro to register the plugin with + the Qt meta object system + \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method + and call qmlRegisterType() to register the types to be exported + by the plugin + \endlist +\li Write a project file for the plugin +\li Create a \l{Module Definition qmldir Files}{qmldir file} to + describe the plugin +\endlist + +QML extension plugins are for 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. + +\section1 Plugin Example + +Suppose there is a new \c TimeModel C++ class that should be made available +as a new QML type. It provides the current time through \c hour and \c minute +properties. + +\snippet qmlextensionplugins/plugin.cpp 0 +\dots + +To make this type available, we create a plugin class named \c QExampleQmlPlugin +which is a subclass of \l QQmlExtensionPlugin. It overrides the +\l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel +type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class +definition to register the plugin with the Qt meta object system using a unique +identifier for the plugin. + +\snippet qmlextensionplugins/plugin.cpp plugin + +The \c TimeModel class receives a \c{1.0} version of this plugin library, as +a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is +imported correctly by any QML components that use this plugin. The +\l{Defining QML Types from C++} article has more information about registering C++ +types into the runtime. + +For this example, the TimeExample source directory is in +\c{imports/TimeExample}. The plugin's type namespace will mirror +this structure, so the types are registered into the namespace +"TimeExample". + +Additionally, the project file, in a \c .pro file, defines the project as a plugin library, +specifies it should be built into the \c imports/TimeExample directory, and registers +the plugin target name and various other details: + +\code +TEMPLATE = lib +CONFIG += qt plugin +QT += qml + +DESTDIR = imports/TimeExample +TARGET = qmlqtimeexampleplugin +SOURCES += qexampleqmlplugin.cpp +\endcode + +Finally, a \l{Module Definition qmldir Files}{qmldir file} is required +in the \c imports/TimeExample directory to describe the plugin and the types that it +exports. The plugin includes a \c Clock.qml file along with the \c qmlqtimeexampleplugin +that is built by the project (as shown above in the \c .pro file) so both of these +need to be specified in the \c qmldir file: + +\quotefile qmlextensionplugins/imports/TimeExample/qmldir + +Once the project is built and installed, the new \c Time component is +accessible by any QML component that imports the \c TimeExample +module + +\snippet qmlextensionplugins/plugins.qml 0 + +The full source code is available in the \l {qmlextensionplugins}{plugins example}. diff --git a/src/qml/qml/qqmlextensionplugin.cpp b/src/qml/qml/qqmlextensionplugin.cpp index 7b560268ba..d86fbc5999 100644 --- a/src/qml/qml/qqmlextensionplugin.cpp +++ b/src/qml/qml/qqmlextensionplugin.cpp @@ -44,71 +44,7 @@ QT_BEGIN_NAMESPACE \ingroup plugins - QQmlExtensionPlugin 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 - \li Subclass QQmlExtensionPlugin, implement registerTypes() method to register types - using qmlRegisterType(), and export the class using the Q_PLUGIN_METADATA() macro - \li Write an appropriate project file for the plugin - \li Create a \l{Module Definition qmldir Files}{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. - - - \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 qmlextensionplugins/plugin.cpp 0 - \dots - - To make this class available as a QML type, create a plugin that registers - this type with a specific \l {QML Modules}{module} using qmlRegisterType(). For this example the plugin - module will be named \c TimeExample (as defined in the project - file further below). - - \snippet qmlextensionplugins/plugin.cpp plugin - - 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 imports/TimeExample directory: - - \code - TEMPLATE = lib - CONFIG += qt plugin - QT += qml - - DESTDIR = imports/TimeExample - TARGET = qmlqtimeexampleplugin - ... - \endcode - - Finally, a \l{Module Definition qmldir Files}{qmldir file} is required in the \c imports/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 qmlextensionplugins/imports/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 TimeExample module: - - \snippet qmlextensionplugins/plugins.qml 0 - - The full source code is available in the \l {qmlextensionplugins}{plugins example}. + \include qqmlextensionplugin.qdocinc The \l {Writing QML Extensions with C++} tutorial also contains a chapter on creating QML plugins. |