Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 W3C technical reports index at http://www.w3.org/TR/.
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.
This document was published by the Device APIs Working Group as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). The Last Call period ends 01 March 2012. All feedback is welcome.
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.
This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures 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 Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
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.
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.
The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Navigator implements Vibration
;
interface Vibration {
void vibrate (unsigned long time) raises (NotSupportedError);
void vibrate (unsigned long[] pattern) raises (NotSupportedError);
};
vibrate
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
time | unsigned long | ✘ | ✘ | Vibration time in milliseconds. |
Exception | Description | ||
---|---|---|---|
NotSupportedError |
|
void
vibrate
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
pattern | unsigned long[] | ✘ | ✘ | 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. |
Exception | Description | ||
---|---|---|---|
NotSupportedError |
|
void
The vibrate()
method, when invoked, must run the algorithm
for processing vibration patterns.
The rules for processing vibration patterns are as given in the following algorithm:
hidden
attribute [PAGE-VISIBILITY] is set to true,
abort these steps.
NotSupportedError
exception and abort these steps.
NotSupportedError
exception [DOM4] and
abort these steps.
When the
visibilitychange
event [PAGE-VISIBILITY] is dispatched at
the Document
, the user
agent must run the following steps:
hidden
attribute [PAGE-VISIBILITY] is set to true,
the user agent must suppress
the vibration produced by running the pre-existing instance of the
processing vibration patterns algorithm, if any.
hidden
attribute [PAGE-VISIBILITY] is set to false,
the user agent must restore
the vibration produced by running the pre-existing instance of the processing vibration
patterns algorithm, if any.
If the device does not provide a vibration mechanism, or it is
disabled, the user agent must
silently ignore any invocations of the vibrate()
method.
This section is non-normative.
In the following example the device vibrates for 1 second:
// vibrate for 1 second navigator.vibrate(1000); // or alternatively navigator.vibrate([1000]);
In the following example the device vibrates for 1 second, is still for 0.5 seconds, and vibrates again for 2 seconds:
navigator.vibrate([1000, 500, 2000]);
The following example cancels any existing vibrations:
navigator.vibrate(0); // or alternatively navigator.vibrate([]);
The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and the Mozilla WebAPI team in general for providing the WebVibrator prototype as an initial input.
No informative references.