Merge branch '4.8' of scm.dev.nokia.troll.no:qt/qt

Conflicts:
	doc/src/declarative/qtbinding.qdoc

1 files changed, 164 insertions, 0 deletions

diff --git a/doc/src/examples/maemovibration.qdoc b/doc/src/examples/maemovibration.qdoc
new file mode 100644
index 0000000..de53ba4
--- /dev/null
+++ b/doc/src/examples/maemovibration.qdoc
@@ -0,0 +1,164 @@
+/****************************************************************************
+**
+** 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$
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example widgets/maemovibration
+    \group all-examples
+    \title Maemo Vibration Example
+
+    The Maemo Vibration example shows how to tell the Maemo Mode Control Entity
+    (MCE) to vibrate a maemo device.
+
+    The MCE is a system service on Maemo that, among other things, provides an
+    D-Bus interface to trigger vibrations. The vibrations are specified as
+    patterns and are defined in a system configuration file.
+
+    The example program reads the configuration file to look for possible
+    vibration patterns and display a button for each. Pressing a button will
+    make the device vibrate accordingly, until the application closes, or
+    another pattern is started.
+
+    \image maemovibration-example.png Screenshot of the Maemo Vibration Example
+
+    The code makes use of two classes:
+
+    \list
+    \o \c MceVibrator connects to the MCE service and can start a certain
+       vibrator pattern. It also is responsible to parse the configuration
+       file.
+
+    \o \c ButtonWidget provides a button for each pattern. Pressing the button
+       activates the pattern in question.
+    \endlist
+
+
+    \section1 MceVibrator Class Definition
+
+    \snippet examples/widgets/maemovibration/mcevibrator.h 0
+
+    The \c MceVibrator class inherits from QObject and provides a specialized
+    and Qt friendly interface to the MCE vibration facilty. The slot \c vibrate()
+    can be called to make the device vibrate according to a specific pattern
+    name. We will connect it to a signal of a \c ButtonWidget object later. The
+    static method \c ParsePatternNames() can be called to find out which patterns
+    are available to us.
+
+    \list
+    \o \c mceInterface is our D-Bus handle to the MCE service. We use it to
+       invoke methods on the MCE request object.
+
+    \o \c lastPatternName contains the pattern that was activated last time. We
+       have to keep track of this, because the last pattern has to be
+       deactivated before activating a new pattern.
+    \endlist
+
+
+    \section1 MceVibrator Class Implementation
+
+    To connect to the service, we initialize the D-Bus interface handle. The
+    system header \c "mce/dbus-names.h" contains definitions of the D-Bus
+    service name and request object path and interface. These are passed to the
+    constructor of the handle, and Qt will automatically establish a connection
+    to it, if it is possible.
+
+    The MCE expects us to first enable the vibrator before we can use it. This
+    is done with the call to the \c MCE_ENABLE_VIBRATOR D-Bus method.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 0
+
+    From now on we can activate vibration patterns. Each time a vibration
+    pattern is activated, the last pattern has to be deactivated first. In the
+    vibrate slot we use the MCE interface to call the activation method.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 1
+
+    The calls to the private method deactivate simply makes sure to deactivate
+    the last pattern used, if there was one.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 2
+
+    Calling either the activate or deactivate MCE D-Bus method with invalid
+    pattern names are ignored.
+
+    Finally, the destructor disables the vibrator. When the destructor of the
+    MCE interface handle is called, the connection is also closed.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 3
+
+    The MCE configuration file contains options for many different things. We
+    are only interested in one line that contains the vibration patterns. It
+    has the following format:
+
+
+    \code
+    VibratorPatterns=semicolon;separated;list;of;values
+    \endcode
+
+    The static method \c ParsePatternNames looks for this line and returns a
+    QStringList containing the values, which are the pattern names we can use.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 4
+
+    The helper function \c checkError() saves us some code duplication. None of the
+    called methods return anything of use to us, so we're only interested in
+    getting error messages for debugging.
+
+    \snippet examples/widgets/maemovibration/mcevibrator.cpp 5
+
+
+    \section1 ButtonWidget Class Definition
+
+    \snippet examples/widgets/maemovibration/buttonwidget.h 0
+
+    The \c ButtonWidget class inherits from QWidget and provides the main user
+    interface for the application. It creates a grid of buttons, one for each
+    string in the stringlist passed to the constructor. Pressing a button emits
+    the \c clicked() signal, where the string is the text of the button that
+    was pressed.
+
+    This class is taken from the QSignalMapper documentation. The only change
+    is the number of columns in the grid from three to two, to make the button
+    labels fit.
+
+
+    \section1 ButtonWidget Class Implementation
+
+    \snippet examples/widgets/maemovibration/buttonwidget.cpp 0
+
+
+    \section1 \c main() Function
+
+    The main function begins with looking up the patterns available to us.
+
+    \snippet examples/widgets/maemovibration/main.cpp 0
+
+    Then we create one instance of both classes, and connects the
+    \c ButtonWidget's clicked signal to the \c MceVibrator's \c vibrate() slot.
+    This works, since the button texts are the same as the pattern names.
+
+    \snippet examples/widgets/maemovibration/main.cpp 1
+*/