|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 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 documentation 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 /*! |
|
43 \example tools/echoplugin |
|
44 \title Echo Plugin Example |
|
45 |
|
46 This example shows how to create a Qt plugin. |
|
47 |
|
48 \image echopluginexample.png |
|
49 |
|
50 There are two kinds of plugins in Qt: plugins that extend Qt |
|
51 itself and plugins that extend applications written in Qt. In this |
|
52 example, we show the procedure of implementing plugins that extend |
|
53 applications. When you create a plugin you declare an interface, |
|
54 which is a class with only pure virtual functions. This interface |
|
55 is inherited by the class that implements the plugin. The class is |
|
56 stored in a shared library and can therefore be loaded by |
|
57 applications at run-time. When loaded, the plugin is dynamically |
|
58 cast to the interface using Qt's \l{Meta-Object |
|
59 System}{meta-object system}. The plugin \l{How to Create Qt |
|
60 Plugins}{overview document} gives a high-level introduction to |
|
61 plugins. |
|
62 |
|
63 We have implemented a plugin, the \c EchoPlugin, which implements |
|
64 the \c EchoInterface. The interface consists of \c echo(), which |
|
65 takes a QString as argument. The \c EchoPlugin returns the string |
|
66 unaltered (i.e., it works as the familiar echo command found in |
|
67 both Unix and Windows). |
|
68 |
|
69 We test the plugin in \c EchoWindow: when you push the QPushButton |
|
70 (as seen in the image above), the application sends the text in |
|
71 the QLineEdit to the plugin, which echoes it back to the |
|
72 application. The answer from the plugin is displayed in the |
|
73 QLabel. |
|
74 |
|
75 |
|
76 \section1 EchoWindow Class Definition |
|
77 |
|
78 The \c EchoWindow class lets us test the \c EchoPlugin through a |
|
79 GUI. |
|
80 |
|
81 \snippet examples/tools/echoplugin/echowindow/echowindow.h 0 |
|
82 |
|
83 We load the plugin in \c loadPlugin() and cast it to \c |
|
84 EchoInterface. When the user clicks the \c button we take the |
|
85 text in \c lineEdit and call the interface's \c echo() with it. |
|
86 |
|
87 |
|
88 \section1 EchoWindow Class Implementation |
|
89 |
|
90 We start with a look at the constructor: |
|
91 |
|
92 \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 0 |
|
93 |
|
94 We create the widgets and set a title for the window. We then load |
|
95 the plugin. \c loadPlugin() returns false if the plugin could not |
|
96 be loaded, in which case we disable the widgets. If you wish a |
|
97 more detailed error message, you can use |
|
98 \l{QPluginLoader::}{errorString()}; we will look more closely at |
|
99 QPluginLoader later. |
|
100 |
|
101 Here is the implementation of \c sendEcho(): |
|
102 |
|
103 \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 1 |
|
104 |
|
105 This slot is called when the user pushes \c button or presses |
|
106 enter in \c lineEdit. We call \c echo() of the echo interface. In |
|
107 our example this is the \c EchoPlugin, but it could be any plugin |
|
108 that inherit the \c EchoInterface. We take the QString returned |
|
109 from \c echo() and display it in the \c label. |
|
110 |
|
111 Here is the implementation of \c createGUI(): |
|
112 |
|
113 \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 2 |
|
114 |
|
115 We create the widgets and lay them out in a grid layout. We |
|
116 connect the label and line edit to our \c sendEcho() slot. |
|
117 |
|
118 Here is the \c loadPlugin() function: |
|
119 |
|
120 \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 3 |
|
121 |
|
122 Access to plugins at run-time is provided by QPluginLoader. You |
|
123 supply it with the filename of the shared library the plugin is |
|
124 stored in and call \l{QPluginLoader::}{instance()}, which loads |
|
125 and returns the root component of the plugin (i.e., it resolves |
|
126 the type of the plugin and creates a QObject instance of it). If |
|
127 the plugin was not successfully loaded, it will be null, so we |
|
128 return false. If it was loaded correctly, we can cast the plugin |
|
129 to our \c EchoInterface and return true. In the case that the |
|
130 plugin loaded does not implement the \c EchoInterface, \c |
|
131 instance() will return null, but this cannot happen in our |
|
132 example. Notice that the location of the plugin is not the same |
|
133 for all platforms. |
|
134 |
|
135 |
|
136 \section1 EchoInterface Class Definition |
|
137 |
|
138 The \c EchoInterface defines the functions that the plugin will |
|
139 provide. An interface is a class that only consists of pure |
|
140 virtual functions. If non virtual functions were present in the |
|
141 class you would get misleading compile errors in the moc files. |
|
142 |
|
143 \snippet examples/tools/echoplugin/echowindow/echointerface.h 0 |
|
144 |
|
145 We declare \c echo(). In our \c EchoPlugin we use this method to |
|
146 return, or echo, \a message. |
|
147 |
|
148 We use the Q_DECLARE_INTERFACE macro to let \l{Meta-Object |
|
149 System}{Qt's meta object system} aware of the interface. We do |
|
150 this so that it will be possible to identify plugins that |
|
151 implements the interface at run-time. The second argument is a |
|
152 string that must identify the interface in a unique way. |
|
153 |
|
154 |
|
155 \section1 EchoPlugin Class Definition |
|
156 |
|
157 We inherit both QObject and \c EchoInterface to make this class a |
|
158 plugin. The Q_INTERFACES macro tells Qt which interfaces the class |
|
159 implements. In our case we only implement the \c EchoInterface. |
|
160 If a class implements more than one interface, they are given as |
|
161 a comma separated list. |
|
162 |
|
163 \snippet examples/tools/echoplugin/plugin/echoplugin.h 0 |
|
164 |
|
165 |
|
166 \section1 EchoPlugin Class Implementation |
|
167 |
|
168 Here is the implementation of \c echo(): |
|
169 |
|
170 \snippet examples/tools/echoplugin/plugin/echoplugin.cpp 0 |
|
171 |
|
172 We simply return the functions parameter. |
|
173 |
|
174 \snippet examples/tools/echoplugin/plugin/echoplugin.cpp 1 |
|
175 |
|
176 We use the Q_EXPORT_PLUGIN2 macro to let Qt know that the \c |
|
177 EchoPlugin class is a plugin. The first parameter is the name of |
|
178 the plugin; it is usual to give the plugin and the library file it |
|
179 is stored in the same name. |
|
180 |
|
181 \section1 The \c main() function |
|
182 |
|
183 \snippet examples/tools/echoplugin/echowindow/main.cpp 0 |
|
184 |
|
185 We create an \c EchoWindow and display it as a top-level window. |
|
186 |
|
187 \section1 The Profiles |
|
188 |
|
189 When creating plugins the profiles need to be adjusted. |
|
190 We show here what changes need to be done. |
|
191 |
|
192 The profile in the echoplugin directory uses the \c subdirs |
|
193 template and simply includes includes to directories in which |
|
194 the echo window and echo plugin lives: |
|
195 |
|
196 \snippet examples/tools/echoplugin/echoplugin.pro 0 |
|
197 |
|
198 The profile for the echo window does not need any plugin specific |
|
199 settings. We move on to the plugin profile: |
|
200 |
|
201 \snippet examples/tools/echoplugin/plugin/plugin.pro 0 |
|
202 |
|
203 We need to set the TEMPLATE as we now want to make a library |
|
204 instead of an executable. We also need to tell qmake that we are |
|
205 creating a plugin. The \c EchoInterface that the plugin implements |
|
206 lives in the \c echowindow directory, so we need to add that |
|
207 directory to the include path. We set the TARGET of the project, |
|
208 which is the name of the library file in which the plugin will be |
|
209 stored; qmake appends the appropriate file extension depending on |
|
210 the platform. By convention the target should have the same name |
|
211 as the plugin (set with Q_EXPORT_PLUGIN2) |
|
212 |
|
213 \section1 Further reading and examples |
|
214 |
|
215 You can find an overview of the macros needed to create plugins |
|
216 \l{Macros for Defining Plugins}{here}. |
|
217 |
|
218 We give an example of a plugin that extend Qt in the \l{Style |
|
219 Plugin Example}{style plugin} example. The \l{Plug & Paint |
|
220 Example}{plug and paint} example shows how to create static |
|
221 plugins. |
|
222 */ |