source: trunk/doc/src/examples/bearercloud.qdoc@ 1168

/****************************************************************************
**
** Copyright (C) 2011 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:FDL$
** 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 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 [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example network/bearercloud
    \title Bearer Cloud Example

    The Bearer Cloud example shows how to use the Bearer Management API to monitor the
    connectivity state of the local device.

    \image bearercloud-example.png Screenshot of the Bearer Cloud example

    Bearer Management provides the QNetworkConfigurationManager class which can be used to monitor
    changes in the available \l {QNetworkConfiguration}{network configurations} and the
    QNetworkSession class which is used to \l {QNetworkSession::open()}{open} and
    \l {QNetworkSession::close()}{close} a session bringing a network interface up or down if
    necessary.

    This example displays all known \l {QNetworkConfiguration}{network configurations} in a cloud
    orbiting the local device.  There are four orbits representing the four possible
    \l {QNetworkConfiguration::StateFlags}{states} that the network configuration can be in.
    The closer the orbit the more useful the network configuration is in its current state.
    The inner orbit is populated with network configurations that are in the
    \l {QNetworkConfiguration::Active}{Active} state.  The second orbit is populated with network
    configurations that are in the \l {QNetworkConfiguration::Discovered}{Discovered} state.  The
    third orbit is populated with network configurations that are in the
    \l {QNetworkConfiguration::Defined}{Defined} state.  Finally the outer orbit is populated by
    configurations that are in the \l {QNetworkConfiguration::Undefined}{Undefined} state.

    Hovering the mouse over a network configuration will display information about the network
    configuration in a tool tip.

    Double clicking on an Active or Discovered network configuration will
    \l {QNetworkSession::close()}{close} or \l {QNetworkSession::open()}{open} a network session,
    respectively.

    Lastly you can reorganize the cloud without changing the state of the network configurations by
    dragging them around.

    This example consists of two main classes, the BearerCloud and Cloud classes.  The Cloud class
    represents a single network session and associated network configuration.  The BearerCloud
    class implements a Graphics View scene and manages the life-cycle of Cloud
    objects in response to notification signals from QNetworkConfigurationManager.

    \section1 Setting the scene

    When constructing the scene we first calculate some random offsets using the global qsand()
    and qrand() functions.  We will use these offsets to scatter the initial position of new Cloud
    objects.

    Next we place a text item in the center of the scene to represent the local device and
    surround it with four concentric circles to help visualize the orbits.

    Finally we connect up the network configuration notification signals and queue the initial
    population of the scene during the next iteration of the event loop.

    \snippet examples/network/bearercloud/bearercloud.cpp 0

    Populating the scene with the initial list of known network configuration is easy.  Iterate
    over the list returned by QNetworkConfigurationManager::allConfigurations(), calling our
    configurationAdded() slot on each one.

    We finishing off by calling cloudMoved() to ensure that animations are started.

    \snippet examples/network/bearercloud/bearercloud.cpp 1

    The configurationAdded() slot gets called when a new network configuration is added to the
    system.

    It stores the \l {QNetworkConfiguration::identifier()}{identifier} of the network
    configuration in the \e {configStates} map, which is used to keep a count of the number of
    network configurations in each state.  This in turn is used to calculate the initial position
    of new Cloud objects.

    Next we create a new Cloud object for this network configuration.  Set its initial position
    and store it in the \e {configurations} hash.

    The last step is to add it to the scene by calling QGraphicsScene::addItem().

    \snippet examples/network/bearercloud/bearercloud.cpp 2

    The configurationRemoved() slot gets called when a network configuration is removed from the
    system.

    First we remove all references to the network configuration from the \e {configStates} and
    \e {configurations} member variables.

    Next we initiate animation by setting a final scale value on the Cloud object associated with
    the removed network configuration.

    Finally we flag the Cloud object to delete itself after it has finished animating.

    \snippet examples/network/bearercloud/bearercloud.cpp 3

    The Cloud object will take care of most of the work required when a network configuration
    changes.  All we do in the configurationChanged() slot is update the \e {configStates} member
    variable.

    \snippet examples/network/bearercloud/bearercloud.cpp 4


    \section1 Responding to changes

    Each network session and associated network configuration known to the system is represented in
    the scene as a Cloud object.

    In the Cloud constructor we first initialize member variables.  Then we create a new
    QNetworkSession object bound to the network configuration.  Next we connect the QNetworkSession
    signals which we use to monitor it for state changes.

    Next we set some QGraphicsItem properties.  The QGraphicsItem::ItemIsMovable flag enables mouse
    interaction with the Cloud object.

    The Cloud object consists of an icon and a text caption, these are constructed here.  We will
    assign values to them later, as these will change as the sessions state changes.

    Next we set the initial animation state and call our newConfigurationActivated() slot to finish
    setting up the Cloud object based on the state of network session.

    \snippet examples/network/bearercloud/cloud.cpp 0

    The newConfigurationActivated() slot is called when a session has successfully roamed from one
    access point to another.

    The first thing we do is set the icon, inserting it into a shared SVG renderer cache if it is
    not already available.  Next we set the text caption to the name of the network configuration.

    We then set the position of the icon and text caption so that they are centered horizontally.

    Finally we call our stateChanged() slot.

    \snippet examples/network/bearercloud/cloud.cpp 1

    The stateChanged() slot is called when the session state changes.

    In this slot we set lower the opacity of Cloud objects with network sessions that cannot be
    \l {QNetworkSession::open()}{opened}, and set a detailed tool tip describing the sessions
    state.

    \snippet examples/network/bearercloud/cloud.cpp 2

    In our reimplementation of the QGraphicsItem::mouseDoubleClickEvent() function we call
    QNetworkSession::open() or QNetworkSession::close() to open or close the session in response
    to a double left click.

    \snippet examples/network/bearercloud/cloud.cpp 3

    As we support the user dragging Cloud objects around we need to restart animations when the
    position of the Cloud object changes.  This is accomplished by reimplementing the
    QGraphicsItem::itemChanged() function and calling the cloudMoved() function of the BearerCloud
    object.

    \snippet examples/network/bearercloud/cloud.cpp 4

    The remainder of the code for the Cloud object implements the animations.  The
    calculateForces() function calculates the new position of the Cloud object based on the
    position of all the other Cloud objects in the scene.  The new position is set when the
    advance() function is called to update the Cloud object for the current animation frame.
*/