1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
/****************************************************************************
**
** Copyright (C) 2010 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 hapticsquare
\title Haptic Square Example
\section1 Overview
This example shows how to use simple haptic effects in an application via
the \l{Feedback}{QtMobility Feedback API}.
It provides an example of how to use the QtMobility libraries to:
\list
\o play "system theme" haptic effects corresponding to certain predefined events
\o play a custom effect, single or repeating
\endlist
\section2 Use Case
Compelling applications attempt to immerse the user in the application
experience. There are many elements to an immersive experience, including
a consistent and beautiful graphical user interface design, unobtrusive yet
informative sound design, and intuitive program flow. Another important
aspect of immersive applications is tactile feedback and haptic effects.
The \l{Feedback}{QtMobility Feedback API} allows application developers to
include tactile feedback into their application via a simple to use and
extensible API. Some common uses for tactile feedback are:
\list
\o maintain consistency with system theme for tactile feedback about interface events (button clicks, scrolling, etc)
\o notify the user of an application-specific event (invalid operation, status change, etc)
\o multisensory user interface (status can be "read" by touching the screen, tactile interfaces, etc)
\o immersive gaming experiences (explosions, impacts, collisions, etc)
\endlist
This example application provides some short snippets which illustrate how
the first two of those use cases may be fulfilled.
\section1 The Application
The application is designed to work on desktop and mobile platforms with
minimal differences in code between the platforms. The interface consists
of four buttons arranged into a square, each of which causes a different
tactile effect to be played by the default tactile effect provider plugin
on the platform.
\image hapticsquare-example.png
\list
\o "Rumble!" plays a non-repeating effect with symmetric attack and decay
\o "Ocean" is a toggle button which plays a repeating ocean wave-like effect
\o "Click" plays the system theme effect for a basic button click
\o "Oops!" plays the system theme effect for a negative or invalid response
\endlist
The example implements two classes:
\list
\o \c {HapticButton}: Implementation of a button. It
inherits QWidget and sends signals for button clicks.
\o \c {Dialog}: A QDialog subclass that displays the four
\c{HapticButton}s mentioned above,
connects them to its slots, and implements the functionality to
play the haptic effects.
\endlist
\section2 The Dialog Class
We will now go through the code for the \c Dialog class. Here is its
definition:
\snippet examples/hapticsquare/hapticsquare.h 0
The buttons are connected to the slots, which play the effects. We will now
go through the implementation of \c Dialog.
The constructor starts by setting up the non-repeating haptic effect, which
is played by clicking the \gui {Rumble! Button}.
\snippet examples/hapticsquare/hapticsquare.cpp 0
Custom haptics effects are created by setting up a QFeedbackHapticsEffect.
A haptics effect provides a fade-in of the effect's
\l{QFeedbackHapticsEffect::}{intensity()}. With vibration, you can think of
the intensity as how hard the device will vibrate. The effect will start at
\l{QFeedbackHapticsEffect::}{attackIntensity()} and interpolate to
\l{QFeedbackHapticsEffect::}{intensity()} in
\l{QFeedbackHapticsEffect::}{attackTime()} milliseconds. When the effect
ends, we have a similar fade-out, where the haptics effect's intensity will
interpolate from \l{QFeedbackHapticsEffect::}{intensity()} to
\l{QFeedbackHapticsEffect::}{fadeTime()} in
\l{QFeedbackHapticsEffect::}{fadeTime()} milliseconds.
The effect will last for a total duration of
\l{QFeedbackHapticsEffect::}{duration()} milliseconds.
We next set up the effect for the \gui {Ocean Button}.
\snippet examples/hapticsquare/hapticsquare.cpp 1
The \c m_ocean is a periodic effect, i.e., it repeats after
\l{QFeedbackHapticsEffect::}{period()} milliseconds. Note that the
\l{QFeedbackHapticsEffect::}{duration()} must be greater than the period
in order for the periodicity of the effect to be discernable.
We then set up the GUI and connects the buttons to slots that will play the
effects.
\snippet examples/hapticsquare/hapticsquare.cpp 2
Let's look at the slots to see how the effects are played.
\snippet examples/hapticsquare/hapticsquare.cpp 3
With the \c m_rumble, we only have to call \l{QFeedbackEffect::}{start()}. It
will stop when the effect has finished, and can be played again by calling
\l{QFeedbackEffect::}{start()} again.
The periodic \c m_ocean effect is started the same way as the \c m_rumble
effect, and may be stopped with the \l{QFeedbackEffect::}{stop()} function.
It will start playing from the beginning again when
\l{QFeedbackEffect::}{start()} is called. We could also have paused the
effect with \l{QFeedbackEffect::}{pause()}.
\snippet examples/hapticsquare/hapticsquare.cpp 4
System theme effects are played with the static
QFeedbackEffect::playThemeEffect() function. Theme effects cannot be stopped
or paused. There is no guarantee that the backend can play the effect;
\l{QFeedbackEffect::}{playThemeEffect()} will return false if the effect
could not be played.
\section1 Known Issues
The example is not intended to exercise the entire API. Instead, it is a
simple example which illustrates some simple uses of the API.
Also, the example will not work correctly on platforms which do not have a
QFeedbackHapticInterface (haptic effect provider) plugin loaded. On such
platforms, clicking the buttons will have no effect. On Maemo5, periodic
effects do not support attack or fade, and so the ocean effect is not
smooth.
*/
|
