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