--- a/light/Overview.html Mon Jan 28 08:56:58 2013 -0800
+++ b/light/Overview.html Wed Jan 30 10:38:51 2013 +0200
@@ -1,39 +1,437 @@
<!DOCTYPE html>
-<html>
- <head>
+<html lang="en" dir="ltr"><head>
<title>Ambient Light Events</title>
- <meta charset="utf-8"/>
- <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
- <script class="remove">
- var respecConfig = {
- specStatus: "ED",
- shortName: "ambient-light",
- //publishDate: "2012-12-13",
- previousPublishDate: "2012-12-13",
- previousMaturity: "LC",
- edDraftURI: "http://dvcs.w3.org/hg/dap/raw-file/tip/light/Overview.html",
- lcEnd: "2013-01-26",
- editors: [
- { name: "Doug Turner", company: "Mozilla Corporation", companyURL: "http://mozilla.com/" },
- { name: "Anssi Kostiainen", company: "Nokia", companyURL: "http://nokia.com/" }
- ],
- inlineCSS: true,
- noIDLIn: true,
- noLegacyStyle: true,
- 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">
+ <meta charset="utf-8">
+
+
+ <style>/*****************************************************************
+ * ReSpec 3 CSS
+ * Robin Berjon - http://berjon.com/
+ *****************************************************************/
+
+/* --- 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;
+}
+
+cite .bibref {
+ font-style: normal;
+}
+
+code {
+ color: #ff4500;
+}
+
+
+/* --- --- */
+ol.algorithm { counter-reset:numsection; list-style-type: none; }
+ol.algorithm li { margin: 0.5em 0; }
+ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; }
+
+/* --- TOC --- */
+.toc a, .tof a {
+ text-decoration: none;
+}
+
+a .secno, a .figno {
+ color: #000;
+}
+
+ul.tof, ol.tof {
+ list-style: none outside none;
+}
+
+.caption {
+ margin-top: 0.5em;
+ font-style: italic;
+}
+
+/* --- 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;
+}
+</style><style>/* --- ISSUES/NOTES --- */
+div.issue-title, div.note-title {
+ padding-right: 1em;
+ min-width: 7.5em;
+ color: #b9ab2d;
+}
+div.issue-title { color: #e05252; }
+div.note-title { color: #52e052; }
+div.issue-title span, div.note-title span {
+ text-transform: uppercase;
+}
+div.note, div.issue {
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+.note > p:first-child, .issue > p:first-child { margin-top: 0 }
+.issue, .note {
+ padding: .5em;
+ border-left-width: .5em;
+ border-left-style: solid;
+}
+div.issue, div.note {
+ padding: 0.5em;
+ margin: 1em 0;
+ position: relative;
+ clear: both;
+}
+span.note, span.issue { padding: .1em .5em .15em; }
+
+.issue {
+ border-color: #e05252;
+ background: #fbe9e9;
+}
+.note {
+ border-color: #52e052;
+ background: #e9fbe9;
+}
+
+
+</style><style>/* --- 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, .idlCallbackID, .idlEnumID {
+ 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, .idlCallbackType {
+ color: #005a9c;
+}
+.idlMethName {
+ color: #ff4500;
+}
+.idlMethName a {
+ color: #ff4500;
+ border-bottom: 1px dotted #ff4500;
+ text-decoration: none;
+}
+
+/*.idlParam*/
+.idlParamType {
+ color: #005a9c;
+}
+.idlParamName, .idlDefaultValue {
+ 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%;
+}
+</style><link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-ED"></head>
+ <body><div class="head">
+ <p>
+
+ <a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a>
+
+ </p>
+ <h1 class="title" id="title">Ambient Light Events</h1>
+
+ <h2 id="w3c-editor-s-draft-30-january-2013"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 30 January 2013</h2>
+ <dl>
+
+ <dt>This version:</dt>
+ <dd><a href="http://dvcs.w3.org/hg/dap/raw-file/tip/light/Overview.html">http://dvcs.w3.org/hg/dap/raw-file/tip/light/Overview.html</a></dd>
+ <dt>Latest published version:</dt>
+ <dd><a href="http://www.w3.org/TR/ambient-light/">http://www.w3.org/TR/ambient-light/</a></dd>
+
+
+ <dt>Latest editor's draft:</dt>
+ <dd><a href="http://dvcs.w3.org/hg/dap/raw-file/tip/light/Overview.html">http://dvcs.w3.org/hg/dap/raw-file/tip/light/Overview.html</a></dd>
+
+
+
+
+
+
+
+
+ <dt>Editors:</dt>
+ <dd><span>Doug Turner</span>, <a href="http://mozilla.com/">Mozilla Corporation</a></dd>
+<dd><span>Anssi Kostiainen</span>, <a href="http://nokia.com/">Nokia</a></dd>
+
+
+ </dl>
+
+
+
+
+
+ <p class="copyright">
+ <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> ©
+ 2013
+
+ <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup>
+ (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>,
+ <a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>,
+ <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved.
+ <abbr title="World Wide Web Consortium">W3C</abbr> <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>
+ <section id="abstract" class="introductory"><h2>Abstract</h2><p>
This specification defines a means to receive events that correspond to
a light sensor detecting the presence of a light.
- </section>
+ </p></section><section id="sotd" class="introductory"><h2>Status of This Document</h2>
+
- <section id="sotd">
+
+ <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 <abbr title="World Wide Web Consortium">W3C</abbr> publications and the latest revision
+ of this technical report can be found in the <a href="http://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports
+ index</a> at http://www.w3.org/TR/.</em>
+ </p>
+
<p>
The functionality described in this specification was initially
specified as part of the
@@ -48,154 +446,202 @@
include the addition of the Light Level section with the LightLevelEvent interface,
editorial cleanup, and an update to the references.
</p>
- </section>
- <section class="informative">
- <h2>Introduction</h2>
+ <p>
+ This document was published by the <a href="http://www.w3.org/2009/dap/">Device APIs Working Group</a> as an Editor's Draft.
+
+
+ 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 comments are welcome.
+
+
+ </p><p>
+ Publication as an Editor's Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr> 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 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
+
+
+
+
+ <abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a href="http://www.w3.org/2004/01/pp-impl/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 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
+
+
+ </p>
+
+
+
+
+</section><section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">2. </span>Conformance</a></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">3. </span>Terminology</a></li><li class="tocline"><a href="#security-and-privacy-considerations" class="tocxref"><span class="secno">4. </span>Security and privacy considerations</a></li><li class="tocline"><a href="#device-light" class="tocxref"><span class="secno">5. </span>Device Light</a><ul class="toc"><li class="tocline"><a href="#devicelightevent-interface" class="tocxref"><span class="secno">5.1 </span><span class="formerLink"><code>DeviceLightEvent</code></span> Interface</a><ul class="toc"><li class="tocline"><a href="#event-handlers" class="tocxref"><span class="secno">5.1.1 </span>Event handlers</a></li></ul></li></ul></li><li class="tocline"><a href="#light-level" class="tocxref"><span class="secno">6. </span>Light Level</a><ul class="toc"><li class="tocline"><a href="#lightlevelevent-interface" class="tocxref"><span class="secno">6.1 </span><span class="formerLink"><code>LightLevelEvent</code></span> Interface</a><ul class="toc"><li class="tocline"><a href="#event-handlers-1" class="tocxref"><span class="secno">6.1.1 </span>Event handlers</a></li></ul></li></ul></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li></ul></li></ul></section>
+
+
+
+ <section class="informative" id="introduction">
+ <!--OddPage--><h2><span class="secno">1. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
<p>
This specification defines events that provide information about the
ambient light level, as measured by a device's light sensor. A
- <a>LightLevelEvent</a> describes the light level as one of three simple
+ <a href="#idl-def-LightLevelEvent" class="idlType"><code>LightLevelEvent</code></a> describes the light level as one of three simple
categories - "dim", "normal", and "bright" - while a
- <a>DeviceLightEvent</a> provides a more granular answer by describing
+ <a href="#idl-def-DeviceLightEvent" class="idlType"><code>DeviceLightEvent</code></a> provides a more granular answer by describing
the light level in terms of lux units.
</p>
</section>
- <section id="conformance">
+ <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 class="rfc2119" title="must">must</em>, <em class="rfc2119" title="must not">must not</em>, <em class="rfc2119" title="required">required</em>, <em class="rfc2119" title="should">should</em>, <em class="rfc2119" title="should not">should not</em>, <em class="rfc2119" title="recommended">recommended</em>, <em class="rfc2119" title="may">may</em>,
+ and <em class="rfc2119" title="optional">optional</em> in this specification are to be interpreted as described in [<cite><a class="bibref" href="#bib-RFC2119">RFC2119</a></cite>].
+</p>
+
<p>
This specification defines conformance criteria that apply to a single
- product: the <dfn>user agent</dfn> that implements the
+ product: the <dfn id="dfn-user-agent">user agent</dfn> that implements the
interfaces that it contains.
</p>
</section>
- <section>
- <h2>Terminology</h2>
+ <section id="terminology">
+ <!--OddPage--><h2><span class="secno">3. </span>Terminology</h2>
<p>
The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
EventHandler</a></code> interface represents a <a href="http://www.w3.org/TR/WebIDL/#idl-callback-functions">callback function</a> used for <a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">event
- handlers</a> as defined in [[!HTML5]]. </p>
+ handlers</a> as defined in [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>]. </p>
<p>
- The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
+ The concepts <dfn id="dfn-queue-a-task"><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
queue a task</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
- fires a simple event</a></dfn> are defined in [[!HTML5]].
+ <dfn id="dfn-fires-a-simple-event"><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
+ fires a simple event</a></dfn> are defined in [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>].
</p>
<p>
- The terms <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
+ The terms <dfn id="dfn-event-handlers"><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
event handlers</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
- event handler event types</a></dfn> are defined in [[!HTML5]].
+ <dfn id="dfn-event-handler-event-types"><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
+ event handler event types</a></dfn> are defined in [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>].
</p>
- <p>The concepts <dfn>
+ <p>The concepts <dfn id="dfn-create-an-event">
<a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#constructing-events">
- create an event</a></dfn> and <dfn>
+ create an event</a></dfn> and <dfn id="dfn-fire-an-event">
<a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#firing-events">
- fire an event</a></dfn> are defined in [[!DOM4]].
- <p>
- The <dfn>current light level</dfn> is a value that represents the ambient
+ fire an event</a></dfn> are defined in [<cite><a class="bibref" href="#bib-DOM4">DOM4</a></cite>].
+ </p><p>
+ The <dfn id="dfn-current-light-level">current light level</dfn> is a value that represents the ambient
light levels around the hosting device in lux units.
</p>
<p>
- The <dfn>current light level state</dfn> represents the ambient light level
+ The <dfn id="dfn-current-light-level-state">current light level state</dfn> represents the ambient light level
around the hosting device as a human-readable string.
</p>
</section>
- <section>
- <h2>Security and privacy considerations</h2>
+ <section id="security-and-privacy-considerations">
+ <!--OddPage--><h2><span class="secno">4. </span>Security and privacy considerations</h2>
<p>
</p>
</section>
- <section>
- <h2>Device Light</h2>
+ <section id="device-light">
+ <!--OddPage--><h2><span class="secno">5. </span>Device Light</h2>
<p>
- The <a>DeviceLightEvent</a> interface provides information about the
+ The <a href="#idl-def-DeviceLightEvent" class="idlType"><code>DeviceLightEvent</code></a> interface provides information about the
ambient light levels, as detected by the device's light detector, in
terms of lux units.
</p>
<p>
- The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+ The HTML5 specification [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>] defines a <a href="#idl-def-Window" class="idlType"><code>Window</code></a> interface,
which this specification extends:
</p>
- <dl title="partial interface Window" class="idl">
- <dt>attribute EventHandler ondevicelight</dt>
- <dd>
- </dd>
- </dl>
+ <pre class="idl"><span class="idlInterface" id="idl-def-Window">partial interface <span class="idlInterfaceID">Window</span> {
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-Window-ondevicelight">ondevicelight</a></span>;</span>
+};</span></pre>
<p>
The <code>ondevicelight</code> event handler and its corresponding
- event handler event type <code>devicelight</code> MUST be supported
- as an IDL attribute by all objects implementing the <a>Window</a>
+ event handler event type <code>devicelight</code> <em class="rfc2119" title="must">must</em> be supported
+ as an IDL attribute by all objects implementing the <a href="#idl-def-Window" class="idlType"><code>Window</code></a>
interface.
</p>
- <section>
- <h2><a>DeviceLightEvent</a> Interface</h2>
- <dl title="[Constructor (DOMString type, optional DeviceLightEventInit eventInitDict)]
- interface DeviceLightEvent : Event"
- class="idl" data-merge='DeviceLightEventInit'>
- <dt>readonly attribute double value</dt>
- <dd>
- The <a>ambient light level in lux</a>.
- </dd>
- </dl>
- <dl title="dictionary DeviceLightEventInit : EventInit" class='idl'>
- <dt>
- double value
- </dt>
- <dd></dd>
- </dl>
+ <section id="devicelightevent-interface">
+ <h3><span class="secno">5.1 </span><a href="#idl-def-DeviceLightEvent" class="idlType"><code>DeviceLightEvent</code></a> Interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-DeviceLightEvent"><span class="idlDictionary" id="idl-def-DeviceLightEventInit">dictionary <span class="idlDictionaryID">DeviceLightEventInit</span> : <span class="idlSuperclass"><a>EventInit</a></span> {
+<span class="idlMember"> <span class="idlMemberType"><a>double</a></span> <span class="idlMemberName"><a href="#widl-DeviceLightEventInit-value">value</a></span>;</span>
+};</span><br><br>[<span class="extAttr">Constructor (DOMString type, optional DeviceLightEventInit eventInitDict)</span>]
+interface <span class="idlInterfaceID">DeviceLightEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>double</a></span> <span class="idlAttrName"><a href="#widl-DeviceLightEvent-value">value</a></span>;</span>
+};</span></pre>
+
<p>
- The <code>value</code> attribute of the <a>DeviceLightEvent</a>
- interface MUST return the value it was initialized to. When the
- object is created, this attribute MUST be initialized to positive
- Infinity. It represents the <a>current light level</a>.
+ The <code>value</code> attribute of the <a href="#idl-def-DeviceLightEvent" class="idlType"><code>DeviceLightEvent</code></a>
+ interface <em class="rfc2119" title="must">must</em> return the value it was initialized to. When the
+ object is created, this attribute <em class="rfc2119" title="must">must</em> be initialized to positive
+ Infinity. It represents the <a href="#dfn-current-light-level" class="internalDFN">current light level</a>.
</p>
- <div class="note">
+ <div class="note"><div class="note-title"><span>Note</span></div><div class="">
The precise lux value reported by different devices in the same light
can be different, due to differences in detection method, sensor
construction etc.
- </div>
+ </div></div>
<p>
- When a <dfn>user agent</dfn> is required to <dfn>fire a device
- light event</dfn>, the <dfn>user agent</dfn> MUST run the
+ When a <dfn id="dfn-user-agent-1">user agent</dfn> is required to <dfn id="dfn-fire-a-device-light-event">fire a device
+ light event</dfn>, the <dfn id="dfn-user-agent-2">user agent</dfn> <em class="rfc2119" title="must">must</em> run the
following steps:
</p>
<ol class="rule">
<li>
- <a>Create an event</a> that uses the <a>DeviceLightEvent</a>
+ <a>Create an event</a> that uses the <a href="#idl-def-DeviceLightEvent" class="idlType"><code>DeviceLightEvent</code></a>
interface, with the name <code>devicelight</code>, which
bubbles, is not cancelable, and has no default action, that also
meets the following conditions:
<ol>
<li>
- If the implementation is unable to report the <a>current
+ If the implementation is unable to report the <a href="#dfn-current-light-level" class="internalDFN">current
light level</a>, initialize the <code>value</code>
attribute to positive Infinity, otherwise initialize the
- attribute to the <a>current light level</a>.
+ attribute to the <a href="#dfn-current-light-level" class="internalDFN">current light level</a>.
</li>
</ol>
</li>
</ol>
<p>
- When the <a>current light level</a> changes, the <dfn>user agent</dfn>
- MUST queue a task to <a>fire a device light event</a> at the
- <a>Window</a> object.
+ When the <a href="#dfn-current-light-level" class="internalDFN">current light level</a> changes, the <dfn id="dfn-user-agent-3">user agent</dfn>
+ <em class="rfc2119" title="must">must</em> queue a task to <a href="#dfn-fire-a-device-light-event" class="internalDFN">fire a device light event</a> at the
+ <a href="#idl-def-Window" class="idlType"><code>Window</code></a> object.
</p>
- <div class="note">
+ <div class="note"><div class="note-title"><span>Note</span></div><div class="">
The definition of granularity i.e. how often the event is fired is
left to the implementation. Implementations can fire the event if
they have reason to believe that the page does not have sufficiently
fresh data.
- </div>
- <section>
- <h2>Event handlers</h2>
+ </div></div>
+ <section id="event-handlers">
+ <h4><span class="secno">5.1.1 </span>Event handlers</h4>
<p>
- The following are the <a>event handlers</a> (and their corresponding
- <a>event handler event types</a>) that MUST be supported as
- attributes by the <a>Window</a> object:
+ The following are the <a href="#dfn-event-handlers" class="internalDFN">event handlers</a> (and their corresponding
+ <a href="#dfn-event-handler-event-types" class="internalDFN">event handler event types</a>) that <em class="rfc2119" title="must">must</em> be supported as
+ attributes by the <a href="#idl-def-Window" class="idlType"><code>Window</code></a> object:
</p>
<table class="simple">
<thead>
@@ -215,87 +661,72 @@
</section>
</section>
- <section>
- <h2>Light Level</h2>
+ <section id="light-level">
+ <!--OddPage--><h2><span class="secno">6. </span>Light Level</h2>
<p>
- The <a>LightLevelEvent</a> interface provides information about the
+ The <a href="#idl-def-LightLevelEvent" class="idlType"><code>LightLevelEvent</code></a> interface provides information about the
ambient light levels, as detected by the device's light detector, in
terms of three general range: "dim", "normal", or "bright".
</p>
<p>
- The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+ The HTML5 specification [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>] defines a <a href="#idl-def-Window" class="idlType"><code>Window</code></a> interface,
which this specification extends:
</p>
- <dl title="partial interface Window" class="idl">
- <dt>attribute EventHandler onlightlevel</dt>
- <dd>
- </dd>
- </dl>
+ <pre class="idl"><span class="idlInterface" id="idl-def-Window-1">partial interface <span class="idlInterfaceID">Window</span> {
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-Window-onlightlevel">onlightlevel</a></span>;</span>
+};</span></pre>
<p>
The <code>onlightlevel</code> event handler and its corresponding
- event handler event type <code>lightlevel</code> MUST be supported
- as an IDL attribute by all objects implementing the <a>Window</a>
+ event handler event type <code>lightlevel</code> <em class="rfc2119" title="must">must</em> be supported
+ as an IDL attribute by all objects implementing the <a href="#idl-def-Window" class="idlType"><code>Window</code></a>
interface.
</p>
- <section>
- <h2><a>LightLevelEvent</a> Interface</h2>
- <dl title="[Constructor (DOMString type, optional LightLevelEventInit eventInitDict)]
- interface LightLevelEvent : Event"
- class="idl" data-merge='LightLevelEventInit LightLevelState'>
- <dt>readonly attribute LightLevelState value</dt>
- <dd></dd>
- </dl>
- <dl id="enum-basic" class="idl" title="enum LightLevelState">
- <dt>‍</dt><!-- (empty string) -->
- <dd>
- </dd>
- <dt>dim</dt>
- <dd>
- </dd>
- <dt>normal</dt>
- <dd>
- </dd>
- <dt>bright</dt>
- <dd>
- </dd>
- </dl>
- <dl title="dictionary LightLevelEventInit : EventInit" class='idl'>
- <dt>
- LightLevelState value
- </dt>
- <dd></dd>
- </dl>
+ <section id="lightlevelevent-interface">
+ <h3><span class="secno">6.1 </span><a href="#idl-def-LightLevelEvent" class="idlType"><code>LightLevelEvent</code></a> Interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-LightLevelEvent"><span class="idlEnum" id="idl-def-LightLevelState">enum <span class="idlEnumID">LightLevelState</span> {
+ "<span class="idlEnumItem"></span>",
+ "<span class="idlEnumItem">dim</span>",
+ "<span class="idlEnumItem">normal</span>",
+ "<span class="idlEnumItem">bright</span>"
+};</span><br><br><span class="idlDictionary" id="idl-def-LightLevelEventInit">dictionary <span class="idlDictionaryID">LightLevelEventInit</span> : <span class="idlSuperclass"><a>EventInit</a></span> {
+<span class="idlMember"> <span class="idlMemberType"><a href="#idl-def-LightLevelState" class="idlType"><code>LightLevelState</code></a></span> <span class="idlMemberName"><a href="#widl-LightLevelEventInit-value">value</a></span>;</span>
+};</span><br><br>[<span class="extAttr">Constructor (DOMString type, optional LightLevelEventInit eventInitDict)</span>]
+interface <span class="idlInterfaceID">LightLevelEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a href="#idl-def-LightLevelState" class="idlType"><code>LightLevelState</code></a></span> <span class="idlAttrName"><a href="#widl-LightLevelEvent-value">value</a></span>;</span>
+};</span></pre>
+
+
<p>
- The <code>value</code> attribute of the <a>LightLevelEvent</a>
- interface MUST return the value it was initialized to. When the
- object is created, this attribute MUST be initialized to positive
- Infinity. It represents the <a>current light level state</a>.
+ The <code>value</code> attribute of the <a href="#idl-def-LightLevelEvent" class="idlType"><code>LightLevelEvent</code></a>
+ interface <em class="rfc2119" title="must">must</em> return the value it was initialized to. When the
+ object is created, this attribute <em class="rfc2119" title="must">must</em> be initialized to positive
+ Infinity. It represents the <a href="#dfn-current-light-level-state" class="internalDFN">current light level state</a>.
</p>
<p>
- When a <dfn>user agent</dfn> is required to <dfn>fire a light
- level event</dfn>, the <dfn>user agent</dfn> MUST run the
+ When a <dfn id="dfn-user-agent-4">user agent</dfn> is required to <dfn id="dfn-fire-a-light-level-event">fire a light
+ level event</dfn>, the <dfn id="dfn-user-agent-5">user agent</dfn> <em class="rfc2119" title="must">must</em> run the
following steps:
</p>
<ol class="rule">
<li>
- <a>Create an event</a> that uses the <a>LightLevelEvent</a>
+ <a>Create an event</a> that uses the <a href="#idl-def-LightLevelEvent" class="idlType"><code>LightLevelEvent</code></a>
interface, with the name <code>lightlevel</code>, which
bubbles, is not cancelable, and has no default action, that also
meets the following conditions:
<ol>
<li>
- If the implementation is unable to report the <a>current
+ If the implementation is unable to report the <a href="#dfn-current-light-level-state" class="internalDFN">current
light level state</a>, initialize the <code>value</code>
attribute to empty string, otherwise initialize the
- attribute to the <a>current light level state</a>, which MUST
+ attribute to the <a href="#dfn-current-light-level-state" class="internalDFN">current light level state</a>, which <em class="rfc2119" title="must">must</em>
be one of the following values:
<ul>
<li><code>dim</code></li>
<li><code>normal</code></li>
<li><code>bright</code></li>
</ul>
- <div class="note">
- The lux ranges that map to the <a>current light level
+ <div class="note"><div class="note-title"><span>Note</span></div><div class="">
+ The lux ranges that map to the <a href="#dfn-current-light-level-state" class="internalDFN">current light level
state</a>s are left to the implementation, as devices with
different sensitivities could map them slightly differently.
However, it is recommended that "<code>dim</code>" correspond
@@ -308,29 +739,29 @@
"<code>bright</code>" correspond to light above 10000 lux
(direct sunlight, or similarly bright conditions that make it
hard to see things that aren't high-contrast).
- </div>
+ </div></div>
</li>
</ol>
</li>
</ol>
<p>
- When the <a>current light level state</a> changes, the <dfn>user agent</dfn>
- MUST queue a task to <a>fire a user proximity event</a> at the
- <a>Window</a> object.
+ When the <a href="#dfn-current-light-level-state" class="internalDFN">current light level state</a> changes, the <dfn id="dfn-user-agent-6">user agent</dfn>
+ <em class="rfc2119" title="must">must</em> queue a task to <a>fire a user proximity event</a> at the
+ <a href="#idl-def-Window" class="idlType"><code>Window</code></a> object.
</p>
- <div class="note">
+ <div class="note"><div class="note-title"><span>Note</span></div><div class="">
The definition of granularity i.e. how often the event is fired is
left to the implementation. Implementations can fire the event if
they have reason to believe that the page does not have sufficiently
fresh data.
- </div>
- <section>
- <h2>Event handlers</h2>
+ </div></div>
+ <section id="event-handlers-1">
+ <h4><span class="secno">6.1.1 </span>Event handlers</h4>
<p>
- The following are the <a>event handlers</a> (and their corresponding
- <a>event handler event types</a>) that MUST be supported as
- attributes by the <a>Window</a> object:
+ The following are the <a href="#dfn-event-handlers" class="internalDFN">event handlers</a> (and their corresponding
+ <a href="#dfn-event-handler-event-types" class="internalDFN">event handler event types</a>) that <em class="rfc2119" title="must">must</em> be supported as
+ attributes by the <a href="#idl-def-Window" class="idlType"><code>Window</code></a> object:
</p>
<table class="simple">
<thead>
@@ -350,12 +781,16 @@
</section>
</section>
- <section class="appendix">
- <h2>Acknowledgements</h2>
+ <section class="appendix" id="acknowledgements">
+ <!--OddPage--><h2><span class="secno">A. </span>Acknowledgements</h2>
<p>
Doug Turner for the <a href="http://dougturner.wordpress.com/2012/03/26/device-light-sensor/">initial prototype</a> and
Marcos Caceres for the test suite.
</p>
</section>
- </body>
-</html>
+
+
+<section id="references" class="appendix"><!--OddPage--><h2><span class="secno">B. </span>References</h2><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; Aryeh Gregor; Ms2ger. <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html/"><cite>DOM4.</cite></a> 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>Robin Berjon et al. <a href="http://www.w3.org/TR/html5/"><cite>HTML5.</cite></a> 17 December 2012. W3C Candidate Recommendation. URL: <a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</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></section></section></body></html>
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/light/Overview.src.html Wed Jan 30 10:38:51 2013 +0200
@@ -0,0 +1,361 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Ambient Light Events</title>
+ <meta charset="utf-8"/>
+ <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
+ <script class="remove">
+ var respecConfig = {
+ specStatus: "ED",
+ shortName: "ambient-light",
+ //publishDate: "2012-12-13",
+ previousPublishDate: "2012-12-13",
+ previousMaturity: "LC",
+ edDraftURI: "http://dvcs.w3.org/hg/dap/raw-file/tip/light/Overview.html",
+ lcEnd: "2013-01-26",
+ editors: [
+ { name: "Doug Turner", company: "Mozilla Corporation", companyURL: "http://mozilla.com/" },
+ { name: "Anssi Kostiainen", company: "Nokia", companyURL: "http://nokia.com/" }
+ ],
+ inlineCSS: true,
+ noIDLIn: true,
+ noLegacyStyle: true,
+ 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 a means to receive events that correspond to
+ a light sensor detecting the presence of a light.
+ </section>
+
+ <section id="sotd">
+ <p>
+ The functionality described in this specification was initially
+ specified as part of the
+ <a href="http://dvcs.w3.org/hg/dap/raw-file/tip/sensor-api/Overview.html">
+ Sensor API</a> but has been extracted in order to be more
+ straightforward to implement, and in order to produce a specification
+ that could be implemented on its own merits without interference with
+ other features.
+ </p>
+ <p>
+ Changes in this document since the previously published First Public Working Draft
+ include the addition of the Light Level section with the LightLevelEvent interface,
+ editorial cleanup, and an update to the references.
+ </p>
+ </section>
+
+ <section class="informative">
+ <h2>Introduction</h2>
+ <p>
+ This specification defines events that provide information about the
+ ambient light level, as measured by a device's light sensor. A
+ <a>LightLevelEvent</a> describes the light level as one of three simple
+ categories - "dim", "normal", and "bright" - while a
+ <a>DeviceLightEvent</a> provides a more granular answer by describing
+ the light level in terms of lux units.
+ </p>
+ </section>
+
+ <section id="conformance">
+ <p>
+ This specification defines conformance criteria that apply to a single
+ product: the <dfn>user agent</dfn> that implements the
+ interfaces that it contains.
+ </p>
+ </section>
+
+ <section>
+ <h2>Terminology</h2>
+ <p>
+ The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
+ EventHandler</a></code> interface represents a <a href="http://www.w3.org/TR/WebIDL/#idl-callback-functions">callback function</a> used for <a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">event
+ handlers</a> as defined in [[!HTML5]]. </p>
+ <p>
+ The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
+ queue a task</a></dfn> and
+ <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
+ fires a simple event</a></dfn> are defined in [[!HTML5]].
+ </p>
+ <p>
+ The terms <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
+ event handlers</a></dfn> and
+ <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
+ event handler event types</a></dfn> are defined in [[!HTML5]].
+ </p>
+ <p>The concepts <dfn>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#constructing-events">
+ create an event</a></dfn> and <dfn>
+ <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#firing-events">
+ fire an event</a></dfn> are defined in [[!DOM4]].
+ <p>
+ The <dfn>current light level</dfn> is a value that represents the ambient
+ light levels around the hosting device in lux units.
+ </p>
+ <p>
+ The <dfn>current light level state</dfn> represents the ambient light level
+ around the hosting device as a human-readable string.
+ </p>
+ </section>
+
+ <section>
+ <h2>Security and privacy considerations</h2>
+ <p>
+ </p>
+ </section>
+
+ <section>
+ <h2>Device Light</h2>
+ <p>
+ The <a>DeviceLightEvent</a> interface provides information about the
+ ambient light levels, as detected by the device's light detector, in
+ terms of lux units.
+ </p>
+ <p>
+ The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+ which this specification extends:
+ </p>
+ <dl title="partial interface Window" class="idl">
+ <dt>attribute EventHandler ondevicelight</dt>
+ <dd>
+ </dd>
+ </dl>
+ <p>
+ The <code>ondevicelight</code> event handler and its corresponding
+ event handler event type <code>devicelight</code> MUST be supported
+ as an IDL attribute by all objects implementing the <a>Window</a>
+ interface.
+ </p>
+ <section>
+ <h2><a>DeviceLightEvent</a> Interface</h2>
+ <dl title="[Constructor (DOMString type, optional DeviceLightEventInit eventInitDict)]
+ interface DeviceLightEvent : Event"
+ class="idl" data-merge='DeviceLightEventInit'>
+ <dt>readonly attribute double value</dt>
+ <dd>
+ The <a>ambient light level in lux</a>.
+ </dd>
+ </dl>
+ <dl title="dictionary DeviceLightEventInit : EventInit" class='idl'>
+ <dt>
+ double value
+ </dt>
+ <dd></dd>
+ </dl>
+ <p>
+ The <code>value</code> attribute of the <a>DeviceLightEvent</a>
+ interface MUST return the value it was initialized to. When the
+ object is created, this attribute MUST be initialized to positive
+ Infinity. It represents the <a>current light level</a>.
+ </p>
+ <div class="note">
+ The precise lux value reported by different devices in the same light
+ can be different, due to differences in detection method, sensor
+ construction etc.
+ </div>
+ <p>
+ When a <dfn>user agent</dfn> is required to <dfn>fire a device
+ light event</dfn>, the <dfn>user agent</dfn> MUST run the
+ following steps:
+ </p>
+ <ol class="rule">
+ <li>
+ <a>Create an event</a> that uses the <a>DeviceLightEvent</a>
+ interface, with the name <code>devicelight</code>, which
+ bubbles, is not cancelable, and has no default action, that also
+ meets the following conditions:
+ <ol>
+ <li>
+ If the implementation is unable to report the <a>current
+ light level</a>, initialize the <code>value</code>
+ attribute to positive Infinity, otherwise initialize the
+ attribute to the <a>current light level</a>.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ When the <a>current light level</a> changes, the <dfn>user agent</dfn>
+ MUST queue a task to <a>fire a device light event</a> at the
+ <a>Window</a> object.
+ </p>
+ <div class="note">
+ The definition of granularity i.e. how often the event is fired is
+ left to the implementation. Implementations can fire the event if
+ they have reason to believe that the page does not have sufficiently
+ fresh data.
+ </div>
+ <section>
+ <h2>Event handlers</h2>
+ <p>
+ The following are the <a>event handlers</a> (and their corresponding
+ <a>event handler event types</a>) that MUST be supported as
+ attributes by the <a>Window</a> object:
+ </p>
+ <table class="simple">
+ <thead>
+ <tr>
+ <th>event handler</th>
+ <th>event handler event type</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><strong><code>ondevicelight</code></strong></td>
+ <td><code>devicelight</code></td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <h2>Light Level</h2>
+ <p>
+ The <a>LightLevelEvent</a> interface provides information about the
+ ambient light levels, as detected by the device's light detector, in
+ terms of three general range: "dim", "normal", or "bright".
+ </p>
+ <p>
+ The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+ which this specification extends:
+ </p>
+ <dl title="partial interface Window" class="idl">
+ <dt>attribute EventHandler onlightlevel</dt>
+ <dd>
+ </dd>
+ </dl>
+ <p>
+ The <code>onlightlevel</code> event handler and its corresponding
+ event handler event type <code>lightlevel</code> MUST be supported
+ as an IDL attribute by all objects implementing the <a>Window</a>
+ interface.
+ </p>
+ <section>
+ <h2><a>LightLevelEvent</a> Interface</h2>
+ <dl title="[Constructor (DOMString type, optional LightLevelEventInit eventInitDict)]
+ interface LightLevelEvent : Event"
+ class="idl" data-merge='LightLevelEventInit LightLevelState'>
+ <dt>readonly attribute LightLevelState value</dt>
+ <dd></dd>
+ </dl>
+ <dl id="enum-basic" class="idl" title="enum LightLevelState">
+ <dt>‍</dt><!-- (empty string) -->
+ <dd>
+ </dd>
+ <dt>dim</dt>
+ <dd>
+ </dd>
+ <dt>normal</dt>
+ <dd>
+ </dd>
+ <dt>bright</dt>
+ <dd>
+ </dd>
+ </dl>
+ <dl title="dictionary LightLevelEventInit : EventInit" class='idl'>
+ <dt>
+ LightLevelState value
+ </dt>
+ <dd></dd>
+ </dl>
+ <p>
+ The <code>value</code> attribute of the <a>LightLevelEvent</a>
+ interface MUST return the value it was initialized to. When the
+ object is created, this attribute MUST be initialized to positive
+ Infinity. It represents the <a>current light level state</a>.
+ </p>
+ <p>
+ When a <dfn>user agent</dfn> is required to <dfn>fire a light
+ level event</dfn>, the <dfn>user agent</dfn> MUST run the
+ following steps:
+ </p>
+ <ol class="rule">
+ <li>
+ <a>Create an event</a> that uses the <a>LightLevelEvent</a>
+ interface, with the name <code>lightlevel</code>, which
+ bubbles, is not cancelable, and has no default action, that also
+ meets the following conditions:
+ <ol>
+ <li>
+ If the implementation is unable to report the <a>current
+ light level state</a>, initialize the <code>value</code>
+ attribute to empty string, otherwise initialize the
+ attribute to the <a>current light level state</a>, which MUST
+ be one of the following values:
+ <ul>
+ <li><code>dim</code></li>
+ <li><code>normal</code></li>
+ <li><code>bright</code></li>
+ </ul>
+ <div class="note">
+ The lux ranges that map to the <a>current light level
+ state</a>s are left to the implementation, as devices with
+ different sensitivities could map them slightly differently.
+ However, it is recommended that "<code>dim</code>" correspond
+ to ambient light below 50 lux (dark enough that the light
+ produced by a white background is eye-straining or
+ distracting), "<code>normal</code>" correspond to light
+ between 50 lux and 10000 lux (office building hallway, very
+ dark overcast day, office lighting, sunrise or sunset on a
+ clear day, overcast day, or similar), and
+ "<code>bright</code>" correspond to light above 10000 lux
+ (direct sunlight, or similarly bright conditions that make it
+ hard to see things that aren't high-contrast).
+ </div>
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ When the <a>current light level state</a> changes, the <dfn>user agent</dfn>
+ MUST queue a task to <a>fire a user proximity event</a> at the
+ <a>Window</a> object.
+ </p>
+
+ <div class="note">
+ The definition of granularity i.e. how often the event is fired is
+ left to the implementation. Implementations can fire the event if
+ they have reason to believe that the page does not have sufficiently
+ fresh data.
+ </div>
+ <section>
+ <h2>Event handlers</h2>
+ <p>
+ The following are the <a>event handlers</a> (and their corresponding
+ <a>event handler event types</a>) that MUST be supported as
+ attributes by the <a>Window</a> object:
+ </p>
+ <table class="simple">
+ <thead>
+ <tr>
+ <th>event handler</th>
+ <th>event handler event type</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><strong><code>onlightlevel</code></strong></td>
+ <td><code>lightlevel</code></td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
+ </section>
+ </section>
+
+ <section class="appendix">
+ <h2>Acknowledgements</h2>
+ <p>
+ Doug Turner for the <a href="http://dougturner.wordpress.com/2012/03/26/device-light-sensor/">initial prototype</a> and
+ Marcos Caceres for the test suite.
+ </p>
+ </section>
+ </body>
+</html>
--- a/proximity/Overview.html Mon Jan 28 08:56:58 2013 -0800
+++ b/proximity/Overview.html Wed Jan 30 10:38:51 2013 +0200
@@ -1,42 +1,440 @@
<!DOCTYPE html>
-<html>
- <head>
+<html lang="en" dir="ltr"><head>
<title>Proximity Events</title>
- <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
- <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
- <script class="remove">
- var respecConfig = {
- specStatus: "ED",
- shortName: "proximity",
- //publishDate: "2012-12-06",
- previousPublishDate: "2012-07-12",
- previousMaturity: "WD",
- edDraftURI: "http://dvcs.w3.org/hg/dap/raw-file/tip/proximity/Overview.html",
- //lcEnd: "yyyy-mm-dd",
- editors: [
- { name: "Anssi Kostiainen", company: "Nokia", companyURL: "http://nokia.com/" },
- { name: "Dzung D Tran", company: "Intel", companyURL: "http://intel.com/" }
- ],
- inlineCSS: true,
- noIDLIn: true,
- noLegacyStyle: true,
- //extraCSS: ["../ReSpec.js/css/respec.css"],
- extraCSS: ["http://dev.w3.org/2009/dap/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",
- testSuiteURI: "http://w3c-test.org/dap/proximity/tests/"
- };
- </script>
- </head>
- <body>
- <section id="abstract">
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+
+
+ <style>/*****************************************************************
+ * ReSpec 3 CSS
+ * Robin Berjon - http://berjon.com/
+ *****************************************************************/
+
+/* --- 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;
+}
+
+cite .bibref {
+ font-style: normal;
+}
+
+code {
+ color: #ff4500;
+}
+
+
+/* --- --- */
+ol.algorithm { counter-reset:numsection; list-style-type: none; }
+ol.algorithm li { margin: 0.5em 0; }
+ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; }
+
+/* --- TOC --- */
+.toc a, .tof a {
+ text-decoration: none;
+}
+
+a .secno, a .figno {
+ color: #000;
+}
+
+ul.tof, ol.tof {
+ list-style: none outside none;
+}
+
+.caption {
+ margin-top: 0.5em;
+ font-style: italic;
+}
+
+/* --- 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;
+}
+</style><style>/* --- ISSUES/NOTES --- */
+div.issue-title, div.note-title {
+ padding-right: 1em;
+ min-width: 7.5em;
+ color: #b9ab2d;
+}
+div.issue-title { color: #e05252; }
+div.note-title { color: #52e052; }
+div.issue-title span, div.note-title span {
+ text-transform: uppercase;
+}
+div.note, div.issue {
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+.note > p:first-child, .issue > p:first-child { margin-top: 0 }
+.issue, .note {
+ padding: .5em;
+ border-left-width: .5em;
+ border-left-style: solid;
+}
+div.issue, div.note {
+ padding: 0.5em;
+ margin: 1em 0;
+ position: relative;
+ clear: both;
+}
+span.note, span.issue { padding: .1em .5em .15em; }
+
+.issue {
+ border-color: #e05252;
+ background: #fbe9e9;
+}
+.note {
+ border-color: #52e052;
+ background: #e9fbe9;
+}
+
+
+</style><style>/* --- 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, .idlCallbackID, .idlEnumID {
+ 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, .idlCallbackType {
+ color: #005a9c;
+}
+.idlMethName {
+ color: #ff4500;
+}
+.idlMethName a {
+ color: #ff4500;
+ border-bottom: 1px dotted #ff4500;
+ text-decoration: none;
+}
+
+/*.idlParam*/
+.idlParamType {
+ color: #005a9c;
+}
+.idlParamName, .idlDefaultValue {
+ 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%;
+}
+</style><link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-ED"></head>
+ <body><div class="head">
+ <p>
+
+ <a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a>
+
+ </p>
+ <h1 class="title" id="title">Proximity Events</h1>
+
+ <h2 id="w3c-editor-s-draft-30-january-2013"><abbr title="World Wide Web Consortium">W3C</abbr> Editor's Draft 30 January 2013</h2>
+ <dl>
+
+ <dt>This version:</dt>
+ <dd><a href="http://dvcs.w3.org/hg/dap/raw-file/tip/proximity/Overview.html">http://dvcs.w3.org/hg/dap/raw-file/tip/proximity/Overview.html</a></dd>
+ <dt>Latest published version:</dt>
+ <dd><a href="http://www.w3.org/TR/proximity/">http://www.w3.org/TR/proximity/</a></dd>
+
+
+ <dt>Latest editor's draft:</dt>
+ <dd><a href="http://dvcs.w3.org/hg/dap/raw-file/tip/proximity/Overview.html">http://dvcs.w3.org/hg/dap/raw-file/tip/proximity/Overview.html</a></dd>
+
+
+ <dt>Test suite:</dt>
+ <dd><a href="http://w3c-test.org/dap/proximity/tests/">http://w3c-test.org/dap/proximity/tests/</a></dd>
+
+
+
+
+
+
+
+ <dt>Editors:</dt>
+ <dd><span>Anssi Kostiainen</span>, <a href="http://nokia.com/">Nokia</a></dd>
+<dd><span>Dzung D Tran</span>, <a href="http://intel.com/">Intel</a></dd>
+
+
+ </dl>
+
+
+
+
+
+ <p class="copyright">
+ <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> ©
+ 2013
+
+ <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup>
+ (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>,
+ <a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>,
+ <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved.
+ <abbr title="World Wide Web Consortium">W3C</abbr> <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>
+ <section id="abstract" class="introductory"><h2>Abstract</h2><p>
This specification defines a means to receive events that correspond to
a proximity sensor detecting the presence of a physical object.
- </section>
+ </p></section><section id="sotd" class="introductory"><h2>Status of This Document</h2>
+
- <section id="sotd">
+
+ <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 <abbr title="World Wide Web Consortium">W3C</abbr> publications and the latest revision
+ of this technical report can be found in the <a href="http://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports
+ index</a> at http://www.w3.org/TR/.</em>
+ </p>
+
<p>
The functionality described in this specification was initially
specified as part of the
@@ -46,17 +444,64 @@
that could be implemented on its own merits without interference with
other features.
</p>
- </section>
- <section class="informative">
- <h2>Introduction</h2>
+ <p>
+ This document was published by the <a href="http://www.w3.org/2009/dap/">Device APIs Working Group</a> as an Editor's Draft.
+
+
+ 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 comments are welcome.
+
+
+ </p><p>
+ Publication as an Editor's Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr> 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 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
+
+
+
+
+ <abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a href="http://www.w3.org/2004/01/pp-impl/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 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
+
+
+ </p>
+
+
+
+
+</section><section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a href="#conformance" class="tocxref"><span class="secno">2. </span>Conformance</a></li><li class="tocline"><a href="#terminology" class="tocxref"><span class="secno">3. </span>Terminology</a></li><li class="tocline"><a href="#security-and-privacy-considerations" class="tocxref"><span class="secno">4. </span>Security and privacy considerations</a></li><li class="tocline"><a href="#device-proximity" class="tocxref"><span class="secno">5. </span>Device proximity</a><ul class="toc"><li class="tocline"><a href="#deviceproximityevent-interface" class="tocxref"><span class="secno">5.1 </span><span class="formerLink"><code>DeviceProximityEvent</code></span> Interface</a><ul class="toc"><li class="tocline"><a href="#event-handlers" class="tocxref"><span class="secno">5.1.1 </span>Event handlers</a></li></ul></li></ul></li><li class="tocline"><a href="#user-proximity" class="tocxref"><span class="secno">6. </span>User proximity</a><ul class="toc"><li class="tocline"><a href="#userproximityevent-interface" class="tocxref"><span class="secno">6.1 </span><span class="formerLink"><code>UserProximityEvent</code></span> Interface</a><ul class="toc"><li class="tocline"><a href="#event-handlers-1" class="tocxref"><span class="secno">6.1.1 </span>Event handlers</a></li></ul></li></ul></li><li class="tocline"><a href="#acknowledgements" class="tocxref"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">B.1 </span>Normative references</a></li></ul></li></ul></section>
+
+
+
+ <section class="informative" id="introduction">
+ <!--OddPage--><h2><span class="secno">1. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
<p>
- The <a>DeviceProximityEvent</a> interface provides web developers
+ The <a href="#idl-def-DeviceProximityEvent" class="idlType"><code>DeviceProximityEvent</code></a> interface provides web developers
information about the distance between the hosting device and a
nearby object.
</p>
<p>
- The <a>UserProximityEvent</a> interface provides web developers
+ The <a href="#idl-def-UserProximityEvent" class="idlType"><code>UserProximityEvent</code></a> interface provides web developers
a user-agent- and platform-specific approximation that the hosting
device has sensed a nearby object.
</p>
@@ -83,186 +528,175 @@
</p>
</section>
- <section id="conformance">
+ <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 class="rfc2119" title="must">must</em>, <em class="rfc2119" title="must not">must not</em>, <em class="rfc2119" title="required">required</em>, <em class="rfc2119" title="should">should</em>, <em class="rfc2119" title="should not">should not</em>, <em class="rfc2119" title="recommended">recommended</em>, <em class="rfc2119" title="may">may</em>,
+ and <em class="rfc2119" title="optional">optional</em> in this specification are to be interpreted as described in [<cite><a class="bibref" href="#bib-RFC2119">RFC2119</a></cite>].
+</p>
+
<p>
This specification defines conformance criteria that apply to a single
- product: the <dfn>user agent</dfn> that implements the
+ product: the <dfn id="dfn-user-agent">user agent</dfn> that implements the
interfaces that it contains.
</p>
</section>
- <section>
- <h2>Terminology</h2>
+ <section id="terminology">
+ <!--OddPage--><h2><span class="secno">3. </span>Terminology</h2>
<p>
The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
EventHandler</a></code> interface represents a callback used for event
- handlers as defined in [[!HTML5]].
- </p>
- <p>
- The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
- queue a task</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
- fires a simple event</a></dfn> are defined in [[!HTML5]].
+ handlers as defined in [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>].
</p>
<p>
- The terms <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
+ The concepts <dfn id="dfn-queue-a-task"><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
+ queue a task</a></dfn> and
+ <dfn id="dfn-fires-a-simple-event"><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
+ fires a simple event</a></dfn> are defined in [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>].
+ </p>
+ <p>
+ The terms <dfn id="dfn-event-handlers"><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
event handlers</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
- event handler event types</a></dfn> are defined in [[!HTML5]].
+ <dfn id="dfn-event-handler-event-types"><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
+ event handler event types</a></dfn> are defined in [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>].
</p>
- <p>The concepts <dfn>
+ <p>The concepts <dfn id="dfn-create-an-event">
<a href="http://dom.spec.whatwg.org/#constructing-events">
- create an event</a></dfn> and <dfn>
+ create an event</a></dfn> and <dfn id="dfn-fire-an-event">
<a href="http://dom.spec.whatwg.org/#firing-events">
- fire an event</a></dfn> are defined in [[!DOM4]].
- <p>
- The <dfn>current device proximity</dfn> is a value that represents the
+ fire an event</a></dfn> are defined in [<cite><a class="bibref" href="#bib-DOM4">DOM4</a></cite>].
+ </p><p>
+ The <dfn id="dfn-current-device-proximity">current device proximity</dfn> is a value that represents the
proximity of the hosting device to a physical object (i.e., some value
- between the <a>maximum sensing distance</a> and the <a>minimum sensing
+ between the <a href="#dfn-maximum-sensing-distance" class="internalDFN">maximum sensing distance</a> and the <a href="#dfn-minimum-sensing-distance" class="internalDFN">minimum sensing
distance</a>), in centimeters.
</p>
<p>
- The <dfn>minimum sensing distance</dfn> at which the sensor can detect
+ The <dfn id="dfn-minimum-sensing-distance">minimum sensing distance</dfn> at which the sensor can detect
a physical object, in centimeters.
</p>
<p>
- The <dfn>maximum sensing distance</dfn> at which the sensor can detect
+ The <dfn id="dfn-maximum-sensing-distance">maximum sensing distance</dfn> at which the sensor can detect
a physical object, in centimeters.
</p>
<p>
- The <dfn>current user proximity state</dfn>, a boolean state, is a
+ The <dfn id="dfn-current-user-proximity-state">current user proximity state</dfn>, a boolean state, is a
user-agent- and platform-specific approximation of the closeness of a
physical object with the hosting device.
</p>
</section>
- <section>
- <h2>Security and privacy considerations</h2>
+ <section id="security-and-privacy-considerations">
+ <!--OddPage--><h2><span class="secno">4. </span>Security and privacy considerations</h2>
<p>
</p>
</section>
- <section>
- <h2>Device proximity</h2>
+ <section id="device-proximity">
+ <!--OddPage--><h2><span class="secno">5. </span>Device proximity</h2>
<p>
- The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+ The HTML5 specification [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>] defines a <a href="#idl-def-Window" class="idlType"><code>Window</code></a> interface,
which this specification extends:
</p>
- <dl title="partial interface Window" class="idl">
- <dt>attribute EventHandler ondeviceproximity</dt>
- <dd>
- </dd>
- </dl>
+ <pre class="idl"><span class="idlInterface" id="idl-def-Window">partial interface <span class="idlInterfaceID">Window</span> {
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-Window-ondeviceproximity">ondeviceproximity</a></span>;</span>
+};</span></pre>
<p>
The <code>ondeviceproximity</code> event handler and its corresponding
- event handler event type <code>deviceproximity</code> MUST be supported
- as an IDL attribute by all objects implementing the <a>Window</a>
+ event handler event type <code>deviceproximity</code> <em class="rfc2119" title="must">must</em> be supported
+ as an IDL attribute by all objects implementing the <a href="#idl-def-Window" class="idlType"><code>Window</code></a>
interface.
</p>
- <section>
- <h2><a>DeviceProximityEvent</a> Interface</h2>
- <dl title="[Constructor (DOMString type, optional DeviceProximityEventInit eventInitDict)]
- interface DeviceProximityEvent : Event"
- class="idl" data-merge='DeviceProximityEventInit'>
- <dt>readonly attribute double value</dt>
- <dd>
- The <a>current device proximity</a>.
- </dd>
- <dt>readonly attribute double min</dt>
- <dd>
- The <a> minimum sensing distance</a>.
- </dd>
- <dt>readonly attribute double max</dt>
- <dd>
- The <a>maximum sensing distance<strong></strong></a>.
- </dd>
- </dl>
- <dl title="dictionary DeviceProximityEventInit : EventInit" class='idl'>
- <dt>
- double value
- </dt>
- <dd></dd>
- <dt>
- double min
- </dt>
- <dd></dd>
- <dt>
- double max
- </dt>
- <dd></dd>
- </dl>
+ <section id="deviceproximityevent-interface">
+ <h3><span class="secno">5.1 </span><a href="#idl-def-DeviceProximityEvent" class="idlType"><code>DeviceProximityEvent</code></a> Interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-DeviceProximityEvent"><span class="idlDictionary" id="idl-def-DeviceProximityEventInit">dictionary <span class="idlDictionaryID">DeviceProximityEventInit</span> : <span class="idlSuperclass"><a>EventInit</a></span> {
+<span class="idlMember"> <span class="idlMemberType"><a>double</a></span> <span class="idlMemberName"><a href="#widl-DeviceProximityEventInit-value">value</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>double</a></span> <span class="idlMemberName"><a href="#widl-DeviceProximityEventInit-min">min</a></span>;</span>
+<span class="idlMember"> <span class="idlMemberType"><a>double</a></span> <span class="idlMemberName"><a href="#widl-DeviceProximityEventInit-max">max</a></span>;</span>
+};</span><br><br>[<span class="extAttr">Constructor (DOMString type, optional DeviceProximityEventInit eventInitDict)</span>]
+interface <span class="idlInterfaceID">DeviceProximityEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>double</a></span> <span class="idlAttrName"><a href="#widl-DeviceProximityEvent-value">value</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>double</a></span> <span class="idlAttrName"><a href="#widl-DeviceProximityEvent-min">min</a></span>;</span>
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>double</a></span> <span class="idlAttrName"><a href="#widl-DeviceProximityEvent-max">max</a></span>;</span>
+};</span></pre>
+
<p>
- The <code>value</code> attribute of the <a>DeviceProximityEvent</a>
- interface MUST return the value it was initialized to. When the
- object is created, this attribute MUST be initialized to positive
- Infinity. It represents the <a>current device proximity</a>.
+ The <code>value</code> attribute of the <a href="#idl-def-DeviceProximityEvent" class="idlType"><code>DeviceProximityEvent</code></a>
+ interface <em class="rfc2119" title="must">must</em> return the value it was initialized to. When the
+ object is created, this attribute <em class="rfc2119" title="must">must</em> be initialized to positive
+ Infinity. It represents the <a href="#dfn-current-device-proximity" class="internalDFN">current device proximity</a>.
</p>
<p>
- The <code>min</code> attribute of the <a>DeviceProximityEvent</a>
- interface MUST return the value it was initialized to. When the
- object is created, this attribute MUST be initialized to negative
- Infinity. It represents the <a>minimum sensing distance</a>.
+ The <code>min</code> attribute of the <a href="#idl-def-DeviceProximityEvent" class="idlType"><code>DeviceProximityEvent</code></a>
+ interface <em class="rfc2119" title="must">must</em> return the value it was initialized to. When the
+ object is created, this attribute <em class="rfc2119" title="must">must</em> be initialized to negative
+ Infinity. It represents the <a href="#dfn-minimum-sensing-distance" class="internalDFN">minimum sensing distance</a>.
</p>
<p>
- The <code>max</code> attribute of the <a>DeviceProximityEvent</a>
- interface MUST return the value it was initialized to. When the
- object is created, this attribute MUST be initialized to positive
- Infinity. It represents the <a>maximum sensing distance</a>.
+ The <code>max</code> attribute of the <a href="#idl-def-DeviceProximityEvent" class="idlType"><code>DeviceProximityEvent</code></a>
+ interface <em class="rfc2119" title="must">must</em> return the value it was initialized to. When the
+ object is created, this attribute <em class="rfc2119" title="must">must</em> be initialized to positive
+ Infinity. It represents the <a href="#dfn-maximum-sensing-distance" class="internalDFN">maximum sensing distance</a>.
</p>
<p>
- When a <dfn>user agent</dfn> is required to <dfn>fire a device
- proximity event</dfn>, the <dfn>user agent</dfn> MUST run the
+ When a <dfn id="dfn-user-agent-1">user agent</dfn> is required to <dfn id="dfn-fire-a-device-proximity-event">fire a device
+ proximity event</dfn>, the <dfn id="dfn-user-agent-2">user agent</dfn> <em class="rfc2119" title="must">must</em> run the
following steps:
</p>
<ol class="rule">
<li>
- <a>Create an event</a> that uses the <a>DeviceProximityEvent</a>
+ <a>Create an event</a> that uses the <a href="#idl-def-DeviceProximityEvent" class="idlType"><code>DeviceProximityEvent</code></a>
interface, with the name <code>deviceproximity</code>, which
bubbles, is not cancelable, and has no default action, that also
meets the following conditions:
<ol>
<li>
- If the implementation is unable to report the <a>current
+ If the implementation is unable to report the <a href="#dfn-current-device-proximity" class="internalDFN">current
device proximity</a>, initialize the <code>value</code>
attribute to positive Infinity, otherwise initialize the
- attribute to the <a>current device proximity</a>.
+ attribute to the <a href="#dfn-current-device-proximity" class="internalDFN">current device proximity</a>.
</li>
<li>
- If the implementation is unable to report the <a>minimum
+ If the implementation is unable to report the <a href="#dfn-minimum-sensing-distance" class="internalDFN">minimum
sensing distance</a>, initialize the <code>min</code>
attribute to negative Infinity, otherwise initialize the
- attribute to the <a>minimum sensing distance</a>.
+ attribute to the <a href="#dfn-minimum-sensing-distance" class="internalDFN">minimum sensing distance</a>.
</li>
<li>
- If the implementation is unable to report the <a>maximum
+ If the implementation is unable to report the <a href="#dfn-maximum-sensing-distance" class="internalDFN">maximum
sensing distance</a>, initialize the <code>max</code>
attribute to positive Infinity, otherwise initialize the
- attribute to the <a>maximum sensing distance</a>.
+ attribute to the <a href="#dfn-maximum-sensing-distance" class="internalDFN">maximum sensing distance</a>.
</li>
</ol>
</li>
</ol>
<p>
- When the <a>current device proximity</a> changes, the <dfn>user
- agent</dfn> MUST queue a task to <a>fire a device proximity event</a>
- at the <a>Window</a> object.
+ When the <a href="#dfn-current-device-proximity" class="internalDFN">current device proximity</a> changes, the <dfn id="dfn-user-agent-3">user
+ agent</dfn> <em class="rfc2119" title="must">must</em> queue a task to <a href="#dfn-fire-a-device-proximity-event" class="internalDFN">fire a device proximity event</a>
+ at the <a href="#idl-def-Window" class="idlType"><code>Window</code></a> object.
</p>
- <div class="note">
+ <div class="note"><div class="note-title"><span>Note</span></div><div class="">
The definition of granularity i.e. how often the event is fired is
left to the implementation. Implementations can fire the event if
they have reason to believe that the page does not have sufficiently
fresh data. Different devices can also support different minimum and
maximum sensing distances as well as different resolution, thus
- authors are strongly advised to use the <a>UserProximityEvent</a>
+ authors are strongly advised to use the <a href="#idl-def-UserProximityEvent" class="idlType"><code>UserProximityEvent</code></a>
interface if they are only interested in finding out if the user is
near or far.
- </div>
- <section>
- <h2>Event handlers</h2>
+ </div></div>
+ <section id="event-handlers">
+ <h4><span class="secno">5.1.1 </span>Event handlers</h4>
<p>
- The following are the <a>event handlers</a> (and their corresponding
- <a>event handler event types</a>) that MUST be supported as
- attributes by the <a>Window</a> object:
+ The following are the <a href="#dfn-event-handlers" class="internalDFN">event handlers</a> (and their corresponding
+ <a href="#dfn-event-handler-event-types" class="internalDFN">event handler event types</a>) that <em class="rfc2119" title="must">must</em> be supported as
+ attributes by the <a href="#idl-def-Window" class="idlType"><code>Window</code></a> object:
</p>
<table class="simple">
<thead>
@@ -282,77 +716,68 @@
</section>
</section>
- <section>
- <h2>User proximity</h2>
+ <section id="user-proximity">
+ <!--OddPage--><h2><span class="secno">6. </span>User proximity</h2>
<p>
- The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+ The HTML5 specification [<cite><a class="bibref" href="#bib-HTML5">HTML5</a></cite>] defines a <a href="#idl-def-Window" class="idlType"><code>Window</code></a> interface,
which this specification extends:
</p>
- <dl title="partial interface Window" class="idl">
- <dt>attribute EventHandler onuserproximity</dt>
- <dd>
- </dd>
- </dl>
+ <pre class="idl"><span class="idlInterface" id="idl-def-Window-1">partial interface <span class="idlInterfaceID">Window</span> {
+<span class="idlAttribute"> attribute <span class="idlAttrType"><a>EventHandler</a></span> <span class="idlAttrName"><a href="#widl-Window-onuserproximity">onuserproximity</a></span>;</span>
+};</span></pre>
<p>
The <code>onuserproximity</code> event handler and its corresponding
- event handler event type <code>userproximity</code> MUST be supported
- as an IDL attribute by all objects implementing the <a>Window</a>
+ event handler event type <code>userproximity</code> <em class="rfc2119" title="must">must</em> be supported
+ as an IDL attribute by all objects implementing the <a href="#idl-def-Window" class="idlType"><code>Window</code></a>
interface.
</p>
- <section>
- <h2><a>UserProximityEvent</a> Interface</h2>
- <dl title="[Constructor (DOMString type, optional UserProximityEventInit eventInitDict)]
- interface UserProximityEvent : Event"
- class="idl" data-merge='UserProximityEventInit'>
- <dt>readonly attribute boolean near</dt>
- <dd>
- The <a>current user proximity state</a>.
- </dd>
- </dl>
- <dl title="dictionary UserProximityEventInit : EventInit" class='idl'>
- <dt>
- boolean near
- </dt>
- <dd></dd>
- </dl>
+ <section id="userproximityevent-interface">
+ <h3><span class="secno">6.1 </span><a href="#idl-def-UserProximityEvent" class="idlType"><code>UserProximityEvent</code></a> Interface</h3>
+ <pre class="idl"><span class="idlInterface" id="idl-def-UserProximityEvent"><span class="idlDictionary" id="idl-def-UserProximityEventInit">dictionary <span class="idlDictionaryID">UserProximityEventInit</span> : <span class="idlSuperclass"><a>EventInit</a></span> {
+<span class="idlMember"> <span class="idlMemberType"><a>boolean</a></span> <span class="idlMemberName"><a href="#widl-UserProximityEventInit-near">near</a></span>;</span>
+};</span><br><br>[<span class="extAttr">Constructor (DOMString type, optional UserProximityEventInit eventInitDict)</span>]
+interface <span class="idlInterfaceID">UserProximityEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
+<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-UserProximityEvent-near">near</a></span>;</span>
+};</span></pre>
+
<p>
- The <code>near</code> attribute of the <a>UserProximityEvent</a>
- interface MUST return the value it was initialized to. When the
- object is created, this attribute MUST be initialized to false.
- It represents the <a>current user proximity state</a>.
+ The <code>near</code> attribute of the <a href="#idl-def-UserProximityEvent" class="idlType"><code>UserProximityEvent</code></a>
+ interface <em class="rfc2119" title="must">must</em> return the value it was initialized to. When the
+ object is created, this attribute <em class="rfc2119" title="must">must</em> be initialized to false.
+ It represents the <a href="#dfn-current-user-proximity-state" class="internalDFN">current user proximity state</a>.
</p>
<p>
- When a <dfn>user agent</dfn> is required to <dfn>fire a user
- proximity event</dfn>, the <dfn>user agent</dfn> MUST run the
+ When a <dfn id="dfn-user-agent-4">user agent</dfn> is required to <dfn id="dfn-fire-a-user-proximity-event">fire a user
+ proximity event</dfn>, the <dfn id="dfn-user-agent-5">user agent</dfn> <em class="rfc2119" title="must">must</em> run the
following steps:
</p>
<ol class="rule">
<li>
- <a>Create an event</a> that uses the <a>UserProximityEvent</a>
+ <a>Create an event</a> that uses the <a href="#idl-def-UserProximityEvent" class="idlType"><code>UserProximityEvent</code></a>
interface, with the name <code>userproximity</code>, which bubbles,
is not cancelable, and has no default action, that also meets the
following conditions:
<ol>
<li>
- If the implementation is unable to report the <a>current user
+ If the implementation is unable to report the <a href="#dfn-current-user-proximity-state" class="internalDFN">current user
proximity state</a>, initialize the <code>near</code> attribute
- to false, otherwise initialize the attribute to the <a>current
+ to false, otherwise initialize the attribute to the <a href="#dfn-current-user-proximity-state" class="internalDFN">current
user proximity state</a>.
</li>
</ol>
</li>
</ol>
<p>
- When the <a>current user proximity state</a> changes, the <dfn>user
- agent</dfn> MUST queue a task to <a>fire a user proximity event</a>
- at the <a>Window</a> object.
+ When the <a href="#dfn-current-user-proximity-state" class="internalDFN">current user proximity state</a> changes, the <dfn id="dfn-user-agent-6">user
+ agent</dfn> <em class="rfc2119" title="must">must</em> queue a task to <a href="#dfn-fire-a-user-proximity-event" class="internalDFN">fire a user proximity event</a>
+ at the <a href="#idl-def-Window" class="idlType"><code>Window</code></a> object.
</p>
- <section>
- <h2>Event handlers</h2>
+ <section id="event-handlers-1">
+ <h4><span class="secno">6.1.1 </span>Event handlers</h4>
<p>
- The following are the <a>event handlers</a> (and their corresponding
- <a>event handler event types</a>) that MUST be supported as
- attributes by the <a>Window</a> object:
+ The following are the <a href="#dfn-event-handlers" class="internalDFN">event handlers</a> (and their corresponding
+ <a href="#dfn-event-handler-event-types" class="internalDFN">event handler event types</a>) that <em class="rfc2119" title="must">must</em> be supported as
+ attributes by the <a href="#idl-def-Window" class="idlType"><code>Window</code></a> object:
</p>
<table class="simple">
<thead>
@@ -372,13 +797,17 @@
</section>
</section>
- <section class="appendix">
- <h2>Acknowledgements</h2>
+ <section class="appendix" id="acknowledgements">
+ <!--OddPage--><h2><span class="secno">A. </span>Acknowledgements</h2>
<p>
Doug Turner for the initial prototype. All Device APIs working group
participants who have sent helpful feedback. Marcos Caceres for his
excellent work on the test suite.
</p>
</section>
- </body>
-</html>
+
+
+<section id="references" class="appendix"><!--OddPage--><h2><span class="secno">B. </span>References</h2><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; Aryeh Gregor; Ms2ger. <a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html/"><cite>DOM4.</cite></a> 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>Robin Berjon et al. <a href="http://www.w3.org/TR/html5/"><cite>HTML5.</cite></a> 17 December 2012. W3C Candidate Recommendation. URL: <a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</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></section></section></body></html>
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/proximity/Overview.src.html Wed Jan 30 10:38:51 2013 +0200
@@ -0,0 +1,384 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Proximity Events</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
+ <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
+ <script class="remove">
+ var respecConfig = {
+ specStatus: "ED",
+ shortName: "proximity",
+ //publishDate: "2012-12-06",
+ previousPublishDate: "2012-07-12",
+ previousMaturity: "WD",
+ edDraftURI: "http://dvcs.w3.org/hg/dap/raw-file/tip/proximity/Overview.html",
+ //lcEnd: "yyyy-mm-dd",
+ editors: [
+ { name: "Anssi Kostiainen", company: "Nokia", companyURL: "http://nokia.com/" },
+ { name: "Dzung D Tran", company: "Intel", companyURL: "http://intel.com/" }
+ ],
+ inlineCSS: true,
+ noIDLIn: true,
+ noLegacyStyle: true,
+ //extraCSS: ["../ReSpec.js/css/respec.css"],
+ extraCSS: ["http://dev.w3.org/2009/dap/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",
+ testSuiteURI: "http://w3c-test.org/dap/proximity/tests/"
+ };
+ </script>
+ </head>
+ <body>
+ <section id="abstract">
+ This specification defines a means to receive events that correspond to
+ a proximity sensor detecting the presence of a physical object.
+ </section>
+
+ <section id="sotd">
+ <p>
+ The functionality described in this specification was initially
+ specified as part of the
+ <a href="http://dvcs.w3.org/hg/dap/raw-file/tip/sensor-api/Overview.html">
+ Sensor API</a> but has been extracted in order to be more
+ straightforward to implement, and in order to produce a specification
+ that could be implemented on its own merits without interference with
+ other features.
+ </p>
+ </section>
+
+ <section class="informative">
+ <h2>Introduction</h2>
+ <p>
+ The <a>DeviceProximityEvent</a> interface provides web developers
+ information about the distance between the hosting device and a
+ nearby object.
+ </p>
+ <p>
+ The <a>UserProximityEvent</a> interface provides web developers
+ a user-agent- and platform-specific approximation that the hosting
+ device has sensed a nearby object.
+ </p>
+ <p>
+ This is achieved by interrogating a proximity sensor of a device, which
+ is a sensor that can detect the presence of a physical object without
+ physical contact. Not all devices contain a proximity sensor, and when
+ there is no proximity sensor, this API is still exposed to the
+ scripting environment but it does nothing.
+ </p>
+ <p>
+ Because most proximity sensors detect electromagnetic radiation (e.g.,
+ an infrared light or a magnetic field), certain material properties can
+ interfere with the sensor's ability to sense the presence of a physical
+ object. Things that can interfere with a sensor include, but are not
+ limited to, the material's translucency, reflectiveness, color,
+ temperature, chemical composition, and even the angle at which the
+ object is reflecting the radiation back at the sensor. As such,
+ proximity sensors should not be relied on as a means to measure
+ distance: the only thing that can be deduced from a proximity sensor is
+ that an object is somewhere in the distance between the minimum sensing
+ distance and the maximum sensing distance with some degree of
+ certainty.
+ </p>
+ </section>
+
+ <section id="conformance">
+ <p>
+ This specification defines conformance criteria that apply to a single
+ product: the <dfn>user agent</dfn> that implements the
+ interfaces that it contains.
+ </p>
+ </section>
+
+ <section>
+ <h2>Terminology</h2>
+ <p>
+ The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#eventhandler">
+ EventHandler</a></code> interface represents a callback used for event
+ handlers as defined in [[!HTML5]].
+ </p>
+ <p>
+ The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
+ queue a task</a></dfn> and
+ <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
+ fires a simple event</a></dfn> are defined in [[!HTML5]].
+ </p>
+ <p>
+ The terms <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
+ event handlers</a></dfn> and
+ <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
+ event handler event types</a></dfn> are defined in [[!HTML5]].
+ </p>
+ <p>The concepts <dfn>
+ <a href="http://dom.spec.whatwg.org/#constructing-events">
+ create an event</a></dfn> and <dfn>
+ <a href="http://dom.spec.whatwg.org/#firing-events">
+ fire an event</a></dfn> are defined in [[!DOM4]].
+ <p>
+ The <dfn>current device proximity</dfn> is a value that represents the
+ proximity of the hosting device to a physical object (i.e., some value
+ between the <a>maximum sensing distance</a> and the <a>minimum sensing
+ distance</a>), in centimeters.
+ </p>
+ <p>
+ The <dfn>minimum sensing distance</dfn> at which the sensor can detect
+ a physical object, in centimeters.
+ </p>
+ <p>
+ The <dfn>maximum sensing distance</dfn> at which the sensor can detect
+ a physical object, in centimeters.
+ </p>
+ <p>
+ The <dfn>current user proximity state</dfn>, a boolean state, is a
+ user-agent- and platform-specific approximation of the closeness of a
+ physical object with the hosting device.
+ </p>
+ </section>
+
+ <section>
+ <h2>Security and privacy considerations</h2>
+ <p>
+ </p>
+ </section>
+
+ <section>
+ <h2>Device proximity</h2>
+ <p>
+ The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+ which this specification extends:
+ </p>
+ <dl title="partial interface Window" class="idl">
+ <dt>attribute EventHandler ondeviceproximity</dt>
+ <dd>
+ </dd>
+ </dl>
+ <p>
+ The <code>ondeviceproximity</code> event handler and its corresponding
+ event handler event type <code>deviceproximity</code> MUST be supported
+ as an IDL attribute by all objects implementing the <a>Window</a>
+ interface.
+ </p>
+ <section>
+ <h2><a>DeviceProximityEvent</a> Interface</h2>
+ <dl title="[Constructor (DOMString type, optional DeviceProximityEventInit eventInitDict)]
+ interface DeviceProximityEvent : Event"
+ class="idl" data-merge='DeviceProximityEventInit'>
+ <dt>readonly attribute double value</dt>
+ <dd>
+ The <a>current device proximity</a>.
+ </dd>
+ <dt>readonly attribute double min</dt>
+ <dd>
+ The <a> minimum sensing distance</a>.
+ </dd>
+ <dt>readonly attribute double max</dt>
+ <dd>
+ The <a>maximum sensing distance<strong></strong></a>.
+ </dd>
+ </dl>
+ <dl title="dictionary DeviceProximityEventInit : EventInit" class='idl'>
+ <dt>
+ double value
+ </dt>
+ <dd></dd>
+ <dt>
+ double min
+ </dt>
+ <dd></dd>
+ <dt>
+ double max
+ </dt>
+ <dd></dd>
+ </dl>
+ <p>
+ The <code>value</code> attribute of the <a>DeviceProximityEvent</a>
+ interface MUST return the value it was initialized to. When the
+ object is created, this attribute MUST be initialized to positive
+ Infinity. It represents the <a>current device proximity</a>.
+ </p>
+ <p>
+ The <code>min</code> attribute of the <a>DeviceProximityEvent</a>
+ interface MUST return the value it was initialized to. When the
+ object is created, this attribute MUST be initialized to negative
+ Infinity. It represents the <a>minimum sensing distance</a>.
+ </p>
+ <p>
+ The <code>max</code> attribute of the <a>DeviceProximityEvent</a>
+ interface MUST return the value it was initialized to. When the
+ object is created, this attribute MUST be initialized to positive
+ Infinity. It represents the <a>maximum sensing distance</a>.
+ </p>
+ <p>
+ When a <dfn>user agent</dfn> is required to <dfn>fire a device
+ proximity event</dfn>, the <dfn>user agent</dfn> MUST run the
+ following steps:
+ </p>
+ <ol class="rule">
+ <li>
+ <a>Create an event</a> that uses the <a>DeviceProximityEvent</a>
+ interface, with the name <code>deviceproximity</code>, which
+ bubbles, is not cancelable, and has no default action, that also
+ meets the following conditions:
+ <ol>
+ <li>
+ If the implementation is unable to report the <a>current
+ device proximity</a>, initialize the <code>value</code>
+ attribute to positive Infinity, otherwise initialize the
+ attribute to the <a>current device proximity</a>.
+ </li>
+ <li>
+ If the implementation is unable to report the <a>minimum
+ sensing distance</a>, initialize the <code>min</code>
+ attribute to negative Infinity, otherwise initialize the
+ attribute to the <a>minimum sensing distance</a>.
+ </li>
+ <li>
+ If the implementation is unable to report the <a>maximum
+ sensing distance</a>, initialize the <code>max</code>
+ attribute to positive Infinity, otherwise initialize the
+ attribute to the <a>maximum sensing distance</a>.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ When the <a>current device proximity</a> changes, the <dfn>user
+ agent</dfn> MUST queue a task to <a>fire a device proximity event</a>
+ at the <a>Window</a> object.
+ </p>
+ <div class="note">
+ The definition of granularity i.e. how often the event is fired is
+ left to the implementation. Implementations can fire the event if
+ they have reason to believe that the page does not have sufficiently
+ fresh data. Different devices can also support different minimum and
+ maximum sensing distances as well as different resolution, thus
+ authors are strongly advised to use the <a>UserProximityEvent</a>
+ interface if they are only interested in finding out if the user is
+ near or far.
+ </div>
+ <section>
+ <h2>Event handlers</h2>
+ <p>
+ The following are the <a>event handlers</a> (and their corresponding
+ <a>event handler event types</a>) that MUST be supported as
+ attributes by the <a>Window</a> object:
+ </p>
+ <table class="simple">
+ <thead>
+ <tr>
+ <th>event handler</th>
+ <th>event handler event type</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><strong><code>ondeviceproximity</code></strong></td>
+ <td><code>deviceproximity</code></td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <h2>User proximity</h2>
+ <p>
+ The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
+ which this specification extends:
+ </p>
+ <dl title="partial interface Window" class="idl">
+ <dt>attribute EventHandler onuserproximity</dt>
+ <dd>
+ </dd>
+ </dl>
+ <p>
+ The <code>onuserproximity</code> event handler and its corresponding
+ event handler event type <code>userproximity</code> MUST be supported
+ as an IDL attribute by all objects implementing the <a>Window</a>
+ interface.
+ </p>
+ <section>
+ <h2><a>UserProximityEvent</a> Interface</h2>
+ <dl title="[Constructor (DOMString type, optional UserProximityEventInit eventInitDict)]
+ interface UserProximityEvent : Event"
+ class="idl" data-merge='UserProximityEventInit'>
+ <dt>readonly attribute boolean near</dt>
+ <dd>
+ The <a>current user proximity state</a>.
+ </dd>
+ </dl>
+ <dl title="dictionary UserProximityEventInit : EventInit" class='idl'>
+ <dt>
+ boolean near
+ </dt>
+ <dd></dd>
+ </dl>
+ <p>
+ The <code>near</code> attribute of the <a>UserProximityEvent</a>
+ interface MUST return the value it was initialized to. When the
+ object is created, this attribute MUST be initialized to false.
+ It represents the <a>current user proximity state</a>.
+ </p>
+ <p>
+ When a <dfn>user agent</dfn> is required to <dfn>fire a user
+ proximity event</dfn>, the <dfn>user agent</dfn> MUST run the
+ following steps:
+ </p>
+ <ol class="rule">
+ <li>
+ <a>Create an event</a> that uses the <a>UserProximityEvent</a>
+ interface, with the name <code>userproximity</code>, which bubbles,
+ is not cancelable, and has no default action, that also meets the
+ following conditions:
+ <ol>
+ <li>
+ If the implementation is unable to report the <a>current user
+ proximity state</a>, initialize the <code>near</code> attribute
+ to false, otherwise initialize the attribute to the <a>current
+ user proximity state</a>.
+ </li>
+ </ol>
+ </li>
+ </ol>
+ <p>
+ When the <a>current user proximity state</a> changes, the <dfn>user
+ agent</dfn> MUST queue a task to <a>fire a user proximity event</a>
+ at the <a>Window</a> object.
+ </p>
+ <section>
+ <h2>Event handlers</h2>
+ <p>
+ The following are the <a>event handlers</a> (and their corresponding
+ <a>event handler event types</a>) that MUST be supported as
+ attributes by the <a>Window</a> object:
+ </p>
+ <table class="simple">
+ <thead>
+ <tr>
+ <th>event handler</th>
+ <th>event handler event type</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><strong><code>onuserproximity</code></strong></td>
+ <td><code>userproximity</code></td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
+ </section>
+ </section>
+
+ <section class="appendix">
+ <h2>Acknowledgements</h2>
+ <p>
+ Doug Turner for the initial prototype. All Device APIs working group
+ participants who have sent helpful feedback. Marcos Caceres for his
+ excellent work on the test suite.
+ </p>
+ </section>
+ </body>
+</html>