| /**************************************************************************** |
| ** |
| ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). |
| ** All rights reserved. |
| ** Contact: Nokia Corporation (qt-info@nokia.com) |
| ** |
| ** This file is part of the QtDeclarative module of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:LGPL$ |
| ** GNU Lesser General Public License Usage |
| ** This file may be used under the terms of the GNU Lesser General Public |
| ** License version 2.1 as published by the Free Software Foundation and |
| ** appearing in the file LICENSE.LGPL included in the packaging of this |
| ** file. Please review the following information to ensure the GNU Lesser |
| ** General Public License version 2.1 requirements will be met: |
| ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
| ** |
| ** In addition, as a special exception, Nokia gives you certain additional |
| ** rights. These rights are described in the Nokia Qt LGPL Exception |
| ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
| ** |
| ** GNU General Public License Usage |
| ** Alternatively, this file may be used under the terms of the GNU General |
| ** Public License version 3.0 as published by the Free Software Foundation |
| ** and appearing in the file LICENSE.GPL included in the packaging of this |
| ** file. Please review the following information to ensure the GNU General |
| ** Public License version 3.0 requirements will be met: |
| ** http://www.gnu.org/copyleft/gpl.html. |
| ** |
| ** Other Usage |
| ** Alternatively, this file may be used in accordance with the terms and |
| ** conditions contained in a signed written agreement between you and Nokia. |
| ** |
| ** |
| ** |
| ** |
| ** |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| #include "qdeclarativeextensionplugin.h" |
| |
| QT_BEGIN_NAMESPACE |
| |
| /*! |
| \since 4.7 |
| \class QDeclarativeExtensionPlugin |
| \brief The QDeclarativeExtensionPlugin class provides an abstract base for custom QML extension plugins. |
| |
| \ingroup plugins |
| |
| QDeclarativeExtensionPlugin is a plugin interface that makes it possible to |
| create QML extensions that can be loaded dynamically into QML applications. |
| These extensions allow custom QML types to be made available to the QML engine. |
| |
| To write a QML extension plugin: |
| |
| \list |
| \o Subclass QDeclarativeExtensionPlugin, implement registerTypes() method |
| to register types using qmlRegisterType(), and export the class using the Q_EXPORT_PLUGIN2() macro |
| \o Write an appropriate project file for the plugin |
| \o Create a \l{Writing a qmldir file}{qmldir file} to describe the plugin |
| \endlist |
| |
| QML extension plugins can be used to provide either application-specific or |
| library-like plugins. Library plugins should limit themselves to registering types, |
| as any manipulation of the engine's root context may cause conflicts |
| or other issues in the library user's code. |
| |
| |
| \section1 An example |
| |
| Suppose there is a new \c TimeModel C++ class that should be made available |
| as a new QML element. It provides the current time through \c hour and \c minute |
| properties, like this: |
| |
| \snippet examples/declarative/cppextensions/plugins/plugin.cpp 0 |
| \dots |
| |
| To make this class available as a QML type, create a plugin that registers |
| this type with a specific \l {QML Modules}{module} using qmlRegisterType(). For this example the plugin |
| module will be named \c com.nokia.TimeExample (as defined in the project |
| file further below). |
| |
| \snippet examples/declarative/cppextensions/plugins/plugin.cpp plugin |
| \codeline |
| \snippet examples/declarative/cppextensions/plugins/plugin.cpp export |
| |
| This registers the \c TimeModel class with the 1.0 version of this |
| plugin library, as a QML type called \c Time. The Q_ASSERT statement |
| ensures the module is imported correctly by any QML components that use this plugin. |
| |
| The project file defines the project as a plugin library and specifies |
| it should be built into the \c com/nokia/TimeExample directory: |
| |
| \code |
| TEMPLATE = lib |
| CONFIG += qt plugin |
| QT += declarative |
| |
| DESTDIR = com/nokia/TimeExample |
| TARGET = qmlqtimeexampleplugin |
| ... |
| \endcode |
| |
| Finally, a \l{Writing a qmldir file}{qmldir file} is required in the \c com/nokia/TimeExample directory |
| that describes the plugin. This directory includes a \c Clock.qml file that |
| should be bundled with the plugin, so it needs to be specified in the \c qmldir |
| file: |
| |
| \quotefile examples/declarative/cppextensions/plugins/com/nokia/TimeExample/qmldir |
| |
| Once the project is built and installed, the new \c Time element can be |
| used by any QML component that imports the \c com.nokia.TimeExample module: |
| |
| \snippet examples/declarative/cppextensions/plugins/plugins.qml 0 |
| |
| The full source code is available in the \l {declarative/cppextensions/plugins}{plugins example}. |
| |
| The \l {Tutorial: Writing QML extensions with C++} also contains a chapter |
| on creating QML plugins. |
| |
| \sa QDeclarativeEngine::importPlugin(), {How to Create Qt Plugins} |
| */ |
| |
| /*! |
| \fn void QDeclarativeExtensionPlugin::registerTypes(const char *uri) |
| |
| Registers the QML types in the given \a uri. Subclasses should implement |
| this to call qmlRegisterType() for all types which are provided by the extension |
| plugin. |
| |
| The \a uri is an identifier for the plugin generated by the QML engine |
| based on the name and path of the extension's plugin library. |
| */ |
| |
| /*! |
| Constructs a QML extension plugin with the given \a parent. |
| |
| Note that this constructor is invoked automatically by the |
| Q_EXPORT_PLUGIN2() macro, so there is no need for calling it |
| explicitly. |
| */ |
| QDeclarativeExtensionPlugin::QDeclarativeExtensionPlugin(QObject *parent) |
| : QObject(parent) |
| { |
| } |
| |
| /*! |
| \internal |
| */ |
| QDeclarativeExtensionPlugin::~QDeclarativeExtensionPlugin() |
| { |
| } |
| |
| /*! |
| \fn void QDeclarativeExtensionPlugin::initializeEngine(QDeclarativeEngine *engine, const char *uri) |
| |
| Initializes the extension from the \a uri using the \a engine. Here an application |
| plugin might, for example, expose some data or objects to QML, |
| as context properties on the engine's root context. |
| */ |
| |
| void QDeclarativeExtensionPlugin::initializeEngine(QDeclarativeEngine *engine, const char *uri) |
| { |
| Q_UNUSED(engine); |
| Q_UNUSED(uri); |
| } |
| |
| QT_END_NAMESPACE |