- From: Robin Berjon via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 16 Nov 2011 16:11:05 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/vibration
In directory hutz:/tmp/cvs-serv563
Added Files:
FPWD.html
Log Message:
snapshot
--- NEW FILE: FPWD.html ---
<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'>
<html lang="en" dir="ltr">
<head>
<title>Vibration API</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<style type="text/css">
/*****************************************************************
* ReSpec CSS
* Robin Berjon (robin at berjon dot com)
* v0.05 - 2009-07-31
*****************************************************************/
/* --- INLINES --- */
em.rfc2119 {
text-transform: lowercase;
font-variant: small-caps;
font-style: normal;
color: #900;
}
h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
border: none;
}
dfn {
font-weight: bold;
}
a.internalDFN {
color: inherit;
border-bottom: 1px solid #99c;
text-decoration: none;
}
a.externalDFN {
color: inherit;
border-bottom: 1px dotted #ccc;
text-decoration: none;
}
a.bibref {
text-decoration: none;
}
code {
color: #ff4500;
}
/* --- WEB IDL --- */
pre.idl {
border-top: 1px solid #90b8de;
border-bottom: 1px solid #90b8de;
padding: 1em;
line-height: 120%;
}
pre.idl::before {
content: "WebIDL";
display: block;
width: 150px;
background: #90b8de;
color: #fff;
font-family: initial;
padding: 3px;
font-weight: bold;
margin: -1em 0 1em -1em;
}
.idlType {
color: #ff4500;
font-weight: bold;
text-decoration: none;
}
/*.idlModule*/
/*.idlModuleID*/
/*.idlInterface*/
.idlInterfaceID, .idlDictionaryID {
font-weight: bold;
color: #005a9c;
}
.idlSuperclass {
font-style: italic;
color: #005a9c;
}
/*.idlAttribute*/
.idlAttrType, .idlFieldType, .idlMemberType {
color: #005a9c;
}
.idlAttrName, .idlFieldName, .idlMemberName {
color: #ff4500;
}
.idlAttrName a, .idlFieldName a, .idlMemberName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlMethod*/
.idlMethType {
color: #005a9c;
}
.idlMethName {
color: #ff4500;
}
.idlMethName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlParam*/
.idlParamType {
color: #005a9c;
}
.idlParamName {
font-style: italic;
}
.extAttr {
color: #666;
}
/*.idlConst*/
.idlConstType {
color: #005a9c;
}
.idlConstName {
color: #ff4500;
}
.idlConstName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlException*/
.idlExceptionID {
font-weight: bold;
color: #c00;
}
.idlTypedefID, .idlTypedefType {
color: #005a9c;
}
.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
color: #c00;
font-weight: normal;
}
.excName a {
font-family: monospace;
}
.idlRaises a.idlType, .excName a.idlType {
border-bottom: 1px dotted #c00;
}
.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
width: 45px;
text-align: center;
}
.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
.idlImplements a {
font-weight: bold;
}
dl.attributes, dl.methods, dl.constants, dl.fields, dl.dictionary-members {
margin-left: 2em;
}
.attributes dt, .methods dt, .constants dt, .fields dt, .dictionary-members dt {
font-weight: normal;
}
.attributes dt code, .methods dt code, .constants dt code, .fields dt code, .dictionary-members dt code {
font-weight: bold;
color: #000;
font-family: monospace;
}
.attributes dt code, .fields dt code, .dictionary-members dt code {
background: #ffffd2;
}
.attributes dt .idlAttrType code, .fields dt .idlFieldType code, .dictionary-members dt .idlMemberType code {
color: #005a9c;
background: transparent;
font-family: inherit;
font-weight: normal;
font-style: italic;
}
.methods dt code {
background: #d9e6f8;
}
.constants dt code {
background: #ddffd2;
}
.attributes dd, .methods dd, .constants dd, .fields dd, .dictionary-members dd {
margin-bottom: 1em;
}
table.parameters, table.exceptions {
border-spacing: 0;
border-collapse: collapse;
margin: 0.5em 0;
width: 100%;
}
table.parameters { border-bottom: 1px solid #90b8de; }
table.exceptions { border-bottom: 1px solid #deb890; }
.parameters th, .exceptions th {
color: #fff;
padding: 3px 5px;
text-align: left;
font-family: initial;
font-weight: normal;
text-shadow: #666 1px 1px 0;
}
.parameters th { background: #90b8de; }
.exceptions th { background: #deb890; }
.parameters td, .exceptions td {
padding: 3px 10px;
border-top: 1px solid #ddd;
vertical-align: top;
}
.parameters tr:first-child td, .exceptions tr:first-child td {
border-top: none;
}
.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
width: 100px;
}
.parameters td.prmType {
width: 120px;
}
table.exceptions table {
border-spacing: 0;
border-collapse: collapse;
width: 100%;
}
/* --- TOC --- */
.toc a {
text-decoration: none;
}
a .secno {
color: #000;
}
/* --- TABLE --- */
table.simple {
border-spacing: 0;
border-collapse: collapse;
border-bottom: 3px solid #005a9c;
}
.simple th {
background: #005a9c;
color: #fff;
padding: 3px 5px;
text-align: left;
}
.simple th[scope="row"] {
background: inherit;
color: inherit;
border-top: 1px solid #ddd;
}
.simple td {
padding: 3px 10px;
border-top: 1px solid #ddd;
}
.simple tr:nth-child(even) {
background: #f0f6ff;
}
/* --- DL --- */
.section dd > p:first-child {
margin-top: 0;
}
.section dd > p:last-child {
margin-bottom: 0;
}
.section dd {
margin-bottom: 1em;
}
.section dl.attrs dd, .section dl.eldef dd {
margin-bottom: 0;
}
/* --- EXAMPLES --- */
pre.example {
border-top: 1px solid #ff4500;
border-bottom: 1px solid #ff4500;
padding: 1em;
margin-top: 1em;
}
pre.example::before {
content: "Example";
display: block;
width: 150px;
background: #ff4500;
color: #fff;
font-family: initial;
padding: 3px;
font-weight: bold;
margin: -1em 0 1em -1em;
}
/* --- EDITORIAL NOTES --- */
.issue {
padding: 1em;
margin: 1em 0em 0em;
border: 1px solid #f00;
background: #ffc;
}
.issue::before {
content: "Issue";
display: block;
width: 150px;
margin: -1.5em 0 0.5em 0;
font-weight: bold;
border: 1px solid #f00;
background: #fff;
padding: 3px 1em;
}
.note {
margin: 1em 0em 0em;
padding: 1em;
border: 2px solid #cff6d9;
background: #e2fff0;
}
.note::before {
content: "Note";
display: block;
width: 150px;
margin: -1.5em 0 0.5em 0;
font-weight: bold;
border: 1px solid #cff6d9;
background: #fff;
padding: 3px 1em;
}
/* --- Best Practices --- */
div.practice {
border: solid #bebebe 1px;
margin: 2em 1em 1em 2em;
}
span.practicelab {
margin: 1.5em 0.5em 1em 1em;
font-weight: bold;
font-style: italic;
}
span.practicelab { background: #dfffff; }
span.practicelab {
position: relative;
padding: 0 0.5em;
top: -1.5em;
}
p.practicedesc {
margin: 1.5em 0.5em 1em 1em;
}
@media screen {
p.practicedesc {
position: relative;
top: -2em;
padding: 0;
margin: 1.5em 0.5em -1em 1em;
}
}
/* --- SYNTAX HIGHLIGHTING --- */
pre.sh_sourceCode {
background-color: white;
color: black;
font-style: normal;
font-weight: normal;
}
pre.sh_sourceCode .sh_keyword { color: #005a9c; font-weight: bold; } /* language keywords */
pre.sh_sourceCode .sh_type { color: #666; } /* basic types */
pre.sh_sourceCode .sh_usertype { color: teal; } /* user defined types */
pre.sh_sourceCode .sh_string { color: red; font-family: monospace; } /* strings and chars */
pre.sh_sourceCode .sh_regexp { color: orange; font-family: monospace; } /* regular expressions */
pre.sh_sourceCode .sh_specialchar { color: #ffc0cb; font-family: monospace; } /* e.g., \n, \t, \\ */
pre.sh_sourceCode .sh_comment { color: #A52A2A; font-style: italic; } /* comments */
pre.sh_sourceCode .sh_number { color: purple; } /* literal numbers */
pre.sh_sourceCode .sh_preproc { color: #00008B; font-weight: bold; } /* e.g., #include, import */
pre.sh_sourceCode .sh_symbol { color: blue; } /* e.g., *, + */
pre.sh_sourceCode .sh_function { color: black; font-weight: bold; } /* function calls and declarations */
pre.sh_sourceCode .sh_cbracket { color: red; } /* block brackets (e.g., {, }) */
pre.sh_sourceCode .sh_todo { font-weight: bold; background-color: #00FFFF; } /* TODO and FIXME */
/* Predefined variables and functions (for instance glsl) */
pre.sh_sourceCode .sh_predef_var { color: #00008B; }
pre.sh_sourceCode .sh_predef_func { color: #00008B; font-weight: bold; }
/* for OOP */
pre.sh_sourceCode .sh_classname { color: teal; }
/* line numbers (not yet implemented) */
pre.sh_sourceCode .sh_linenum { display: none; }
/* Internet related */
pre.sh_sourceCode .sh_url { color: blue; text-decoration: underline; font-family: monospace; }
/* for ChangeLog and Log files */
pre.sh_sourceCode .sh_date { color: blue; font-weight: bold; }
pre.sh_sourceCode .sh_time, pre.sh_sourceCode .sh_file { color: #00008B; font-weight: bold; }
pre.sh_sourceCode .sh_ip, pre.sh_sourceCode .sh_name { color: #006400; }
/* for Prolog, Perl... */
pre.sh_sourceCode .sh_variable { color: #006400; }
/* for LaTeX */
pre.sh_sourceCode .sh_italics { color: #006400; font-style: italic; }
pre.sh_sourceCode .sh_bold { color: #006400; font-weight: bold; }
pre.sh_sourceCode .sh_underline { color: #006400; text-decoration: underline; }
pre.sh_sourceCode .sh_fixed { color: green; font-family: monospace; }
pre.sh_sourceCode .sh_argument { color: #006400; }
pre.sh_sourceCode .sh_optionalargument { color: purple; }
pre.sh_sourceCode .sh_math { color: orange; }
pre.sh_sourceCode .sh_bibtex { color: blue; }
/* for diffs */
pre.sh_sourceCode .sh_oldfile { color: orange; }
pre.sh_sourceCode .sh_newfile { color: #006400; }
pre.sh_sourceCode .sh_difflines { color: blue; }
/* for css */
pre.sh_sourceCode .sh_selector { color: purple; }
pre.sh_sourceCode .sh_property { color: blue; }
pre.sh_sourceCode .sh_value { color: #006400; font-style: italic; }
/* other */
pre.sh_sourceCode .sh_section { color: black; font-weight: bold; }
pre.sh_sourceCode .sh_paren { color: red; }
pre.sh_sourceCode .sh_attribute { color: #006400; }
</style><link charset="utf-8" type="text/css" rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-WD"></head>
<body style="display: inherit;"><div class="head"><p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a></p><h1 class="title" id="title">Vibration API</h1><h2 id="w3c-working-draft-17-november-2011">W3C Working Draft 17 November 2011</h2><dl><dt>This version:</dt><dd><a href="http://www.w3.org/TR/2011/WD-vibration-20111117/">http://www.w3.org/TR/2011/WD-vibration-20111117/</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/vibration/">http://www.w3.org/TR/vibration/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2009/dap/vibration/">http://dev.w3.org/2009/dap/vibration/</a></dd><dt>Editor:</dt><dd><span>Anssi Kostiainen</span>, Nokia</dd>
</dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2011 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p><hr></div>
<div class="introductory section" id="abstract"><h2>Abstract</h2>
This specification defines an API that provides access to the vibration
mechanism of the hosting device. Vibration is a form of tactile feedback.
</div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em></p>
<p>
This document represents the early 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 realised using this simpler first version. The intent is to address them in a future revision.
</p>
<p>This document was published by the <a href="http://www.w3.org/2009/dap/">Device APIs Working Group</a> as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to <a href="mailto:public-device-apis@w3.org">public-device-apis@w3.org</a> (<a href="mailto:public-device-apis-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-device-apis/">archives</a>). All feedback is welcome.</p><p>Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-imp/43696/status" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.</p></div><div class="section" id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a class="tocxref" href="#introduction"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a class="tocxref" href="#conformance"><span class="secno">2. </span>Conformance</a></li><li class="tocline"><a class="tocxref" href="#vibration-interface"><span class="secno">3. </span>Vibration Interface</a><ul class="toc"><li class="toclie"><a class="tocxref" href="#methods"><span class="secno">3.1 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#examples"><span class="secno">4. </span>Examples</a></li><li class="tocline"><a class="tocxref" href="#acknowledgements"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a class="tocxref" href="#references"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a class="tocxref" href="#informative-references"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
<div id="introduction" class="informative section">
<!--OddPage--><h2><span class="secno">1. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
<p>
The Vibration API defines a means for web developers to
programmatically provide tactile feedback in the form of vibration. The
API is designed to tackle high-value use cases related to gaming, and
is not meant to be used as a generic notification mechanism.
</p>
</div>
<div class="section" id="conformance"><!--OddPage--><h2><span class="secno">2. </span>Conformance</h2><p>As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.</p>
<p>The key words <em title="must" class="rfc2119">must</em>, <em title="must not" class="rfc2119">must not</em>, <em title="required" class="rfc2119">required</em>, <em title="should" class="rfc2119">should</em>, <em title="should not" class="rfc2119">should not</em>, <em title="recommended" class="rfc2119">recommended</em>, <em title="may" class="rfc2119">may</em>, and <em title="optional" class="rfc2119">optional</em> in this specification are to be interpreted as described in [<cite><a href="#bib-RFC2119" rel="biblioentry" class="bibref">RFC2119</a></cite>].</p>
<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>
</div>
<div class="section" id="vibration-interface">
<!--OddPage--><h2><span class="secno">3. </span>Vibration Interface</h2>
<pre class="idl"><span class="idlImplements"><a>Navigator</a> implements <a class="idlType" href="#idl-def-Vibration"><code>Vibration</code></a>;</span></pre><div class="idlImplementsDesc"><p>All instances of the <code><a>Navigator</a></code> type are defined to also implement the <a class="idlType" href="#idl-def-Vibration"><code>Vibration</code></a> interface.</p></div>
<pre class="idl"><span class="idlInterface" id="idl-def-Vibration">interface <span class="idlInterfaceID">Vibration</span> {
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Vibration-vibrate-void-unsigned-long-time">vibrate</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>unsigned long</a></span> <span class="idlParamName">time</span></span>) raises (<span class="idlRaises"><a>NotSupportedError</a></span>);</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Vibration-vibrate-void-unsigned-longArray-pattern">vibrate</a></span> (<span class="idlParam">optional <span class="idlParamType"><a>unsigned long</a>[]</span> <span class="idlParamName">pattern</span></span>) raises (<span class="idlRaises"><a>NotSupportedError</a></span>);</span>
};</span>
</pre><div class="section" id="methods"><h3><span class="secno">3.1 </span>Methods</h3><dl class="methods"><dt id="widl-Vibration-vibrate-void-unsigned-long-time"><code>vibrate</code></dt><dd>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">time</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
Vibration time in milliseconds.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>NotSupportedError</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>
NOT_SUPPORTED_ERR (9)
</code></td><td class="excCodeDesc">
The <code>time</code> argument exceeds an implementation
dependent limit.
</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-Vibration-vibrate-void-unsigned-longArray-pattern"><code>vibrate</code></dt><dd>
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">pattern</td><td class="prmType"><code><a>unsigned long</a>[]</code></td><td class="prmNullFalse">✘</td><td class="prmOptTrue">✔</td><td class="prmDesc">
A vibration pattern represented by a list of time entries.
Odd entries represent vibration time in milliseconds, even
entries still periods in milliseconds between the vibrations.
</td></tr></table><table class="exceptions"><tr><th>Exception</th><th>Description</th></tr><tr><td class="excName"><a>NotSupportedError</a></td><td class="excDesc"><table class="exceptionCodes"><tr><td class="excCodeName"><code>
NOT_SUPPORTED_ERR (9)
</code></td><td class="excCodeDesc">
The length of the <code>pattern</code> argument exceeds an
implementation-dependent limit, or one or more entries in the
<code>pattern</code> argument exceed an implementation
dependent limit.
</td></tr></table></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
<p>
The <code>vibrate()</code> method, when invoked, <em title="must" class="rfc2119">must</em> run the algorithm
for <a class="internalDFN" href="#dfn-processing-vibration-patterns">processing vibration patterns</a>.
</p>
<p>
The rules for <dfn id="dfn-processing-vibration-patterns">processing vibration patterns</dfn> are as given in
the following algorithm:
</p>
<ol>
<!--li>
If the <var>already started</var> flag is set to true, 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.
</li-->
<li>
If the <code>
<a href="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html#pv-hidden">
hidden</a></code> attribute [<cite><a href="#bib-PAGE-VISIBILITY" rel="biblioentry" class="bibref">PAGE-VISIBILITY</a></cite>] is set to true,
abort these steps.
</li>
<!--li>
Let <var>already started</var> flag be true.
</li-->
<li>
Let <var>pattern</var> be the value of the first argument.
</li>
<li>
If <var>pattern</var> is 0, an empty list, or <code>null</code>, cancel the pre-existing
instance of the <a class="internalDFN" href="#dfn-processing-vibration-patterns">processing vibration patterns</a> algorithm, if
any, and abort these steps.
</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>
Let <var>pattern</var> be <var>list</var>.
</li>
</ol>
</li>
<li>
If any entry of <var>pattern</var> exceeds an
implementation-dependent limit, then the
<a class="product-ua" href="#ua">user agent</a> <em title="may" class="rfc2119">may</em> throw a
<code>NotSupportedError</code> exception and abort these steps.
</li>
<li>
If the length of <var>pattern</var> is even, then remove the last
entry in <var>pattern</var>.
</li>
<li>
If the length of <var>pattern</var> exceeds an implementation
dependent limit, the <a class="product-ua" href="#ua">user agent</a>
<em title="may" class="rfc2119">may</em> throw a <code>NotSupportedError</code> exception [<cite><a href="#bib-DOM4" rel="biblioentry" class="bibref">DOM4</a></cite>] and
abort these steps.
</li>
<li>
Cancel the pre-existing instance of the <a class="internalDFN" href="#dfn-processing-vibration-patterns">processing vibration
patterns</a> algorithm, if any.
</li>
<li>
An implementation <em title="may" class="rfc2119">may</em> abort the algorithm at this point.
<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>
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 earliest even entry
has index 0), vibrate the device for <var>time</var>
milliseconds.
</li>
<li>
Otherwise
<a href="http://dev.w3.org/html5/spec/webappapis.html#pause">
pause</a> [<cite><a href="#bib-HTML5" rel="biblioentry" class="bibref">HTML5</a></cite>] 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 [<cite><a href="#bib-PAGE-VISIBILITY" rel="biblioentry" class="bibref">PAGE-VISIBILITY</a></cite>] is dispatched at
the <code>Document</code>, the <a class="product-ua" href="#ua">user
agent</a> <em title="must" class="rfc2119">must</em> run the following steps:
</p>
<ol>
<li>
If the <code><a href="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html#pv-hidden">
hidden</a></code> attribute [<cite><a href="#bib-PAGE-VISIBILITY" rel="biblioentry" class="bibref">PAGE-VISIBILITY</a></cite>] is set to true,
the <a class="product-ua" href="#ua">user agent</a> <em title="must" class="rfc2119">must</em> suppress
the vibration produced by running the pre-existing instance of the
<a class="internalDFN" href="#dfn-processing-vibration-patterns">processing vibration patterns</a> algorithm, if any.
</li>
<li>
If the <code><a href="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html#pv-hidden">
hidden</a></code> attribute [<cite><a href="#bib-PAGE-VISIBILITY" rel="biblioentry" class="bibref">PAGE-VISIBILITY</a></cite>] is set to false,
the <a class="product-ua" href="#ua">user agent</a> <em title="must" class="rfc2119">must</em> restore
the vibration produced by running the pre-existing instance of the <a class="internalDFN" href="#dfn-processing-vibration-patterns">processing vibration
patterns</a> algorithm, if any.
</li>
</ol>
<p>
If the device does not provide a vibration mechanism, or it is
disabled, the <a class="product-ua" href="#ua">user agent</a> <em title="must" class="rfc2119">must</em>
silently ignore any invocations of the <code>vibrate()</code> method.
</p>
</div>
<div id="examples" class="informative section">
<!--OddPage--><h2><span class="secno">4. </span>Examples</h2><p><em>This section is non-normative.</em></p>
<p>
This specification is inspired by Mozilla's
<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=679966">
Web Vibrator prototype</a>. Below is an excerpt extracted from
the
<a href="https://bugzilla.mozilla.org/attachment.cgi?id=571161&action=diff#a/dom/interfaces/base/nsIDOMNavigator.idl_sec2">
source code</a> to be more readily available:
</p>
<div class="example">
<pre class="example sh_javascript sh_sourceCode"><span class="sh_comment">/**</span>
<span class="sh_comment"> * Pulse the device's vibrator, if it has one. If the device does not have a</span>
<span class="sh_comment"> * vibrator, this function does nothing.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * mozVibrate takes one optional argument. The argument specifies how long</span>
<span class="sh_comment"> * to vibrate for, or it gives a pattern of vibrator-on/vibrator-off timings.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * If a vibration pattern is in effect when this function is called, this</span>
<span class="sh_comment"> * call will overwrite the existing pattern, if this call successfully</span>
<span class="sh_comment"> * completes.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * We handle the argument to mozVibrate as follows.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * - If the argument is undefined, null, 0, or the empty list, we cancel any</span>
<span class="sh_comment"> * outstanding vibration pattern; that is, we stop the device from vibrating.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * - Otherwise, if the argument X is not a list, we treat it as though it's</span>
<span class="sh_comment"> * the singleton list [X] and then proceed as below.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * - If the argument is a list (or if we wrapped it as a list above), then we</span>
<span class="sh_comment"> * try to convert each element in the list to an integer, by first</span>
<span class="sh_comment"> * converting it to a number and then rounding. If we cannot convert any</span>
<span class="sh_comment"> * element to an integer, or if any of the integers are negative, we throw</span>
<span class="sh_comment"> * an illegal value exception.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * This list of integers specifies a vibration pattern. Given a list of</span>
<span class="sh_comment"> * numbers</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * [a_1, b_1, a_2, b_2, ..., a_n]</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * the device will vibrate for a_1 milliseconds, then be still for b_1</span>
<span class="sh_comment"> * milliseconds, then vibrate for a_2 milliseconds, and so on.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * The list may contain an even or an odd number of elements, but if you</span>
<span class="sh_comment"> * pass an even number of elements (that is, if your list ends with b_n</span>
<span class="sh_comment"> * instead of a_n), the final element doesn't specify anything meaningful.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> * We may throw an illegal value exception if the vibration pattern is too</span>
<span class="sh_comment"> * long, or if any of its elements is too large.</span>
<span class="sh_comment"> *</span>
<span class="sh_comment"> */</span>
<span class="sh_symbol">[</span>implicit_jscontext<span class="sh_symbol">]</span>
void <span class="sh_function">mozVibrate</span><span class="sh_symbol">([</span>optional<span class="sh_symbol">]</span> <span class="sh_keyword">in</span> jsval aPattern<span class="sh_symbol">);</span></pre>
</div>
<p>
In the following example the device vibrates for 1 second:
</p><div class="example">
<pre class="example sh_javascript sh_sourceCode"><span class="sh_comment">// vibrate for 1 second</span>
navigator<span class="sh_symbol">.</span><span class="sh_function">vibrate</span><span class="sh_symbol">(</span><span class="sh_number">1000</span><span class="sh_symbol">);</span>
<span class="sh_comment">// or alternatively</span>
navigator<span class="sh_symbol">.</span><span class="sh_function">vibrate</span><span class="sh_symbol">([</span><span class="sh_number">1000</span><span class="sh_symbol">]);</span></pre>
</div>
<p>
In the following example the device vibrates for 1 second, is still for
0.5 seconds, and vibrates again for 2 seconds:
</p>
<div class="example">
<pre class="example sh_javascript sh_sourceCode">navigator<span class="sh_symbol">.</span><span class="sh_function">vibrate</span><span class="sh_symbol">([</span><span class="sh_number">1000</span><span class="sh_symbol">,</span> <span class="sh_number">500</span><span class="sh_symbol">,</span> <span class="sh_number">2000</span><span class="sh_symbol">]);</span></pre>
</div>
<p>
</p><p>
The following example cancels any existing vibrations:
</p>
<div class="example">
<pre class="example sh_javascript sh_sourceCode">navigator<span class="sh_symbol">.</span><span class="sh_function">vibrate</span><span class="sh_symbol">(</span><span class="sh_number">0</span><span class="sh_symbol">);</span>
<span class="sh_comment">// or alternatively</span>
navigator<span class="sh_symbol">.</span><span class="sh_function">vibrate</span><span class="sh_symbol">([]);</span></pre>
</div>
</div>
<div id="acknowledgements" class="appendix section">
<!--OddPage--><h2><span class="secno">A. </span>Acknowledgements</h2>
<p>
Thanks to the Mozilla WebAPI team for providing the WebVibrator
prototype as an initial input.
</p>
</div>
<div class="appendix section" id="references"><!--OddPage--><h2><span class="secno">B. </span>References</h2><div class="section" id="normative-references"><h3><span class="secno">B.1 </span>Normative references</h3><dl class="bibliography"><dt id="bib-DOM4">[DOM4]</dt><dd>Anne van Kesteren; Ms2ger. <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html"><cite>DOM4.</cite></a> 7 September 2011. W3C Editor's Draft. (Work in progress.) URL: <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html">http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html</a>
</dd><dt id="bib-HTML5">[HTML5]</dt><dd>Ian Hickson; David Hyatt. <a href="http://www.w3.org/TR/html5"><cite>HTML5.</cite></a> 25 May 2011. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/html5">http://www.w3.org/TR/html5</a>
</dd><dt id="bib-PAGE-VISIBILITY">[PAGE-VISIBILITY]</dt><dd>J. Mann; A. Jain. <a href="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html"><cite>Page Visibility</cite></a>. 26 September 2011. W3C Editor's Draft. (Work in progress.) URL: <a href="http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html">http://dvcs.w3.org/hg/webperf/raw-file/tip/specs/PageVisibility/Overview.html</a>
</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels.</cite></a> March 1997. Internet RFC 2119. URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
</dd></dl></div><div class="section" id="informative-references"><h3><span class="secno">B.2 </span>Informative references</h3><p>No informative references.</p></div></div></body></html>
Received on Wednesday, 16 November 2011 16:11:13 UTC