Document examples.

8 files changed, 260 insertions, 0 deletions

diff --git a/doc/src/bearer.qdocconf b/doc/src/bearer.qdocconf
index 32c8ebd3db..5937fafe90 100644
--- a/doc/src/bearer.qdocconf
+++ b/doc/src/bearer.qdocconf
@@ -22,6 +22,10 @@ base                    = file:./doc/html
 defines                 = Q_QDOC \
                           __cplusplus
 
+examples.fileextensions = "*.cpp *.h *.svg"
+exampledirs             = ../../examples \
+                          ../..
+
 Cpp.ignoretokens        = QAXFACTORY_EXPORT \
                           QM_EXPORT_CANVAS \
                           QM_EXPORT_DNS \
diff --git a/doc/src/examples/bearercloud.qdoc b/doc/src/examples/bearercloud.qdoc
new file mode 100644
index 0000000000..765341cb2e
--- /dev/null
+++ b/doc/src/examples/bearercloud.qdoc
@@ -0,0 +1,189 @@
+/****************************************************************************
+**
+** Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the Qt Mobility Components.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** If you have questions regarding the use of this file, please
+** contact Nokia at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example 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
+
+    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/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/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 \i {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 \i {configurations} hash.
+
+    The last step is to add it to the scene by calling QGraphicsScene::addItem().
+
+    \snippet examples/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 \i {configStates} and
+    \i {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/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 \i {configStates} member
+    variable.
+
+    \snippet examples/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/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/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/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/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/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.
+*/
diff --git a/doc/src/examples/bearermonitor.qdoc b/doc/src/examples/bearermonitor.qdoc
new file mode 100644
index 0000000000..7ca003f314
--- /dev/null
+++ b/doc/src/examples/bearermonitor.qdoc
@@ -0,0 +1,41 @@
+/****************************************************************************
+**
+** Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the Qt Mobility Components.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** If you have questions regarding the use of this file, please
+** contact Nokia at http://www.qtsoftware.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example bearermonitor
+    \title Bearer Monitor Example
+
+    The Bearer Monitor example shows how to use the Bearer Management API.
+
+    \image bearermonitor-example.png
+*/
diff --git a/doc/src/images/bearercloud-example.png b/doc/src/images/bearercloud-example.png
new file mode 100644
index 0000000000..a8ecda64cc
--- /dev/null
+++ b/doc/src/images/bearercloud-example.png
diff --git a/doc/src/images/bearermonitor-example.png b/doc/src/images/bearermonitor-example.png
new file mode 100644
index 0000000000..d8576a6077
--- /dev/null
+++ b/doc/src/images/bearermonitor-example.png
diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc
index 7b6732ef6d..f51ccba8c7 100644
--- a/doc/src/index.qdoc
+++ b/doc/src/index.qdoc
@@ -126,5 +126,11 @@ To build the library, run \tt qmake and \tt make.
     \o \l{QNetworkSession}
 \endlist
 
+\section2 Examples
+
+\list
+   \o \l{bearercloud}{Bearer Cloud}
+   \o \l{bearermonitor}{Bearer Monitor}
+\endlist
 
 */
diff --git a/examples/bearercloud/bearercloud.cpp b/examples/bearercloud/bearercloud.cpp
index 9066c5b9c7..6106c04ace 100644
--- a/examples/bearercloud/bearercloud.cpp
+++ b/examples/bearercloud/bearercloud.cpp
@@ -47,6 +47,7 @@
 #define M_PI 3.14159265358979323846
 #endif
 
+//! [0]
 BearerCloud::BearerCloud(QObject *parent)
 :   QGraphicsScene(parent), timerId(0)
 {
@@ -91,6 +92,7 @@ BearerCloud::BearerCloud(QObject *parent)
 
     QTimer::singleShot(0, this, SLOT(updateConfigurations()));
 }
+//! [0]
 
 BearerCloud::~BearerCloud()
 {
@@ -123,6 +125,7 @@ void BearerCloud::timerEvent(QTimerEvent *)
     }
 }
 
+//! [2]
 void BearerCloud::configurationAdded(const QNetworkConfiguration &config)
 {
     const QNetworkConfiguration::StateFlags state = config.state();
@@ -141,7 +144,9 @@ void BearerCloud::configurationAdded(const QNetworkConfiguration &config)
 
     addItem(item);
 }
+//! [2]
 
+//! [3]
 void BearerCloud::configurationRemoved(const QNetworkConfiguration &config)
 {
     foreach (const QNetworkConfiguration::StateFlags &state, configStates.uniqueKeys())
@@ -152,7 +157,9 @@ void BearerCloud::configurationRemoved(const QNetworkConfiguration &config)
     item->setFinalScale(0.0);
     item->setDeleteAfterAnimation(true);
 }
+//! [3]
 
+//! [4]
 void BearerCloud::configurationChanged(const QNetworkConfiguration &config)
 {
     foreach (const QNetworkConfiguration::StateFlags &state, configStates.uniqueKeys())
@@ -160,7 +167,9 @@ void BearerCloud::configurationChanged(const QNetworkConfiguration &config)
 
     configStates.insert(config.state(), config.identifier());
 }
+//! [4]
 
+//! [1]
 void BearerCloud::updateConfigurations()
 {
     QList<QNetworkConfiguration> allConfigurations = manager.allConfigurations();
@@ -170,4 +179,5 @@ void BearerCloud::updateConfigurations()
 
     cloudMoved();
 }
+//! [1]
 
diff --git a/examples/bearercloud/cloud.cpp b/examples/bearercloud/cloud.cpp
index 725ff492d6..7dbd64bcbf 100644
--- a/examples/bearercloud/cloud.cpp
+++ b/examples/bearercloud/cloud.cpp
@@ -48,6 +48,7 @@
 
 static QMap<QString, QSvgRenderer *> svgCache;
 
+//! [0]
 Cloud::Cloud(const QNetworkConfiguration &config, QGraphicsItem *parent)
 :   QGraphicsItem(parent), configuration(config), deleteAfterAnimation(false)
 {
@@ -70,6 +71,7 @@ Cloud::Cloud(const QNetworkConfiguration &config, QGraphicsItem *parent)
 
     newConfigurationActivated();
 }
+//! [0]
 
 Cloud::~Cloud()
 {
@@ -194,6 +196,7 @@ void Cloud::paint(QPainter *, const QStyleOptionGraphicsItem *, QWidget *)
 {
 }
 
+//! [4]
 QVariant Cloud::itemChange(QGraphicsItem::GraphicsItemChange change, const QVariant &value)
 {
     switch (change) {
@@ -206,7 +209,9 @@ QVariant Cloud::itemChange(QGraphicsItem::GraphicsItemChange change, const QVari
 
     return QGraphicsItem::itemChange(change, value);
 }
+//! [4]
 
+//! [3]
 void Cloud::mouseDoubleClickEvent(QGraphicsSceneMouseEvent *event)
 {
     if (event->button() == Qt::LeftButton) {
@@ -218,7 +223,9 @@ void Cloud::mouseDoubleClickEvent(QGraphicsSceneMouseEvent *event)
         event->accept();
     }
 }
+//! [3]
 
+//! [2]
 void Cloud::stateChanged(QNetworkSession::State state)
 {
     if (configuration.name().isEmpty())
@@ -284,7 +291,9 @@ void Cloud::stateChanged(QNetworkSession::State state)
 
     setToolTip(tooltip);
 }
+//! [2]
 
+//! [1]
 void Cloud::newConfigurationActivated()
 {
     const QString bearerName = session->bearerName();
@@ -317,6 +326,7 @@ void Cloud::newConfigurationActivated()
 
     stateChanged(session->state());
 }
+//! [1]
 
 qreal Cloud::getRadiusForState(QNetworkConfiguration::StateFlags state)
 {