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.
The DeviceProximityEvent interface provides web developers information about the distance between the hosting device and a nearby object.
The UserProximityEvent interface provides web developers a user-agent- and platform-specific approximation that the hosting device has sensed a nearby object.
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.
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.
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 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 device proximity is a value that represents the proximity of the hosting device to a physical object (i.e., some value between the maximum sensing distance and the minimum sensing distance), in centimeters.
The minimum sensing distance at which the sensor can detect a physical object, in centimeters.
The maximum sensing distance at which the sensor can detect a physical object, in centimeters.
The current user proximity state, a boolean state, is a user-agent- and platform-specific approximation of the closeness of a physical object with the hosting device.
The HTML5 specification [[!HTML5]] defines a Window interface, which this specification extends:
The ondeviceproximity
event handler and its corresponding
event handler event type deviceproximity
MUST be supported
as an IDL attribute by all objects implementing the Window
interface.
The value
attribute of the DeviceProximityEvent
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 device proximity.
The min
attribute of the DeviceProximityEvent
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 minimum sensing distance.
The max
attribute of the DeviceProximityEvent
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 maximum sensing distance.
When a user agent is required to fire a device proximity event, the user agent MUST run the following steps:
deviceproximity
, 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 device proximity.
min
attribute to negative Infinity, otherwise initialize the
attribute to the minimum sensing distance.
max
attribute to positive Infinity, otherwise initialize the
attribute to the maximum sensing distance.
When the current device proximity changes, the user agent MUST queue a task to fire a device 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 |
---|---|
ondeviceproximity |
deviceproximity |
The HTML5 specification [[!HTML5]] defines a Window interface, which this specification extends:
The onuserproximity
event handler and its corresponding
event handler event type userproximity
MUST be supported
as an IDL attribute by all objects implementing the Window
interface.
The near
attribute of the UserProximityEvent
interface MUST return the value it was initialized to. When the
object is created, this attribute MUST be initialized to false.
It represents the current user proximity state.
When a user agent is required to fire a user proximity event, the user agent MUST run the following steps:
userproximity
, which bubbles,
is not cancelable, and has no default action, that also meets the
following conditions:
near
attribute
to false, otherwise initialize the attribute to the current
user proximity state.
When the current user proximity 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 |
---|---|
onuserproximity |
userproximity |
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.