Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 183 insertions, 0 deletions

diff --git a/doc/src/examples/bearercloud.qdoc b/doc/src/examples/bearercloud.qdoc
new file mode 100644
index 0000000..ddf145c
--- /dev/null
+++ b/doc/src/examples/bearercloud.qdoc
@@ -0,0 +1,183 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 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 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.
+*/