Update copyright headers
[qt:qt.git] / doc / src / examples / maemovibration.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 widgets/maemovibration
30     \group all-examples
31     \title Maemo Vibration Example
32
33     \brief The Maemo Vibration example shows how to tell the Maemo Mode Control Entity
34     (MCE) to vibrate a maemo device.
35
36     The MCE is a system service on Maemo that, among other things, provides an
37     D-Bus interface to trigger vibrations. The vibrations are specified as
38     patterns and are defined in a system configuration file.
39
40     The example program reads the configuration file to look for possible
41     vibration patterns and display a button for each. Pressing a button will
42     make the device vibrate accordingly, until the application closes, or
43     another pattern is started.
44
45     \image maemovibration-example.png Screenshot of the Maemo Vibration Example
46
47     The code makes use of two classes:
48
49     \list
50     \o \c MceVibrator connects to the MCE service and can start a certain
51        vibrator pattern. It also is responsible to parse the configuration
52        file.
53
54     \o \c ButtonWidget provides a button for each pattern. Pressing the button
55        activates the pattern in question.
56     \endlist
57
58
59     \section1 MceVibrator Class Definition
60
61     \snippet examples/widgets/maemovibration/mcevibrator.h 0
62
63     The \c MceVibrator class inherits from QObject and provides a specialized
64     and Qt friendly interface to the MCE vibration facilty. The slot \c vibrate()
65     can be called to make the device vibrate according to a specific pattern
66     name. We will connect it to a signal of a \c ButtonWidget object later. The
67     static method \c ParsePatternNames() can be called to find out which patterns
68     are available to us.
69
70     \list
71     \o \c mceInterface is our D-Bus handle to the MCE service. We use it to
72        invoke methods on the MCE request object.
73
74     \o \c lastPatternName contains the pattern that was activated last time. We
75        have to keep track of this, because the last pattern has to be
76        deactivated before activating a new pattern.
77     \endlist
78
79
80     \section1 MceVibrator Class Implementation
81
82     To connect to the service, we initialize the D-Bus interface handle. The
83     system header \c "mce/dbus-names.h" contains definitions of the D-Bus
84     service name and request object path and interface. These are passed to the
85     constructor of the handle, and Qt will automatically establish a connection
86     to it, if it is possible.
87
88     The MCE expects us to first enable the vibrator before we can use it. This
89     is done with the call to the \c MCE_ENABLE_VIBRATOR D-Bus method.
90
91     \snippet examples/widgets/maemovibration/mcevibrator.cpp 0
92
93     From now on we can activate vibration patterns. Each time a vibration
94     pattern is activated, the last pattern has to be deactivated first. In the
95     vibrate slot we use the MCE interface to call the activation method.
96
97     \snippet examples/widgets/maemovibration/mcevibrator.cpp 1
98
99     The calls to the private method deactivate simply makes sure to deactivate
100     the last pattern used, if there was one.
101
102     \snippet examples/widgets/maemovibration/mcevibrator.cpp 2
103
104     Calling either the activate or deactivate MCE D-Bus method with invalid
105     pattern names are ignored.
106
107     Finally, the destructor disables the vibrator. When the destructor of the
108     MCE interface handle is called, the connection is also closed.
109
110     \snippet examples/widgets/maemovibration/mcevibrator.cpp 3
111
112     The MCE configuration file contains options for many different things. We
113     are only interested in one line that contains the vibration patterns. It
114     has the following format:
115
116
117     \code
118     VibratorPatterns=semicolon;separated;list;of;values
119     \endcode
120
121     The static method \c ParsePatternNames looks for this line and returns a
122     QStringList containing the values, which are the pattern names we can use.
123
124     \snippet examples/widgets/maemovibration/mcevibrator.cpp 4
125
126     The helper function \c checkError() saves us some code duplication. None of the
127     called methods return anything of use to us, so we're only interested in
128     getting error messages for debugging.
129
130     \snippet examples/widgets/maemovibration/mcevibrator.cpp 5
131
132
133     \section1 ButtonWidget Class Definition
134
135     \snippet examples/widgets/maemovibration/buttonwidget.h 0
136
137     The \c ButtonWidget class inherits from QWidget and provides the main user
138     interface for the application. It creates a grid of buttons, one for each
139     string in the stringlist passed to the constructor. Pressing a button emits
140     the \c clicked() signal, where the string is the text of the button that
141     was pressed.
142
143     This class is taken from the QSignalMapper documentation. The only change
144     is the number of columns in the grid from three to two, to make the button
145     labels fit.
146
147
148     \section1 ButtonWidget Class Implementation
149
150     \snippet examples/widgets/maemovibration/buttonwidget.cpp 0
151
152
153     \section1 \c main() Function
154
155     The main function begins with looking up the patterns available to us.
156
157     \snippet examples/widgets/maemovibration/main.cpp 0
158
159     Then we create one instance of both classes, and connects the
160     \c ButtonWidget's clicked signal to the \c MceVibrator's \c vibrate() slot.
161     This works, since the button texts are the same as the pattern names.
162
163     \snippet examples/widgets/maemovibration/main.cpp 1
164 */