/usr/share/qt5/doc/qtfeedback/qtfeedback-index.html is in qtfeedback5-doc-html 5.0~git20130529-0ubuntu13.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qtfeedback.qdoc -->
<title>C++ Feedback API | Qt 5.0 </title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
</head>
<body>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.0</li>
<li>C++ Feedback API</li>
<li id="buildversion">Qt 5.0.0 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<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="#platform-issues">Platform Issues</a></li>
<li class="level1"><a href="#using-effects">Using Effects</a></li>
<li class="level2"><a href="#theme-effects">Theme Effects</a></li>
<li class="level2"><a href="#custom-effects">Custom Effects</a></li>
<li class="level1"><a href="#main-classes">Main Classes</a></li>
<li class="level1"><a href="#examples">Examples</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">C++ Feedback API</h1>
<span class="subtitle"></span>
<!-- $$$qtfeedback-index.html-description -->
<div class="descr"> <a name="details"></a>
<p>The C++ Feedback API enables a client to control and provide tactile and audio feedback to the user. The feedback is in response to user actions. For example, touching an onscreen button. Control of the feedback involves control of the vibration of the device, when a vibrator is used, or the piezo feedback from the screen.</p>
<a name="overview"></a>
<h2 id="overview">Overview</h2>
<p>The Feedback API allows application developers to implement feedback and programmatic vibration in their applications. The API provides abstractions for various types of feedback, and allows custom implementations of these types of feedback.</p>
<p>The <a href="qfeedbackeffect.html">QFeedbackEffect</a> class provides a simple interface to allow developers to start, stop or pause the playback of an effect. It is an abstract class which is implemented by <a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a> and QFeedbackFileEffect. In addition, it allows the instantaneous playback of feedback effects which match the system theme.</p>
<p>A <a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a> is a custom effect which allows a program to play a haptic effect on an actuator. Such an effect might have a duration, intensity, and envelope of playback (including attack time and intensity, and fade time and intensity), as well as a period if it is a periodic (repeating) effect.</p>
<p>A QFeedbackFileEffect is a haptic tune or audio file saved in a file which may be played back. These effects must be created by third-party applications, and a plugin which supports the specific file format must be installed. In particular, note that audio effects are generally limited to simple formats, to reduce latency. You can check what formats are supported by the system by calling QFeedbackFileEffect::supportedMimeTypes().</p>
<p>For the vast majority of use cases, the <a href="qfeedbackeffect.html">QFeedbackEffect</a>, <a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a> and QFeedbackFileEffect classes are the only classes which developers will use in their programs. There are some special cases, however, where they may wish to implement their own feedback plugin. The QtFeedback API allows third party developers to implement <a href="qfeedbackinterface.html">QFeedbackInterface</a> in a plugin which may be loaded by the plugin loading mechanism to play feedback effects.</p>
<p>Note that in any application, only the highest priority plugin for each of the three types of feedback will be used to provide the feedback effects, except for file feedback plugins (where only the highest priority plugin for each supported mime-type is used). The interface classes which must be implemented by a plugin to provide effects to clients are:</p>
<ul>
<li><a href="qfeedbackhapticsinterface.html">QFeedbackHapticsInterface</a> for <a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a></li>
<li>QFeedbackFileInterface for QFeedbackFileEffect</li>
<li><a href="qfeedbackthemeinterface.html">QFeedbackThemeInterface</a> for the built-in theme effects (QFeedbackEffect::ThemeEffect).</li>
</ul>
<p>Generally, the device platform will provide an implementation of each of the three different interfaces, which will be the default plugins used for the various <a href="qfeedbackeffect.html">QFeedbackEffect</a>s.</p>
<a name="platform-issues"></a>
<h3 >Platform Issues</h3>
<p><b>Note: </b>Platforms might have user settings that enable/disables the vibration.</p><a name="using-effects"></a>
<h2 id="using-effects">Using Effects</h2>
<a name="theme-effects"></a>
<h3 >Theme Effects</h3>
<p>The most common use of the API is to play system theme effects for user interface interaction notifications, for example, button clicks. These system theme effects can be played instantaneously, but cannot be paused or stopped. They are played via the static <a href="qfeedbackeffect.html#playThemeEffect">QFeedbackEffect::playThemeEffect</a>() function:</p>
<pre class="cpp"> <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>Press);</pre>
<p>There are many different theme effects defined, to cover a variety of interactions and notifications, to allow an application to maintain greater consistency with the platform user experience.</p>
<pre class="cpp"> <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>DragStart);</pre>
<a name="custom-effects"></a>
<h3 >Custom Effects</h3>
<p>The next most common use of the API is to define a custom effect which can be used to notify the user of application-specific events or to increase the immersiveness of an application. A custom effect may be either periodic or non-periodic.</p>
<p>The following diagram shows the graph of intensity over time of a non-periodic effect which was started at time <code>t</code> and ended at time <code>q</code>, with an <a href="qfeedbackhapticseffect.html#intensity-prop">intensity</a> of <code>I</code>, an <a href="qfeedbackhapticseffect.html#attackIntensity-prop">attack intensity</a> of <code>AI</code>, a <a href="qfeedbackhapticseffect.html#fadeIntensity-prop">fade intensity</a> of <code>FI</code>, an <a href="qfeedbackhapticseffect.html#attackTime-prop">attack time</a> of <code>AT</code>, and a <a href="qfeedbackhapticseffect.html#fadeTime-prop">fade time</a> of <code>FT</code>, with a total <a href="qfeedbackeffect.html#duration-prop">duration</a> of <code>Duration</code> milliseconds:</p>
<p class="centerAlign"><img src="images/non-periodic-effect.png" alt="" /></p><p>The following diagram shows the graph of intensity over time of a periodic effect which was started at time <code>t</code> and ended at time <code>q</code>, with an <a href="qfeedbackhapticseffect.html#intensity-prop">intensity</a> of <code>I</code>, an <a href="qfeedbackhapticseffect.html#attackIntensity-prop">attack intensity</a> of <code>AI</code>, a <a href="qfeedbackhapticseffect.html#fadeIntensity-prop">fade intensity</a> of <code>FI</code>, an <a href="qfeedbackhapticseffect.html#attackTime-prop">attack time</a> of <code>AT</code>, and a <a href="qfeedbackhapticseffect.html#fadeTime-prop">fade time</a> of <code>FT</code>, with a <a href="qfeedbackhapticseffect.html#period-prop">period</a> of <code>Period</code> milliseconds and a total <a href="qfeedbackeffect.html#duration-prop">duration</a> of <code>Duration</code> milliseconds:</p>
<p class="centerAlign"><img src="images/periodic-effect.png" alt="" /></p><p>A custom haptic effect may be defined in the following manner:</p>
<pre class="cpp"> <span class="type"><a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a></span> rumble;
rumble<span class="operator">.</span>setAttackIntensity(<span class="number">0.0</span>);
rumble<span class="operator">.</span>setAttackTime(<span class="number">250</span>);
rumble<span class="operator">.</span>setIntensity(<span class="number">1.0</span>);
rumble<span class="operator">.</span>setDuration(<span class="number">1000</span>);
rumble<span class="operator">.</span>setFadeTime(<span class="number">250</span>);
rumble<span class="operator">.</span>setFadeIntensity(<span class="number">0.0</span>);</pre>
<p><b>Note: </b>No periodicity was defined for the effect, although that can be done by calling <a href="qfeedbackhapticseffect.html#period-prop">QFeedbackHapticsEffect::setPeriod</a>() if required.</p><p>Once the effect has been defined, it may be played via the API offered in the <a href="qfeedbackeffect.html">QFeedbackEffect</a> base class:</p>
<pre class="cpp"> rumble<span class="operator">.</span>start();</pre>
<p>Custom haptic effects are stateful, and so they may be paused:</p>
<pre class="cpp"> rumble<span class="operator">.</span>pause();</pre>
<p>Or stopped:</p>
<pre class="cpp"> rumble<span class="operator">.</span>stop();</pre>
<p>Certain operations cannot be performed on an effect if it is in a certain state. The current state of the effect may be queried via the base-class API:</p>
<pre class="cpp"> <span class="keyword">if</span> (rumble<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)
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"The device has stopped rumbling!"</span>;</pre>
<p>All custom effects are played using a specific <a href="qfeedbackactuator.html">device actuator</a>. By default, the effect is played via the actuator which the current haptic effect provider plugin considers to be the system default actuator, and so most application developers will not need to change which actuator is used. In some cases, however, it may be desirable to set which actuator the effect is played on; doing so requires prior knowledge of either the name or the id of the actuator on which the developer wishes the effect to be played:</p>
<pre class="cpp"> <span class="type"><a href="qfeedbackactuator.html">QFeedbackActuator</a></span> <span class="operator">*</span>actuator <span class="operator">=</span> <span class="number">0</span>; <span class="comment">// default system actuator</span>
<span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qfeedbackactuator.html">QFeedbackActuator</a></span><span class="operator">*</span><span class="operator">></span> actuators <span class="operator">=</span> <span class="type"><a href="qfeedbackactuator.html">QFeedbackActuator</a></span><span class="operator">::</span>actuators();
foreach (<span class="type"><a href="qfeedbackactuator.html">QFeedbackActuator</a></span><span class="operator">*</span> temp<span class="operator">,</span> actuators) {
<span class="keyword">if</span> (temp<span class="operator">-</span><span class="operator">></span>name() <span class="operator">=</span><span class="operator">=</span> <span class="string">"ExampleActuatorName"</span>) {
actuator <span class="operator">=</span> temp;
}
}
rumble<span class="operator">.</span>setActuator(actuator);</pre>
<p>Finally, there is software available which allows "haptic tunes" to be saved to file, for later playback. If the haptic file effect provider plugin on the system understands that file format, the file can be played on device:</p>
<pre class="cpp"> <span class="type">QFeedbackFileEffect</span> hapticTune;
hapticTune<span class="operator">.</span>setSource(<span class="type">QUrl</span><span class="operator">::</span>fromLocalFile(<span class="string">"mySavedRumble.ivt"</span>));
hapticTune<span class="operator">.</span>load();
hapticTune<span class="operator">.</span>start();</pre>
<p>In addition, small audio effects can be played as feedback.</p>
<p>If you wish to see a simple example application which demonstrates some of the above code in use, please see the <a href="qtfeedback-hapticsquare-example.html">Haptic Square</a> example application.</p>
<a name="main-classes"></a>
<h2 id="main-classes">Main Classes</h2>
<ul>
<li><a href="qfeedbackeffect.html">QFeedbackEffect</a></li>
<li><a href="qfeedbackhapticseffect.html">QFeedbackHapticsEffect</a></li>
<li>QFeedbackFileEffect</li>
<li><a href="qfeedbackactuator.html">QFeedbackActuator</a></li>
<li><a href="qfeedbackinterface.html">QFeedbackInterface</a></li>
</ul>
<a name="examples"></a>
<h2 id="examples">Examples</h2>
<ul>
<li><a href="qtfeedback-hapticsquare-example.html">Haptic Square</a></li>
<li><a href="qtfeedback-hapticsplayer-example.html">Haptics Player</a></li>
</ul>
</div>
<!-- @@@qtfeedback-index.html -->
<div class="footer">Copyright (c) 2011 Nokia Corporation and/or its subsidiaries. All rights reserved.</div>
</body>
</html>
|