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
48 \li Implement QQmlExtensionPlugin's
49 \l{QQmlExtensionPlugin::}{registerTypes()} method
50 \li Register types with qmlRegisterType()
51 \li Export the class using the Q_EXPORT_PLUGIN2() macro
52 \li Write a project file for the plugin
53 \li Create a \l{Syntax of a qmldir file}{qmldir file} to describe the plugin
56 QML extension plugins are for either application-specific or library-like
57 plugins. Library plugins should limit themselves to registering types, as
58 any manipulation of the engine's root context may cause conflicts or other
59 issues in the library user's code.
61 \section1 Plugin Example
63 Suppose there is a new \c TimeModel C++ class that should be made available
64 as a new QML element. It provides the current time through \c hour and \c minute
67 \snippet examples/qml/cppextensions/plugins/plugin.cpp 0
70 A plugin class, \c QExampleQMLPlugin, is a subclass of
71 \l QQmlExtensionPlugin and it implements the
72 \l{QQmlExtensionPlugin::}{registerTypes()} method.
74 In the registerTypes() method, the plugin class can
75 register the \c TimeModel class to the declarative
76 runtime with the qmlRegisterType() function. The Q_EXPORT_PLUGIN2() macro has
77 two parameters, the generated plugin name and the class name.
79 \snippet examples/qml/cppextensions/plugins/plugin.cpp plugin
81 \snippet examples/qml/cppextensions/plugins/plugin.cpp export
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 module is
85 imported correctly by any QML components that use this plugin. The
86 \l{Defining QML Object 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 module import statement will follow
93 The project file, in a \c .pro file, defines the project as a plugin library
94 and specifies it should be built into the \c com/nokia/TimeExample
102 DESTDIR = com/nokia/TimeExample
103 TARGET = qmlqtimeexampleplugin
107 Finally, a \l{Syntax of a qmldir file}{qmldir file} is required in the \c
108 com/nokia/TimeExample directory to specify the plugin. This directory
109 includes a \c Clock.qml file that should be bundled with the plugin, so it
110 needs to be specified in the \c qmldir file:
112 \quotefile examples/qml/cppextensions/plugins/com/nokia/TimeExample/qmldir
114 Once the project is built and installed, the new \c Time component is
115 accessible by any QML component that imports the \c com.nokia.TimeExample
118 \snippet examples/qml/cppextensions/plugins/plugins.qml 0
120 The full source code is available in the \l {qml/cppextensions/plugins}{plugins example}.
126 \li \l {Tutorial: Extending QML with C++} - contains a chapter
127 on creating QML plugins.
128 \li \l{Defining QML Object Types from C++} - information about registering C++ types into
130 \li \l{How to Create Qt Plugins} - information about Qt plugins