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
--- /dev/null
+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}.
\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.
projects / platform / upstream / qtdeclarative.git / commitdiff