src/declarative/qml/qdeclarativeextensionplugin.cpp

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