/****************************************************************************
**
** Copyright (C) 2010 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:FDL$
** 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 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example publish-subscribe
    \title Publish and Subscribe Example

    The Publish and Subscribe example shows how to use the Qt Publish and Subscribe API to
    publish and retrieve values from the platforms Publish and Subscribe system.

    This example program can act as either a publisher of Value Space content, a subscriber of
    Value Space content or both. It can also optionally act as the Value Space Manager. The
    behavior is selected by passing a combination of three optional command line parameters when
    starting the program. If no parameters are supplied the program defaults to acting as both a
    publisher and a subscriber.

    \table
        \header
            \o Parameter
            \o Description
        \row
            \o -server
            \o Starts the Value Space Server.  Only one instance should be started with the this
               parameter.  This parameter is only needed if the Value Space will use a layer that
               has a client-server architecture and a server needs to be started.

        \row
            \o -publisher
            \o Publish values in the Value Space and create a dialog to control those values
               directly.
        \row
            \o -subscriber
            \o Create a dialog to view Value Space items.
    \endtable

    \section2 Publisher

    When acting as a publisher of Value Space content the program creates a PublisherDialog.  This
    dialog contains a widget for setting the base path of the QValueSpacePublisher and
    widgets for setting the value of the three fixed attributes 'intValue', 'stringValue' and
   'byteArrayValue'.

    \image publish-subscribe-publisher.png

    We declare the slots which we will use to respond to user input in the dialog.

    \snippet publish-subscribe/publisherdialog.h 0

    And connect them to signals from the widgets in the constructor.

    \snippet publish-subscribe/publisherdialog.cpp 1

    To publish values in the Value Space we first need to create a QValueSpacePublisher. This is
    done in the \c {createNewObject()} slot, which is also used to handle changes in the base path.
    After the object is constructed we publish the initial values by explicitly calling the other
    slots.

    \snippet publish-subscribe/publisherdialog.cpp 2

    We use QValueSpacePublisher::setValue() to set the values in response to dialog input.

    \snippet publish-subscribe/publisherdialog.cpp 0

    As a final step in the constructor we explicitly call the \c {createNewObject()} slot to create
    an initial QValueSpacePublisher.

    \snippet publish-subscribe/publisherdialog.cpp 3

    \section2 Subscriber

    When acting as a subscriber of Value Space content the program creates a SubscriberDialog.
    This dialog contains a widget for setting the base path of the QValueSpaceSubscriber and a
    table for displaying all of the values directly under base path in the Value Space.

    \image publish-subscribe-subscriber.png

    We declare two slots to propagate values from the Value Space to the dialog in response to
    change notifications from QValueSpaceSubscriber.

    \snippet publish-subscribe/subscriberdialog.h 0

    To read values from the Value Space we first create a QValueSpaceSubscriber and connect to the
    \c {contentsChanged()} signal.

    We explicitly call our \c {subscriberChanged()} slot to populate the table with the initial
    values.

    \snippet publish-subscribe/subscriberdialog.cpp 0

    In response to the \c {contentsChanged()} signal we update all the values in the table.

    \snippet publish-subscribe/subscriberdialog.cpp 1
*/
