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 specification defines events that provide information about the ambient light level, as measured by a device's light sensor. A LightLevelEvent describes the light level as one of three simple categories - "dim", "normal", and "bright" - while a DeviceLightEvent provides a more granular answer by describing the light level in terms of lux units.
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
The
EventHandler
interface represents a callback function used for event
handlers as defined in [[!HTML5]].
The concepts queue a task, fires a simple event, and browsing context 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 current light level is a value that represents the ambient light levels around the hosting device in lux units.
The current light level state represents the ambient light level around the hosting device as a human-readable string.
The DeviceLightEvent interface provides information about the ambient light levels, as detected by the device's light detector, in terms of lux units.
The HTML5 specification [[!HTML5]] defines a Window interface, which this specification extends:
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.
The value
attribute of the DeviceLightEvent
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 current light level.
When a user agent is required to fire a device light event, the user agent MUST run the following steps:
devicelight
, which
bubbles, is not cancelable, and has no default action, that also
meets the following conditions:
value
attribute to positive Infinity, otherwise initialize the
attribute to the current light level.
When the current light level changes, the user agent MUST queue a task to fire a device light event at each browsing context's Window object.
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 |
The LightLevelEvent 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".
The HTML5 specification [[!HTML5]] defines a Window interface, which this specification extends:
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.
The value
attribute of the LightLevelEvent
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 current light level state.
When a user agent is required to fire a light level event, the user agent MUST run the following steps:
lightlevel
, which
bubbles, is not cancelable, and has no default action, that also
meets the following conditions:
value
attribute to empty string, otherwise initialize the
attribute to the current light level state, which MUST
be one of the following values:
dim
normal
bright
dim
" correspond
to ambient light below 50 lux (dark enough that the light
produced by a white background is eye-straining or
distracting), "normal
" 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
"bright
" correspond to light above 10000 lux
(direct sunlight, or similarly bright conditions that make it
hard to see things that aren't high-contrast).
When the current light level state changes, the user agent MUST queue a task to fire a user proximity event at each browsing context's Window object.
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 |
Doug Turner for the initial prototype and Marcos Caceres for the test suite.