<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- hapticsquare.qdoc -->
<title>Qt Mobility 1.2: Haptic Square Example</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>QtMobility Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="http://qt.nokia.com/doc/4.7/all-examples.html">Examples</a></li>
<li>Haptic Square Example</li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level2"><a href="#use-case">Use Case</a></li>
<li class="level1"><a href="#the-application">The Application</a></li>
<li class="level2"><a href="#the-dialog-class">The Dialog Class</a></li>
<li class="level1"><a href="#known-issues">Known Issues</a></li>
</ul>
</div>
<h1 class="title">Haptic Square Example</h1>
<span class="subtitle"></span>
<!-- $$$hapticsquare-description -->
<div class="descr"> <a name="details"></a>
<p>Files:</p>
<ul>
<li><a href="hapticsquare-hapticbutton-cpp.html">hapticsquare/hapticbutton.cpp</a></li>
<li><a href="hapticsquare-hapticbutton-h.html">hapticsquare/hapticbutton.h</a></li>
<li><a href="hapticsquare-hapticsquare-cpp.html">hapticsquare/hapticsquare.cpp</a></li>
<li><a href="hapticsquare-hapticsquare-h.html">hapticsquare/hapticsquare.h</a></li>
<li><a href="hapticsquare-main-cpp.html">hapticsquare/main.cpp</a></li>
<li><a href="hapticsquare-hapticsquare-pro.html">hapticsquare/hapticsquare.pro</a></li>
</ul>
<a name="overview"></a>
<h2>Overview</h2>
<p>This example shows how to use simple haptic effects in an application via the <a href="feedback.html">QtMobility Feedback API</a>.</p>
<p>It provides an example of how to use the QtMobility libraries to:</p>
<ul>
<li>play "system theme" haptic effects corresponding to certain predefined events</li>
<li>play a custom effect, single or repeating</li>
</ul>
<a name="use-case"></a>
<h3>Use Case</h3>
<p>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.</p>
<p>The <a href="feedback.html">QtMobility Feedback API</a> 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:</p>
<ul>
<li>maintain consistency with system theme for tactile feedback about interface events (button clicks, scrolling, etc)</li>
<li>notify the user of an application-specific event (invalid operation, status change, etc)</li>
<li>multisensory user interface (status can be "read" by touching the screen, tactile interfaces, etc)</li>
<li>immersive gaming experiences (explosions, impacts, collisions, etc)</li>
</ul>
<p>This example application provides some short snippets which illustrate how the first two of those use cases may be fulfilled.</p>
<a name="the-application"></a>
<h2>The Application</h2>
<p>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.</p>
<p class="centerAlign"><img src="images/hapticsquare-example.png" alt="" /></p><ul>
<li>"Rumble!" plays a non-repeating effect with symmetric attack and decay</li>
<li>"Ocean" is a toggle button which plays a repeating ocean wave-like effect</li>
<li>"Click" plays the system theme effect for a basic button click</li>
<li>"Oops!" plays the system theme effect for a negative or invalid response</li>
</ul>
<p>The example implements two classes:</p>
<ul>
<li><tt>HapticButton</tt>: Implementation of a button. It inherits <a href="http://qt.nokia.com/doc/4.7/qwidget.html">QWidget</a> and sends signals for button clicks.</li>
<li><tt>Dialog</tt>: A <a href="http://qt.nokia.com/doc/4.7/qdialog.html">QDialog</a> subclass that displays the four <tt>HapticButton</tt>s mentioned above, connects them to its slots, and implements the functionality to play the haptic effects.</li>
</ul>
<a name="the-dialog-class"></a>
<h3>The Dialog Class</h3>
<p>We will now go through the code for the <tt>Dialog</tt> class. Here is its definition:</p>
<pre class="cpp"> <span class="keyword">class</span> HapticSquare : <span class="keyword">public</span> <span class="type"><a href="http://qt.nokia.com/doc/4.7/qwidget.html">QWidget</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
HapticSquare();
<span class="operator">~</span>HapticSquare();
<span class="keyword">private</span> Q_SLOTS:
<span class="type">void</span> playRumble();
<span class="type">void</span> playOcean();
<span class="type">void</span> playButtonClick();
<span class="type">void</span> playNegativeEffect();
<span class="keyword">private</span>:
HapticButton <span class="operator">*</span>m_btnRumble;
HapticButton <span class="operator">*</span>m_btnOcean;
HapticButton <span class="operator">*</span>m_btnButtonClick;
HapticButton <span class="operator">*</span>m_btnNegativeEffect;
<span class="type"><a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a></span> m_rumble;
<span class="type"><a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a></span> m_ocean;
};</pre>
<p>The buttons are connected to the slots, which play the effects. We will now go through the implementation of <tt>Dialog</tt>.</p>
<p>The constructor starts by setting up the non-repeating haptic effect, which is played by clicking the <b>Rumble! Button</b>.</p>
<pre class="cpp"> HapticSquare<span class="operator">::</span>HapticSquare()
{
m_rumble<span class="operator">.</span>setAttackIntensity(<span class="number">0.1</span>);
m_rumble<span class="operator">.</span>setAttackTime(<span class="number">250</span>);
m_rumble<span class="operator">.</span>setIntensity(<span class="number">1.0</span>);
m_rumble<span class="operator">.</span>setDuration(<span class="number">1000</span>);
m_rumble<span class="operator">.</span>setFadeTime(<span class="number">250</span>);
m_rumble<span class="operator">.</span>setFadeIntensity(<span class="number">0.1</span>);</pre>
<p>Custom haptics effects are created by setting up a <a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a>.</p>
<p>A haptics effect provides a fade-in of the effect's <a href="qfeedbackhapticseffect.html#intensity-prop">intensity()</a>. With vibration, you can think of the intensity as how hard the device will vibrate. The effect will start at <a href="qfeedbackhapticseffect.html#attackIntensity-prop">attackIntensity()</a> and interpolate to <a href="qfeedbackhapticseffect.html#intensity-prop">intensity()</a> in <a href="qfeedbackhapticseffect.html#attackTime-prop">attackTime()</a> milliseconds. When the effect ends, we have a similar fade-out, where the haptics effect's intensity will interpolate from <a href="qfeedbackhapticseffect.html#intensity-prop">intensity()</a> to <a href="qfeedbackhapticseffect.html#fadeTime-prop">fadeTime()</a> in <a href="qfeedbackhapticseffect.html#fadeTime-prop">fadeTime()</a> milliseconds. The effect will last for a total duration of <a href="qfeedbackhapticseffect.html#duration-prop">duration()</a> milliseconds.</p>
<p>We next set up the effect for the <b>Ocean Button</b>.</p>
<pre class="cpp"> m_ocean<span class="operator">.</span>setAttackIntensity(<span class="number">0.1</span>);
m_ocean<span class="operator">.</span>setAttackTime(<span class="number">450</span>);
m_ocean<span class="operator">.</span>setIntensity(<span class="number">0.8</span>);
m_ocean<span class="operator">.</span>setDuration(<span class="number">6000</span>);
m_ocean<span class="operator">.</span>setFadeTime(<span class="number">900</span>);
m_ocean<span class="operator">.</span>setFadeIntensity(<span class="number">0.05</span>);
m_ocean<span class="operator">.</span>setPeriod(<span class="number">1500</span>);</pre>
<p>The <tt>m_ocean</tt> is a periodic effect, i.e., it repeats after <a href="qfeedbackhapticseffect.html#period-prop">period()</a> milliseconds. Note that the <a href="qfeedbackhapticseffect.html#duration-prop">duration()</a> must be greater than the period in order for the periodicity of the effect to be discernable.</p>
<p>We then set up the GUI and connects the buttons to slots that will play the effects.</p>
<pre class="cpp"> m_btnRumble <span class="operator">=</span> <span class="keyword">new</span> HapticButton(tr(<span class="string">"Rumble!"</span>));
m_btnOcean <span class="operator">=</span> <span class="keyword">new</span> HapticButton(tr(<span class="string">"Ocean"</span>));
m_btnButtonClick <span class="operator">=</span> <span class="keyword">new</span> HapticButton(tr(<span class="string">"Click"</span>));
m_btnNegativeEffect <span class="operator">=</span> <span class="keyword">new</span> HapticButton(tr(<span class="string">"Oops!"</span>));
<span class="type"><a href="http://qt.nokia.com/doc/4.7/qgridlayout.html">QGridLayout</a></span> <span class="operator">*</span>topLayout <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="http://qt.nokia.com/doc/4.7/qgridlayout.html">QGridLayout</a></span>(<span class="keyword">this</span>);
topLayout<span class="operator">-</span><span class="operator">></span>addWidget(m_btnRumble<span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">0</span>);
topLayout<span class="operator">-</span><span class="operator">></span>addWidget(m_btnOcean<span class="operator">,</span> <span class="number">0</span><span class="operator">,</span> <span class="number">1</span>);
topLayout<span class="operator">-</span><span class="operator">></span>addWidget(m_btnButtonClick<span class="operator">,</span> <span class="number">1</span><span class="operator">,</span> <span class="number">0</span>);
topLayout<span class="operator">-</span><span class="operator">></span>addWidget(m_btnNegativeEffect<span class="operator">,</span> <span class="number">1</span><span class="operator">,</span> <span class="number">1</span>);
connect(m_btnRumble<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(playRumble()));
connect(m_btnOcean<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(playOcean()));
connect(m_btnButtonClick<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(playButtonClick()));
connect(m_btnNegativeEffect<span class="operator">,</span> SIGNAL(clicked())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(playNegativeEffect()));
}</pre>
<p>Let's look at the slots to see how the effects are played.</p>
<pre class="cpp"> <span class="type">void</span> HapticSquare<span class="operator">::</span>playRumble()
{
m_rumble<span class="operator">.</span>start();
}
<span class="type">void</span> HapticSquare<span class="operator">::</span>playOcean()
{
<span class="keyword">if</span> (m_ocean<span class="operator">.</span>state() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qfeedbackeffect.html">QFeedbackEffect</a></span><span class="operator">::</span>Stopped) {
m_ocean<span class="operator">.</span>start();
} <span class="keyword">else</span> {
m_ocean<span class="operator">.</span>stop();
}
}</pre>
<p>With the <tt>m_rumble</tt>, we only have to call <a href="qfeedbackeffect.html#start">start()</a>. It will stop when the effect has finished, and can be played again by calling <a href="qfeedbackeffect.html#start">start()</a> again.</p>
<p>The periodic <tt>m_ocean</tt> effect is started the same way as the <tt>m_rumble</tt> effect, and may be stopped with the <a href="qfeedbackeffect.html#stop">stop()</a> function. It will start playing from the beginning again when <a href="qfeedbackeffect.html#start">start()</a> is called. We could also have paused the effect with <a href="qfeedbackeffect.html#pause">pause()</a>.</p>
<pre class="cpp"> <span class="type">void</span> HapticSquare<span class="operator">::</span>playButtonClick()
{
<span class="type"><a href="qfeedbackeffect.html">QFeedbackEffect</a></span><span class="operator">::</span>playThemeEffect(<span class="type"><a href="qfeedbackeffect.html">QFeedbackEffect</a></span><span class="operator">::</span>ThemeBasicButton);
}
<span class="type">void</span> HapticSquare<span class="operator">::</span>playNegativeEffect()
{
<span class="type"><a href="qfeedbackeffect.html">QFeedbackEffect</a></span><span class="operator">::</span>playThemeEffect(<span class="type"><a href="qfeedbackeffect.html">QFeedbackEffect</a></span><span class="operator">::</span>ThemeNegativeTacticon);
}</pre>
<p>System theme effects are played with the static <a href="qfeedbackeffect.html#playThemeEffect">QFeedbackEffect::playThemeEffect</a>() function. Theme effects cannot be stopped or paused. There is no guarantee that the backend can play the effect; <a href="qfeedbackeffect.html#playThemeEffect">playThemeEffect()</a> will return false if the effect could not be played.</p>
<a name="known-issues"></a>
<h2>Known Issues</h2>
<p>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.</p>
</div>
<!-- @@@hapticsquare -->
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2008-2011 Nokia Corporation and/or its
subsidiaries. Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide.</p>
<p>
All other trademarks are property of their respective owners. <a title="Privacy Policy"
href="http://qt.nokia.com/about/privacy-policy">Privacy Policy</a></p>
<br />
<p>
Licensees holding valid Qt Commercial licenses may use this document in accordance with the Qt Commercial License Agreement provided with the Software or, alternatively, in accordance with the terms contained in a written agreement between you and Nokia.</p>
<p>
Alternatively, this document may be used under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU
Free Documentation License version 1.3</a>
as published by the Free Software Foundation.</p>
</div>
</body>
</html>
distrib
>
Mageia
>
5
>
i586
>
media
>
core-release
>
by-pkgid
>
50facae208d4a6f280e44a513b104320
>
files
>
352
