Update copyright headers
[qt:qt.git] / doc / src / examples / bearercloud.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \example network/bearercloud
30     \title Bearer Cloud Example
31
32     \brief The Bearer Cloud example shows how to use the Bearer Management API to monitor the
33     connectivity state of the local device.
34
35     \image bearercloud-example.png Screenshot of the Bearer Cloud example
36
37     Bearer Management provides the QNetworkConfigurationManager class which can be used to monitor
38     changes in the available \l {QNetworkConfiguration}{network configurations} and the
39     QNetworkSession class which is used to \l {QNetworkSession::open()}{open} and
40     \l {QNetworkSession::close()}{close} a session bringing a network interface up or down if
41     necessary.
42
43     This example displays all known \l {QNetworkConfiguration}{network configurations} in a cloud
44     orbiting the local device.  There are four orbits representing the four possible
45     \l {QNetworkConfiguration::StateFlags}{states} that the network configuration can be in.
46     The closer the orbit the more useful the network configuration is in its current state.
47     The inner orbit is populated with network configurations that are in the
48     \l {QNetworkConfiguration::Active}{Active} state.  The second orbit is populated with network
49     configurations that are in the \l {QNetworkConfiguration::Discovered}{Discovered} state.  The
50     third orbit is populated with network configurations that are in the
51     \l {QNetworkConfiguration::Defined}{Defined} state.  Finally the outer orbit is populated by
52     configurations that are in the \l {QNetworkConfiguration::Undefined}{Undefined} state.
53
54     Hovering the mouse over a network configuration will display information about the network
55     configuration in a tool tip.
56
57     Double clicking on an Active or Discovered network configuration will
58     \l {QNetworkSession::close()}{close} or \l {QNetworkSession::open()}{open} a network session,
59     respectively.
60
61     Lastly you can reorganize the cloud without changing the state of the network configurations by
62     dragging them around.
63
64     This example consists of two main classes, the BearerCloud and Cloud classes.  The Cloud class
65     represents a single network session and associated network configuration.  The BearerCloud
66     class implements a Graphics View scene and manages the life-cycle of Cloud
67     objects in response to notification signals from QNetworkConfigurationManager.
68
69     \section1 Setting the scene
70
71     When constructing the scene we first calculate some random offsets using the global qsand()
72     and qrand() functions.  We will use these offsets to scatter the initial position of new Cloud
73     objects.
74
75     Next we place a text item in the center of the scene to represent the local device and
76     surround it with four concentric circles to help visualize the orbits.
77
78     Finally we connect up the network configuration notification signals and queue the initial
79     population of the scene during the next iteration of the event loop.
80
81     \snippet examples/network/bearercloud/bearercloud.cpp 0
82
83     Populating the scene with the initial list of known network configuration is easy.  Iterate
84     over the list returned by QNetworkConfigurationManager::allConfigurations(), calling our
85     configurationAdded() slot on each one.
86
87     We finishing off by calling cloudMoved() to ensure that animations are started.
88
89     \snippet examples/network/bearercloud/bearercloud.cpp 1
90
91     The configurationAdded() slot gets called when a new network configuration is added to the
92     system.
93
94     It stores the \l {QNetworkConfiguration::identifier()}{identifier} of the network
95     configuration in the \e {configStates} map, which is used to keep a count of the number of
96     network configurations in each state.  This in turn is used to calculate the initial position
97     of new Cloud objects.
98
99     Next we create a new Cloud object for this network configuration.  Set its initial position
100     and store it in the \e {configurations} hash.
101
102     The last step is to add it to the scene by calling QGraphicsScene::addItem().
103
104     \snippet examples/network/bearercloud/bearercloud.cpp 2
105
106     The configurationRemoved() slot gets called when a network configuration is removed from the
107     system.
108
109     First we remove all references to the network configuration from the \e {configStates} and
110     \e {configurations} member variables.
111
112     Next we initiate animation by setting a final scale value on the Cloud object associated with
113     the removed network configuration.
114
115     Finally we flag the Cloud object to delete itself after it has finished animating.
116
117     \snippet examples/network/bearercloud/bearercloud.cpp 3
118
119     The Cloud object will take care of most of the work required when a network configuration
120     changes.  All we do in the configurationChanged() slot is update the \e {configStates} member
121     variable.
122
123     \snippet examples/network/bearercloud/bearercloud.cpp 4
124
125
126     \section1 Responding to changes
127
128     Each network session and associated network configuration known to the system is represented in
129     the scene as a Cloud object.
130
131     In the Cloud constructor we first initialize member variables.  Then we create a new
132     QNetworkSession object bound to the network configuration.  Next we connect the QNetworkSession
133     signals which we use to monitor it for state changes.
134
135     Next we set some QGraphicsItem properties.  The QGraphicsItem::ItemIsMovable flag enables mouse
136     interaction with the Cloud object.
137
138     The Cloud object consists of an icon and a text caption, these are constructed here.  We will
139     assign values to them later, as these will change as the sessions state changes.
140
141     Next we set the initial animation state and call our newConfigurationActivated() slot to finish
142     setting up the Cloud object based on the state of network session.
143
144     \snippet examples/network/bearercloud/cloud.cpp 0
145
146     The newConfigurationActivated() slot is called when a session has successfully roamed from one
147     access point to another.
148
149     The first thing we do is set the icon, inserting it into a shared SVG renderer cache if it is
150     not already available.  Next we set the text caption to the name of the network configuration.
151
152     We then set the position of the icon and text caption so that they are centered horizontally.
153
154     Finally we call our stateChanged() slot.
155
156     \snippet examples/network/bearercloud/cloud.cpp 1
157
158     The stateChanged() slot is called when the session state changes.
159
160     In this slot we set lower the opacity of Cloud objects with network sessions that cannot be
161     \l {QNetworkSession::open()}{opened}, and set a detailed tool tip describing the sessions
162     state.
163
164     \snippet examples/network/bearercloud/cloud.cpp 2
165
166     In our reimplementation of the QGraphicsItem::mouseDoubleClickEvent() function we call
167     QNetworkSession::open() or QNetworkSession::close() to open or close the session in response
168     to a double left click.
169
170     \snippet examples/network/bearercloud/cloud.cpp 3
171
172     As we support the user dragging Cloud objects around we need to restart animations when the
173     position of the Cloud object changes.  This is accomplished by reimplementing the
174     QGraphicsItem::itemChanged() function and calling the cloudMoved() function of the BearerCloud
175     object.
176
177     \snippet examples/network/bearercloud/cloud.cpp 4
178
179     The remainder of the code for the Cloud object implements the animations.  The
180     calculateForces() function calculates the new position of the Cloud object based on the
181     position of all the other Cloud objects in the scene.  The new position is set when the
182     advance() function is called to update the Cloud object for the current animation frame.
183 */