--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/echoplugin.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,222 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $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.
+*/