/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** 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. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example publish-subscribe
    \ingroup publishsubscribe-examples
    \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, or 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
            \li Parameter
            \li Description
        \row
            \li -publisher
            \li Publish values in the Value Space and create a dialog to control those values
               directly.
        \row
            \li -subscriber
            \li 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
*/
