src/qml/doc/src/modules/cppplugins.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   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
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qtqml-modules-cppplugins.html
  30 \title Creating C++ Plugins for QML
  31 \brief Description of how to write C++ plugins for QML
  32
  33 \section1 Creating a Plugin
  34
  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.
  39
  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
  43     QML engine.
  44
  45     To write a QML extension plugin:
  46     \list 1
  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
  54     \endlist
  55
  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.
  60
  61 \section1 Plugin Example
  62
  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
  65     properties.
  66
  67     \snippet examples/qml/cppextensions/plugins/plugin.cpp 0
  68     \dots
  69
  70     A plugin class, \c QExampleQMLPlugin, is a subclass of
  71     \l QQmlExtensionPlugin and it implements the
  72     \l{QQmlExtensionPlugin::}{registerTypes()} method.
  73
  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.
  78
  79     \snippet examples/qml/cppextensions/plugins/plugin.cpp plugin
  80     \codeline
  81     \snippet examples/qml/cppextensions/plugins/plugin.cpp export
  82
  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.
  88
  89     For this example, the TimeExample source directory is in
  90     \c{com/nokia/TimeExample}. The plugin's module import statement will follow
  91     this structure.
  92
  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
  95     directory:
  96
  97     \code
  98     TEMPLATE = lib
  99     CONFIG += qt plugin
 100     QT += declarative
 101
 102     DESTDIR = com/nokia/TimeExample
 103     TARGET = qmlqtimeexampleplugin
 104     ...
 105     \endcode
 106
 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:
 111
 112     \quotefile examples/qml/cppextensions/plugins/com/nokia/TimeExample/qmldir
 113
 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
 116     module
 117
 118     \snippet examples/qml/cppextensions/plugins/plugins.qml 0
 119
 120     The full source code is available in the \l {qml/cppextensions/plugins}{plugins example}.
 121
 122
 123 \section1 Reference
 124
 125     \list
 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
 129     the runtime.
 130     \li \l{How to Create Qt Plugins} - information about Qt plugins
 131     \endlist
 132
 133
 134 */