src/qml/qml/qqmlextensionplugin.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtQml module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qqmlextensionplugin.h"
  43
  44 QT_BEGIN_NAMESPACE
  45
  46 /*!
  47     \since 5.0
  48     \inmodule QtQml
  49     \class QQmlExtensionPlugin
  50     \brief The QQmlExtensionPlugin class provides an abstract base for custom QML extension plugins.
  51
  52     \ingroup plugins
  53
  54     QQmlExtensionPlugin is a plugin interface that makes it possible to
  55     create QML extensions that can be loaded dynamically into QML applications.
  56     These extensions allow custom QML types to be made available to the QML engine.
  57
  58     To write a QML extension plugin:
  59
  60     \list
  61     \li Subclass QQmlExtensionPlugin, implement registerTypes() method
  62     to register types using qmlRegisterType(), and export the class using the Q_EXPORT_PLUGIN2() macro
  63     \li Write an appropriate project file for the plugin
  64     \li Create a \l{Module Definition qmldir Files}{qmldir file} to describe the plugin
  65     \endlist
  66
  67     QML extension plugins can be used to provide either application-specific or
  68     library-like plugins. Library plugins should limit themselves to registering types,
  69     as any manipulation of the engine's root context may cause conflicts
  70     or other issues in the library user's code.
  71
  72
  73     \section1 An example
  74
  75     Suppose there is a new \c TimeModel C++ class that should be made available
  76     as a new QML element. It provides the current time through \c hour and \c minute
  77     properties, like this:
  78
  79     \snippet examples/qml/plugins/plugin.cpp 0
  80     \dots
  81
  82     To make this class available as a QML type, create a plugin that registers
  83     this type with a specific \l {QML Modules}{module} using qmlRegisterType(). For this example the plugin
  84     module will be named \c TimeExample (as defined in the project
  85     file further below).
  86
  87     \snippet examples/qml/plugins/plugin.cpp plugin
  88     \codeline
  89     \snippet examples/qml/plugins/plugin.cpp export
  90
  91     This registers the \c TimeModel class with the 1.0 version of this
  92     plugin library, as a QML type called \c Time. The Q_ASSERT statement
  93     ensures the module is imported correctly by any QML components that use this plugin.
  94
  95     The project file defines the project as a plugin library and specifies
  96     it should be built into the \c imports/TimeExample directory:
  97
  98     \code
  99     TEMPLATE = lib
 100     CONFIG += qt plugin
 101     QT += qml
 102
 103     DESTDIR = imports/TimeExample
 104     TARGET = qmlqtimeexampleplugin
 105     ...
 106     \endcode
 107
 108     Finally, a \l{Module Definition qmldir Files}{qmldir file} is required in the \c imports/TimeExample directory
 109     that describes the plugin. This directory includes a \c Clock.qml file that
 110     should be bundled with the plugin, so it needs to be specified in the \c qmldir
 111     file:
 112
 113     \quotefile examples/qml/plugins/imports/TimeExample/qmldir
 114
 115     Once the project is built and installed, the new \c Time element can be
 116     used by any QML component that imports the \c TimeExample module:
 117
 118     \snippet examples/qml/plugins/plugins.qml 0
 119
 120     The full source code is available in the \l {qml/plugins}{plugins example}.
 121
 122     The \l {Writing QML Extensions with C++} tutorial also contains a chapter
 123     on creating QML plugins.
 124
 125     Note that the QtQuick 1 version is called QDeclarativeExtensionPlugin.
 126
 127     \sa QQmlEngine::importPlugin(), {How to Create Qt Plugins}
 128 */
 129
 130 /*!
 131     \fn void QQmlExtensionPlugin::registerTypes(const char *uri)
 132
 133     Registers the QML types in the given \a uri. Subclasses should implement
 134     this to call qmlRegisterType() for all types which are provided by the extension
 135     plugin.
 136
 137     The \a uri is an identifier for the plugin generated by the QML engine
 138     based on the name and path of the extension's plugin library.
 139 */
 140
 141 /*!
 142     Constructs a QML extension plugin with the given \a parent.
 143
 144     Note that this constructor is invoked automatically by the
 145     Q_EXPORT_PLUGIN2() macro, so there is no need for calling it
 146     explicitly.
 147 */
 148 QQmlExtensionPlugin::QQmlExtensionPlugin(QObject *parent)
 149     : QObject(parent)
 150 {
 151 }
 152
 153 /*!
 154   \internal
 155  */
 156 QQmlExtensionPlugin::~QQmlExtensionPlugin()
 157 {
 158 }
 159
 160 /*!
 161     \fn void QQmlExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)
 162
 163     Initializes the extension from the \a uri using the \a engine. Here an application
 164     plugin might, for example, expose some data or objects to QML,
 165     as context properties on the engine's root context.
 166 */
 167
 168 void QQmlExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)
 169 {
 170     Q_UNUSED(engine);
 171     Q_UNUSED(uri);
 172 }
 173
 174 QT_END_NAMESPACE