diff options
Diffstat (limited to 'doc/src/examples/bearercloud.qdoc')
| -rw-r--r-- | doc/src/examples/bearercloud.qdoc | 183 |
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. +*/ |