Magnetic Field Events

Introduction

This section is non-normative.

The DeviceMagneticFieldEvent interface provides web developers information about the magnetic field near the hosting device.

This is achieved by interrogating a magnetic field sensor or similar detectors of a device.

Magnetic field sensor is a device that detects the current device magnetic field.

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.

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 current device magnetic field is the magnetic field vector near the hosting device. It is represented by three components x, y and z in X, Y and -Z axis of the device coordinate system in micro-Tesla (uT) unit.

NOTE

The magnetic field's Z axis is inverted.

The device coordinate system is a orthogonal coordinate system in which the X axis refers to the screen's horizontal axis (the small edge in portrait mode, the long edge in landscape mode) and points to the right, the Y axis refers to the screen's vertical axis and points towards the top of the screen (the origin is in the lower-left corner), and the Z axis points toward the sky when the device is lying on its back on a table.

NOTE

The axis are swapped when the device's screen orientation changes.

Magnetic Field

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

partial interface Window {
    attribute EventHandler ondevicemagneticfield;
};

Attributes

ondevicemagneticfield of type EventHandler

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

DeviceMagneticFieldEvent Interface

[Constructor (DOMString type, optional DeviceMagneticFieldEventInit eventInitDict)]
interface DeviceMagneticFieldEvent : Event {
   readonly attribute double x;
   readonly attribute double y;
   readonly attribute double z;
};

dictionary DeviceMagneticFieldEventInit : EventInit {
   double x;
   double y;
   double z;
};

Attributes

x of type double, readonly

Ambient magnetic field in the X axis of the device coordinate system in uT. Ranged from -∞ to +∞.

y of type double, readonly

Ambient magnetic field in the Y axis of the device coordinate system in uT. Ranged from -∞ to +∞.

z of type double, readonly

Ambient magnetic field in the -Z axis of the device coordinate system in uT. Ranged from -∞ to +∞.

Dictionary DeviceMagneticFieldEventInit Members

x of type double

y of type double

z of type double

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

1. Create an event that uses the DeviceMagneticFieldEvent interface, with the name devicemagneticfield, 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 magnetic field, it must stop the service, otherwise initialize the attribute to the current device magnetic field.
2. Queue a task to dispatch the newly created event at the Window object.

When the current device magnetic field changes, the user agent must fire a device magnetic field 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.

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
ondevicemagneticfield	devicemagneticfield

References

Normative references

[DOM4]

Anne van Kesteren; Aryeh Gregor; Ms2ger. DOM4. URL: http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html/

[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

[HTML5]

Ian Hickson; David Hyatt. HTML5. 29 March 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/html5

Informative references

No informative references.