examples/widgets/doc/src/echoplugin.qdoc

   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 documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   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 Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  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 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 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 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 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 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 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 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 tools/echoplugin/plugin/echoplugin.cpp 0
 157
 158     We simply return the functions parameter.
 159
 160     \snippet 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 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 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 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 */