Proximity Events

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.

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 24 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.

1. Introduction

This section is non-normative.

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.

3. Terminology

The EventHandler interface represents a callback 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 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.

The maximum sensing distance at which the sensor can detect a physical object.

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.

5. Device proximity

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

partial interface Window {
             attribute EventHandler ondeviceproximity;
};

5.1 Attributes

ondeviceproximity of type EventHandler

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.

5.2 `DeviceProximityEvent` Interface

[Constructor (DOMString type, optional DeviceProximityEventInit eventInitDict)]
interface DeviceProximityEvent : Event {
    readonly attribute double value;
    readonly attribute double min;
    readonly attribute double max;
};
dictionary DeviceProximityEventInit : EventInit {
    double value;
    double min;
    double max;
};

5.2.1 Attributes

max of type double, readonly: The maximum sensing distance.
min of type double, readonly: The minimum sensing distance.
value of type double, readonly: The current device proximity.

5.2.2 Dictionary `DeviceProximityEventInit` Members

max of type double
min of type double
value of type double

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

Create an event that uses the DeviceProximityEvent interface, with the name deviceproximity, 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 proximity, initialize the value attribute to positive Infinity, otherwise initialize the attribute to the current device proximity.
2. If the implementation is unable to report the minimum sensing distance, initialize the min attribute to negative Infinity, otherwise initialize the attribute to the minimum sensing distance.
3. If the implementation is unable to report the maximum sensing distance, initialize the max attribute to positive Infinity, otherwise initialize the attribute to the maximum sensing distance.
Queue a task to dispatch the newly created event at the Window object.

When the current proximity changes, the user agent must fire a device proximity 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. Different devices may also support different minimum and maximum sensing distances as well as different resolution, thus authors are strongly advised to use the UserProximityEvent interface if the are only interested in finding out if the user is near or far.

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
`ondeviceproximity`	`deviceproximity`

6. User proximity

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

partial interface Window {
             attribute EventHandler onuserproximity;
};

6.1 Attributes

onuserproximity of type EventHandler

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.

6.2 `UserProximityEvent` Interface

[Constructor (DOMString type, optional UserProximityEventInit eventInitDict)]
interface UserProximityEvent : Event {
    readonly attribute boolean near;
};
dictionary UserProximityEventInit : EventInit {
    boolean near;
};

6.2.1 Attributes

near of type boolean, readonly: The current user proximity state.

6.2.2 Dictionary `UserProximityEventInit` Members

near of type boolean

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

Create an event that uses the UserProximityEvent interface, with the name userproximity, 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 user proximity state, initialize the near attribute to false, otherwise initialize the attribute to the current user proximity state.
Queue a task to dispatch the newly created event at the Window object.

When the current user proximity state changes, the user agent must fire a user proximity event.

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
`onuserproximity`	`userproximity`

Proximity Events

W3C Working Draft 06 December 2012

Abstract

Status of This Document

Table of Contents

1. Introduction

2. Conformance

3. Terminology

4. Security and privacy considerations

5. Device proximity

5.1 Attributes

5.2 `DeviceProximityEvent` Interface

5.2.1 Attributes

5.2.2 Dictionary `DeviceProximityEventInit` Members

5.2.3 Event handlers

6. User proximity

6.1 Attributes

6.2 `UserProximityEvent` Interface

6.2.1 Attributes

6.2.2 Dictionary `UserProximityEventInit` Members

6.2.3 Event handlers

A. Acknowledgements

B. References

B.1 Normative references

Proximity Events

W3C Working Draft 06 December 2012

Abstract

Status of This Document

Table of Contents

1. Introduction

2. Conformance

3. Terminology

4. Security and privacy considerations

5. Device proximity

5.1 Attributes

5.2 DeviceProximityEvent Interface

5.2.1 Attributes

5.2.2 Dictionary DeviceProximityEventInit Members

5.2.3 Event handlers

6. User proximity

6.1 Attributes

6.2 UserProximityEvent Interface

6.2.1 Attributes

6.2.2 Dictionary UserProximityEventInit Members

6.2.3 Event handlers

A. Acknowledgements

B. References

B.1 Normative references

5.2 `DeviceProximityEvent` Interface

5.2.2 Dictionary `DeviceProximityEventInit` Members

6.2 `UserProximityEvent` Interface

6.2.2 Dictionary `UserProximityEventInit` Members