← Back to branch summary

~saviq/ubuntu/saucy/qtdeclarative-opensource-src/add-qtquick-delegate-range

« back to all changes in this revision

Viewing changes to src/qml/qml/qqmlextensionplugin.cpp

  • Committer: Package Import Robot
  • Author(s): Timo Jyrinki
  • Date: 2013-02-05 14:17:19 UTC
  • Revision ID: package-import@ubuntu.com-20130205141719-qqeyml8wslpyez52
Tags: upstream-5.0.1
Import upstream version 5.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
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 to register types
 
62
    using qmlRegisterType(), and export the class using the Q_PLUGIN_METADATA() 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 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 plugins/plugin.cpp plugin
 
88
 
 
89
    This registers the \c TimeModel class with the 1.0 version of this 
 
90
    plugin library, as a QML type called \c Time. The Q_ASSERT statement 
 
91
    ensures the module is imported correctly by any QML components that use this plugin.
 
92
 
 
93
    The project file defines the project as a plugin library and specifies 
 
94
    it should be built into the \c imports/TimeExample directory:
 
95
 
 
96
    \code
 
97
    TEMPLATE = lib
 
98
    CONFIG += qt plugin
 
99
    QT += qml
 
100
 
 
101
    DESTDIR = imports/TimeExample
 
102
    TARGET = qmlqtimeexampleplugin
 
103
    ...
 
104
    \endcode    
 
105
 
 
106
    Finally, a \l{Module Definition qmldir Files}{qmldir file} is required in the \c imports/TimeExample directory
 
107
    that describes the plugin. This directory includes a \c Clock.qml file that
 
108
    should be bundled with the plugin, so it needs to be specified in the \c qmldir
 
109
    file:
 
110
 
 
111
    \quotefile plugins/imports/TimeExample/qmldir
 
112
 
 
113
    Once the project is built and installed, the new \c Time element can be 
 
114
    used by any QML component that imports the \c TimeExample module:
 
115
 
 
116
    \snippet plugins/plugins.qml 0
 
117
 
 
118
    The full source code is available in the \l {qml/plugins}{plugins example}.
 
119
 
 
120
    The \l {Writing QML Extensions with C++} tutorial also contains a chapter
 
121
    on creating QML plugins.
 
122
 
 
123
    Note that the QtQuick 1 version is called QDeclarativeExtensionPlugin.
 
124
 
 
125
    \sa QQmlEngine::importPlugin(), {How to Create Qt Plugins}
 
126
*/
 
127
 
 
128
/*!
 
129
    \fn void QQmlExtensionPlugin::registerTypes(const char *uri)
 
130
 
 
131
    Registers the QML types in the given \a uri. Subclasses should implement
 
132
    this to call qmlRegisterType() for all types which are provided by the extension
 
133
    plugin.
 
134
 
 
135
    The \a uri is an identifier for the plugin generated by the QML engine
 
136
    based on the name and path of the extension's plugin library. 
 
137
*/
 
138
 
 
139
/*!
 
140
    Constructs a QML extension plugin with the given \a parent.
 
141
 
 
142
    Note that this constructor is invoked automatically by the
 
143
    Q_PLUGIN_METADATA() macro, so there is no need for calling it
 
144
    explicitly.
 
145
*/
 
146
QQmlExtensionPlugin::QQmlExtensionPlugin(QObject *parent)
 
147
    : QObject(parent)
 
148
{
 
149
}
 
150
 
 
151
/*!
 
152
  \internal
 
153
 */
 
154
QQmlExtensionPlugin::~QQmlExtensionPlugin()
 
155
{
 
156
}
 
157
 
 
158
/*!
 
159
    \fn void QQmlExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)
 
160
 
 
161
    Initializes the extension from the \a uri using the \a engine. Here an application
 
162
    plugin might, for example, expose some data or objects to QML,
 
163
    as context properties on the engine's root context.
 
164
*/
 
165
 
 
166
void QQmlExtensionPlugin::initializeEngine(QQmlEngine *engine, const char *uri)
 
167
{
 
168
    Q_UNUSED(engine);
 
169
    Q_UNUSED(uri);
 
170
}
 
171
 
 
172
QT_END_NAMESPACE