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