48 \class QDeclarativeExtensionPlugin |
48 \class QDeclarativeExtensionPlugin |
49 \brief The QDeclarativeExtensionPlugin class provides an abstract base for custom QML extension plugins. |
49 \brief The QDeclarativeExtensionPlugin class provides an abstract base for custom QML extension plugins. |
50 |
50 |
51 \ingroup plugins |
51 \ingroup plugins |
52 |
52 |
53 QDeclarativeExtensionPlugin is a plugin interface that makes it |
53 QDeclarativeExtensionPlugin is a plugin interface that makes it possible to |
54 possible to offer extensions that can be loaded dynamically into |
54 create QML extensions that can be loaded dynamically into QML applications. |
55 applications using the QDeclarativeEngine class. |
55 These extensions allow custom QML types to be made available to the QML engine. |
56 |
56 |
57 Writing a QML extension plugin is achieved by subclassing this |
57 To write a QML extension plugin: |
58 base class, reimplementing the pure virtual registerTypes() |
58 |
59 function, and exporting the class using the Q_EXPORT_PLUGIN2() |
59 \list |
60 macro. |
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{The qmldir file}{qmldir file} to describe the plugin |
|
64 \endlist |
61 |
65 |
62 QML extension plugins can be used to provide either application-specific or |
66 QML extension plugins can be used to provide either application-specific or |
63 library-like plugins. Library plugins should limit themselves to registering types, |
67 library-like plugins. Library plugins should limit themselves to registering types, |
64 as any manipulation of the engine's root context may cause conflicts |
68 as any manipulation of the engine's root context may cause conflicts |
65 or other issues in the library user's code. |
69 or other issues in the library user's code. |
66 |
70 |
67 See \l {Tutorial: Writing QML extensions with C++} for details on creating |
|
68 QML extensions, including how to build a plugin with with QDeclarativeExtensionPlugin. |
|
69 For a simple overview, see the \l{declarative/cppextensions/plugins}{plugins} example. |
|
70 |
|
71 Also see \l {How to Create Qt Plugins} for general Qt plugin documentation. |
|
72 |
71 |
73 \sa QDeclarativeEngine::importPlugin() |
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 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{The 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} |
74 */ |
125 */ |
75 |
126 |
76 /*! |
127 /*! |
77 \fn void QDeclarativeExtensionPlugin::registerTypes(const char *uri) |
128 \fn void QDeclarativeExtensionPlugin::registerTypes(const char *uri) |
78 |
129 |