source: trunk/doc/src/examples/echoplugin.qdoc@ 651

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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