165 lines
6.0 KiB
Plaintext
165 lines
6.0 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
|
|
** Contact: http://www.qt-project.org/
|
|
**
|
|
** 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
|
|
*/
|