W3C

Ambient Light Events

W3C Working Draft 13 December 2012

This version:
http://www.w3.org/TR/2012/WD-ambient-light-20121213/
Latest published version:
http://www.w3.org/TR/ambient-light/
Latest editor's draft:
http://dvcs.w3.org/hg/dap/raw-file/tip/light/Overview.html
Previous version:
http://www.w3.org/TR/2012/WD-ambient-light-20120802/
Editor:
Doug Turner, Mozilla Corporation

Abstract

This specification defines a means to receive events that correspond to a light sensor detecting the presence of a light.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

The functionality described in this specification was initially specified as part of the Sensor API 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.

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.

This document was published by the Device APIs Working Group as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). The Last Call period ends 26 January 2013. All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

The DeviceLightEvent interface provides web developers information about the ambient light levels near the hosting in terms of lux units.

The LightLevelEvent interface provides web developers information about the ambient light levels near the hosting in terms of general ranges.

The values of the LightLevelEvent event may be "normal", "dim", or "bright". "bright" is supposed to mean "direct sunlight, or similarly bright conditions that make it hard to see things that aren't high-contrast". "dim" is supposed to mean "dark enough that the light produced by a white background is eye-straining or distracting". The lux values for "dim" typical begin below 50, and the values for "bright" begin above 10000.

This is achieved by interrogating a photosensors or similar detectors of a device.

2. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

3. Terminology

The EventHandler interface represents a callback function used for event handlers as defined in [HTML5].

The concepts queue a task and fires a simple event are defined in [HTML5].

The terms event handlers and event handler event types are defined in [HTML5].

The concepts create an event and fire an event are defined in [DOM4].

The value device light is a value that represents the ambient light levels around the hosting device in lux units.

4. Security and privacy considerations

5. Device Light

The HTML5 specification [HTML5] defines a Window interface, which this specification extends:

partial interface Window {
             attribute EventHandler ondevicelight;
};

5.1 Attributes

ondevicelight of type EventHandler

The ondevicelight event handler and its corresponding event handler event type devicelight must be supported as an IDL attribute by all objects implementing the Window interface.

5.2 DeviceLightEvent Interface

[Constructor (DOMString type, optional DeviceLightEventInit eventInitDict)]
interface DeviceLightEvent : Event {
    readonly attribute double value;
};
dictionary DeviceLightEventInit : EventInit { double value; };

5.2.1 Attributes

value of type double, readonly
The ambient light level in lux.

5.2.2 Dictionary DeviceLightEventInit Members

value of type double

When a user agent is required to fire a device light event, the user agent must run the following steps:

  1. Create an event that uses the DeviceLightEvent interface, with the name devicelight, which bubbles, is not cancelable, and has no default action, that also meets the following conditions:
    1. If the implementation is unable to report the current device light, initialize the value attribute to positive Infinity, otherwise initialize the attribute to the current device light.
  2. Queue a task to dispatch the newly created event at the Window object.

When the current light changes, the user agent must fire a device light event.

Note
The definition of granularity i.e. how often the event is fired is left to the implementation. Implementations may fire the event if they have reason to believe that the page does not have sufficiently fresh data.

5.2.3 Event handlers

The following are the event handlers (and their corresponding event handler event types) that must be supported as attributes by the Window object:

event handler event handler event type
ondevicelight devicelight

6. Light Level

The HTML5 specification [HTML5] defines a Window interface, which this specification extends:

partial interface Window {
             attribute EventHandler onlightlevel;
};

6.1 Attributes

onlightlevel of type EventHandler

The onlightlevel event handler and its corresponding event handler event type lightlevel must be supported as an IDL attribute by all objects implementing the Window interface.

6.2 LightLevelEvent Interface

[Constructor (DOMString type, optional LightLevelEventInit eventInitDict)]
interface LightLevelEvent : Event {
    readonly attribute string value;
};
dictionary LightLevelEventInit : EventInit { string value; };

6.2.1 Attributes

value of type string, readonly
The light level may be one of the following strings: "normal", "dim", or "bright". The corresponding lux values are left up to the UA.

6.2.2 Dictionary LightLevelEventInit Members

value of type string

When a user agent is required to fire a light level event, the user agent must run the following steps:

  1. Create an event that uses the LightLevelEvent interface, with the name lightlevel, which bubbles, is not cancelable, and has no default action, that also meets the following conditions:
    1. If the implementation is unable to report the current light level, initialize the value attribute to empty string, otherwise initialize the attribute to the current light level.
  2. Queue a task to dispatch the newly created event at the Window object.

When the current light changes, the user agent must fire a light level event.

Note
The definition of granularity i.e. how often the event is fired is left to the implementation. Implementations may fire the event if they have reason to believe that the page does not have sufficiently fresh data.

6.2.3 Event handlers

The following are the event handlers (and their corresponding event handler event types) that must be supported as attributes by the Window object:

event handler event handler event type
onlightlevel lightlevel

A. Acknowledgements

Doug Turner for the initial prototype and Marcos Caceres for the test suite.

B. References

B.1 Normative references

[DOM4]
Anne van Kesteren; Aryeh Gregor; Ms2ger. DOM4. URL: http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html/
[HTML5]
Ian Hickson; David Hyatt. HTML5. 29 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt