| /**************************************************************************** |
| ** |
| ** Copyright (C) 2017 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** 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 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 \l |
| QRandomGenerator. 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. |
| */ |