- From: CVS User akostiai <cvsmail@w3.org>
- Date: Mon, 27 May 2013 07:00:26 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/vibration
In directory roscoe:/tmp/cvs-serv28281
Added Files:
Overview.src.html
Log Message:
add Overview.src.html (see Overview.html for previous CVS log)
--- /sources/public/2009/dap/vibration/Overview.src.html 2013/05/27 07:00:26 NONE
+++ /sources/public/2009/dap/vibration/Overview.src.html 2013/05/27 07:00:26 1.1
<!DOCTYPE html>
<html>
<head>
<title>Vibration API</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='http://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
<script class='remove'>
var respecConfig = {
specStatus: "ED",
shortName: "vibration",
//publishDate: "2013-05-08",
previousPublishDate: "2013-05-23",
previousMaturity: "LC",
edDraftURI: "http://dev.w3.org/2009/dap/vibration/",
//lcEnd: "2013-06-13",
editors: [
{ name: "Anssi Kostiainen", company: "Intel" }
],
inlineCSS: true,
noIDLIn: true,
noLegacyStyle:true,
extraCSS: ["../ReSpec.js/css/respec.css"],
wg: "Device APIs Working Group",
wgURI: "http://www.w3.org/2009/dap/",
wgPublicList: "public-device-apis",
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
};
</script>
</head>
<body>
<section id='abstract'>
This specification defines an API that provides access to the vibration
mechanism of the hosting device. Vibration is a form of tactile feedback.
</section>
<section id='sotd'>
<p>
This document represents the consensus of the group on the scope and
features of the Vibration API. It should be noted that the group is
aware of more advanced use cases that cannot be realized using this
simpler first version. The intent is to address them in a future
revision.
</p>
</section>
<section class="informative">
<h2>Introduction</h2>
<p>
The API is specifically designed to address use cases that require
simple tactile feedback only. Use cases requiring more fine-grained
control are out of scope for this specification. In addition, the API
is not meant to be used as a generic notification mechanism.
</p>
</section>
<section id='conformance'>
<p>
This specification defines conformance criteria that apply to a single
product: the <dfn id="ua">user agent</dfn> that implements the
interfaces that it contains.
</p>
<p>
Implementations that use ECMAScript to implement the APIs defined in
this specification must implement them in a manner consistent with the
ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]],
as this specification uses that specification and terminology.
</p>
</section>
<section>
<h2>Terminology</h2>
<p>
The concepts <dfn><a href="http://dev.w3.org/html5/spec/browsers.html#browsing-context">
browsing context</a></dfn> and
<dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#spin-the-event-loop">
spin the event loop</a></dfn> are defined in [[!HTML5]].
</p>
</section>
<section>
<h2>Vibration Interface</h2>
<dl title='partial interface Navigator' class='idl'>
<dt>boolean vibrate()</dt>
<dd>
<dl class='parameters'>
<dt>(unsigned long or sequence<unsigned long>) pattern</dt>
<dd></dd>
</dl>
</dd>
</dl>
<p>
The <code>vibrate()</code> method, when invoked, MUST run the algorithm
for <a>processing vibration patterns</a>.
</p>
<p>
The rules for <dfn>processing vibration patterns</dfn> are as given in
the following algorithm:
</p>
<ol>
<li>
Let <var>pattern</var> be the value of the first argument.
</li>
<li>
If <var>pattern</var> is a list, proceed to the next step.
Otherwise run the following substeps:
<ol>
<li>
Let <var>list</var> be an initially empty list, and add
<var>pattern</var> to <var>list</var>.
</li>
<li>
Set <var>pattern</var> to <var>list</var>.
</li>
</ol>
</li>
<li>
If any entry of <var>pattern</var> exceeds an
implementation-dependent limit, then return false and terminate
these steps.
</li>
<li>
If the length of <var>pattern</var> is even and is not zero, then
remove the last entry in <var>pattern</var>.
</li>
<li>
If the length of <var>pattern</var> exceeds an
implementation-dependent limit, then return false and terminate
these steps.
</li>
<li>
If the <code>
<a href="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html#dom-document-hidden">
hidden</a></code> attribute [[!PAGE-VISIBILITY]] is set to true,
then return false and terminate these steps.
<div class="note">
A trusted (also known as privileged) application that integrates
closely with the operating system's functionality may vibrate the
device even if such an application is not visible at all, and thus
may ignore the previous step.
</div>
</li>
<li>
An implementation MAY return false and terminate these steps.
<div class="note">
For example, an implementation might abort the
algorithm because the user has set a preference indicating that
pages at a given origin should never be able to vibrate the device,
or an implementation might cap the total amount of time a page may
cause the device to vibrate and reject requests in excess of this
limit.
</div>
</li>
<li>
Cancel the pre-existing instance of the <a>processing vibration
patterns</a> algorithm, if any.
</li>
<li>
If <var>pattern</var> is an empty list, or if the device does
not provide a vibration mechanism (or it is disabled), then return
true and terminate these steps.
</li>
<li>
Return true, and then continue running these steps asynchronously.
</li>
<li>
For each <var>time</var> in <var>pattern</var>, run the following
substeps:
<ol>
<li>
If the index of <var>time</var> is even (the first entry has
index 0), vibrate the device for <var>time</var> milliseconds.
</li>
<li>
Otherwise wait for <var>time</var> milliseconds.
</li>
</ol>
</li>
</ol>
<p>
When the
<code><a href="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html#sec-visibilitychange-event">
visibilitychange</a></code> event [[!PAGE-VISIBILITY]] is dispatched at
the <code>Document</code> in a <a>browsing context</a>, the
<a class="product-ua" href="#ua">user agent</a> MUST cancel the
pre-existing instance of the <a>processing vibration patterns</a>
algorithm, if any.
</p>
</section>
<section class='informative'>
<h2>Examples</h2>
<p>
In the following example the device will vibrate for 1000 milliseconds (ms):
<pre class='example sh_javascript'>
// vibrate for 1000 ms
navigator.vibrate(1000);
// or alternatively
navigator.vibrate([1000]);
</pre>
<p>
In the following example the pattern will cause the device to vibrate
for 50 ms, be still for 100 ms, and then vibrate for 150 ms:
</p>
<pre class='example sh_javascript'>
navigator.vibrate([50, 100, 150]);
</pre>
<p>
<p>
The following example cancels any existing vibrations:
</p>
<pre class='example sh_javascript'>
// cancel any existing vibrations
navigator.vibrate(0);
// or alternatively
navigator.vibrate([]);
</pre>
</section>
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
The group is deeply indebted to Justin Lebar, Mounir Lamouri, Jonas
Sicking, and the Mozilla WebAPI team for their contributions, and for
providing the WebVibrator prototype as an initial input.
</p>
</section>
</body>
</html>
Received on Monday, 27 May 2013 07:00:35 UTC