diff options
Diffstat (limited to 'doc/src/examples/echoplugin.qdoc')
-rw-r--r-- | doc/src/examples/echoplugin.qdoc | 208 |
1 files changed, 0 insertions, 208 deletions
diff --git a/doc/src/examples/echoplugin.qdoc b/doc/src/examples/echoplugin.qdoc deleted file mode 100644 index 8481754e98..0000000000 --- a/doc/src/examples/echoplugin.qdoc +++ /dev/null @@ -1,208 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example tools/echoplugin - \title Echo Plugin Example - - This example shows how to create a Qt plugin. - - \image echopluginexample.png - - There are two kinds of plugins in Qt: plugins that extend Qt - itself and plugins that extend applications written in Qt. In this - example, we show the procedure of implementing plugins that extend - applications. When you create a plugin you declare an interface, - which is a class with only pure virtual functions. This interface - is inherited by the class that implements the plugin. The class is - stored in a shared library and can therefore be loaded by - applications at run-time. When loaded, the plugin is dynamically - cast to the interface using Qt's \l{Meta-Object - System}{meta-object system}. The plugin \l{How to Create Qt - Plugins}{overview document} gives a high-level introduction to - plugins. - - We have implemented a plugin, the \c EchoPlugin, which implements - the \c EchoInterface. The interface consists of \c echo(), which - takes a QString as argument. The \c EchoPlugin returns the string - unaltered (i.e., it works as the familiar echo command found in - both Unix and Windows). - - We test the plugin in \c EchoWindow: when you push the QPushButton - (as seen in the image above), the application sends the text in - the QLineEdit to the plugin, which echoes it back to the - application. The answer from the plugin is displayed in the - QLabel. - - - \section1 EchoWindow Class Definition - - The \c EchoWindow class lets us test the \c EchoPlugin through a - GUI. - - \snippet examples/tools/echoplugin/echowindow/echowindow.h 0 - - We load the plugin in \c loadPlugin() and cast it to \c - EchoInterface. When the user clicks the \c button we take the - text in \c lineEdit and call the interface's \c echo() with it. - - - \section1 EchoWindow Class Implementation - - We start with a look at the constructor: - - \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 0 - - We create the widgets and set a title for the window. We then load - the plugin. \c loadPlugin() returns false if the plugin could not - be loaded, in which case we disable the widgets. If you wish a - more detailed error message, you can use - \l{QPluginLoader::}{errorString()}; we will look more closely at - QPluginLoader later. - - Here is the implementation of \c sendEcho(): - - \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 1 - - This slot is called when the user pushes \c button or presses - enter in \c lineEdit. We call \c echo() of the echo interface. In - our example this is the \c EchoPlugin, but it could be any plugin - that inherit the \c EchoInterface. We take the QString returned - from \c echo() and display it in the \c label. - - Here is the implementation of \c createGUI(): - - \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 2 - - We create the widgets and lay them out in a grid layout. We - connect the label and line edit to our \c sendEcho() slot. - - Here is the \c loadPlugin() function: - - \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 3 - - Access to plugins at run-time is provided by QPluginLoader. You - supply it with the filename of the shared library the plugin is - stored in and call \l{QPluginLoader::}{instance()}, which loads - and returns the root component of the plugin (i.e., it resolves - the type of the plugin and creates a QObject instance of it). If - the plugin was not successfully loaded, it will be null, so we - return false. If it was loaded correctly, we can cast the plugin - to our \c EchoInterface and return true. In the case that the - plugin loaded does not implement the \c EchoInterface, \c - instance() will return null, but this cannot happen in our - example. Notice that the location of the plugin is not the same - for all platforms. - - - \section1 EchoInterface Class Definition - - The \c EchoInterface defines the functions that the plugin will - provide. An interface is a class that only consists of pure - virtual functions. If non virtual functions were present in the - class you would get misleading compile errors in the moc files. - - \snippet examples/tools/echoplugin/echowindow/echointerface.h 0 - - We declare \c echo(). In our \c EchoPlugin we use this method to - return, or echo, \a message. - - We use the Q_DECLARE_INTERFACE macro to let \l{Meta-Object - System}{Qt's meta object system} aware of the interface. We do - this so that it will be possible to identify plugins that - implements the interface at run-time. The second argument is a - string that must identify the interface in a unique way. - - - \section1 EchoPlugin Class Definition - - We inherit both QObject and \c EchoInterface to make this class a - plugin. The Q_INTERFACES macro tells Qt which interfaces the class - implements. In our case we only implement the \c EchoInterface. - If a class implements more than one interface, they are given as - a comma separated list. - - \snippet examples/tools/echoplugin/plugin/echoplugin.h 0 - - - \section1 EchoPlugin Class Implementation - - Here is the implementation of \c echo(): - - \snippet examples/tools/echoplugin/plugin/echoplugin.cpp 0 - - We simply return the functions parameter. - - \snippet examples/tools/echoplugin/plugin/echoplugin.cpp 1 - - We use the Q_EXPORT_PLUGIN2 macro to let Qt know that the \c - EchoPlugin class is a plugin. The first parameter is the name of - the plugin; it is usual to give the plugin and the library file it - is stored in the same name. - - \section1 The \c main() function - - \snippet examples/tools/echoplugin/echowindow/main.cpp 0 - - We create an \c EchoWindow and display it as a top-level window. - - \section1 The Profiles - - When creating plugins the profiles need to be adjusted. - We show here what changes need to be done. - - The profile in the echoplugin directory uses the \c subdirs - template and simply includes includes to directories in which - the echo window and echo plugin lives: - - \snippet examples/tools/echoplugin/echoplugin.pro 0 - - The profile for the echo window does not need any plugin specific - settings. We move on to the plugin profile: - - \snippet examples/tools/echoplugin/plugin/plugin.pro 0 - - We need to set the TEMPLATE as we now want to make a library - instead of an executable. We also need to tell qmake that we are - creating a plugin. The \c EchoInterface that the plugin implements - lives in the \c echowindow directory, so we need to add that - directory to the include path. We set the TARGET of the project, - which is the name of the library file in which the plugin will be - stored; qmake appends the appropriate file extension depending on - the platform. By convention the target should have the same name - as the plugin (set with Q_EXPORT_PLUGIN2) - - \section1 Further reading and examples - - You can find an overview of the macros needed to create plugins - \l{Macros for Defining Plugins}{here}. - - We give an example of a plugin that extend Qt in the \l{Style - Plugin Example}{style plugin} example. The \l{Plug & Paint - Example}{plug and paint} example shows how to create static - plugins. -*/ |