1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
29 \page qtqml-modules-cppplugins.html
30 \title Creating C++ Plugins for QML
31 \brief Description of how to write C++ plugins for QML
33 \section1 Creating a Plugin
35 The \l{QQmlEngine}{QML engine} load C++ plugins for QML.
36 Such plugins are usually provided in a QML extension module, and can
37 provide types and functionality for use by clients in QML documents
38 which import the module.
40 QQmlExtensionPlugin is a plugin interface that makes it possible to
41 create QML extensions that can be loaded dynamically into QML applications.
42 These extensions allow custom QML types to be made available to the
45 To write a QML extension plugin:
47 \li Subclass QQmlExtensionPlugin
49 \li Use the Q_PLUGIN_METADATA() macro to register the plugin with
50 the Qt meta object system
51 \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method
52 and call qmlRegisterType() to register the types to be exported
55 \li Write a project file for the plugin
56 \li Create a \l{Module Definition qmldir Files}{qmldir file} to
60 QML extension plugins are for either application-specific or library-like
61 plugins. Library plugins should limit themselves to registering types, as
62 any manipulation of the engine's root context may cause conflicts or other
63 issues in the library user's code.
65 \section1 Plugin Example
67 Suppose there is a new \c TimeModel C++ class that should be made available
68 as a new QML element. It provides the current time through \c hour and \c minute
71 \snippet examples/qml/cppextensions/plugins/plugin.cpp 0
74 To make this type available, we create a plugin class named \c QExampleQmlPlugin
75 which is a subclass of \l QQmlExtensionPlugin. It overrides the
76 \l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel
77 type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class
78 definition to register the plugin with the Qt meta object system using a unique
79 identifier for the plugin.
81 \snippet examples/qml/cppextensions/plugins/plugin.cpp plugin
83 The \c TimeModel class receives a \c{1.0} version of this plugin library, as
84 a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is
85 imported correctly by any QML components that use this plugin. The
86 \l{Defining QML Types from C++} article has more information about registering C++
87 types into the runtime.
89 For this example, the TimeExample source directory is in
90 \c{com/nokia/TimeExample}. The plugin's type namespace will mirror
91 this structure, so the types are registered into the namespace
92 "com.nokia.TimeExample".
94 Additionally, the project file, in a \c .pro file, defines the project as a plugin library,
95 specifies it should be built into the \c com/nokia/TimeExample directory, and registers
96 the plugin target name and various other details:
103 DESTDIR = com/nokia/TimeExample
104 TARGET = qmlqtimeexampleplugin
105 SOURCES += qexampleqmlplugin.cpp
108 Finally, a \l{Module Definition qmldir Files}{qmldir file} is required
109 in the \c com/nokia/TimeExample directory to describe the plugin and the types that it
110 exports. The plugin includes a \c Clock.qml file along with the \c qmlqtimeexampleplugin
111 that is built by the project (as shown above in the \c .pro file) so both of these
112 need to be specified in the \c qmldir file:
114 \quotefile examples/qml/cppextensions/plugins/com/nokia/TimeExample/qmldir
116 Once the project is built and installed, the new \c Time component is
117 accessible by any QML component that imports the \c com.nokia.TimeExample
120 \snippet examples/qml/cppextensions/plugins/plugins.qml 0
122 The full source code is available in the \l {qml/cppextensions/plugins}{plugins example}.
128 \li \l {Writing QML Extensions with C++} - contains a chapter
129 on creating QML plugins.
130 \li \l{Defining QML Types from C++} - information about registering C++ types into
132 \li \l{How to Create Qt Plugins} - information about Qt plugins