Battery Status Event Specification

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 System Information API but has been extracted in order to be more readily available, more straightforward to implement, and in order to produce a specification that could be implemented on its own merits without interference with other, often unrelated, features.

This document was published by the Device APIs and Policy Working Group as a 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). 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 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. Conformance
2. BatteryStatusEvent Interface
3. Examples
A. Acknowledgements
B. References
- B.1 Normative references
- B.2 Informative references

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

2. `BatteryStatusEvent` Interface

This interface defines the batterystatus event type.

[NoInterfaceObject]
interface BatteryStatusEvent : Event {
    readonly attribute boolean isPlugged;
    readonly attribute float?  level;
    void initBatteryStatusEvent (DOMString type, boolean bubbles, boolean cancelable, boolean isPlugged, float? level);
};

2.1 Attributes

isPlugged of type boolean, readonly: Represents whether the device is plugged in. If the device is current plugged in and its battery is being charged or is at its full capacity, then isPlugged must be set to true, otherwise false.
No exceptions.
level of type float, readonly, nullable: Represents how much of the internal power source remains, scaled from 0 to 100. A value of 0 indicates that the system's battery is depleted, i.e. it is about to be suspended. If the implementation is unable to report battery's level, then level must be set to null.
No exceptions.

2.2 Methods

initBatteryStatusEvent

Initializes a BatteryStatusEvent created through the DocumentEvent interface [DOM-LEVEL-3-EVENTS].

Parameter	Type	Nullable	Optional
type	`DOMString`	✘	✘
bubbles	`boolean`	✘	✘
cancelable	`boolean`	✘	✘
isPlugged	`boolean`	✘	✘
level	`float`	✔	✘

No exceptions.

Return type: void

The batterystatus event type must be available when the script's global object [HTML5] is either a Window object or an object implementing the WorkerUtils interface [WEBWORKERS].

The initBatteryStatusEvent() method must initialize the event in a manner analogous to the initEvent() method in [DOM-LEVEL-3-EVENTS]. The isPlugged and level arguments must initialize the attributes with the same names.

When a change in the battery status of the hosting device occurs as follows, the User Agent must dispatch a BatteryStatusEvent event on the Window [HTML5] and WorkerGlobalScope [WEBWORKERS] objects:

isPlugged changes, or
level varies by a 1% or more

TODO: Conditions for event triggering must be testable.

The onbatterystatus event handler must be supported by Window and WorkerGlobalScope objects, as an IDL attribute on the Window and WorkerGlobalScope objects respectively.

TODO: Define onbatterystatus event handler in WebIDL.

When an event listener is registered with the event type batterystatus, then the User Agent must dispatch a BatteryStatusEvent event immediately.

TODO: Make immediately explicit and align with [DOM-LEVEL-3-EVENTS].

2.3 The batterystatus Event

Type	`batterystatus`
Interface	`BatteryStatusEvent` if generated by the User Agent, `Event` otherwise.
Sync / Async	Async
Bubbles	No
Target	`defaultView`
Cancelable	No
Default action	none
Context info	`Event.target: defaultView`

3. Examples

This section is non-normative.

By using the addEventListener() method:

window.addEventListener('batterystatus', function (event) {
  console.log(event.level);
}, true);

By assigning a function expression to the onbatterystatus property:

window.onbatterystatus = function (event) {
  console.log(event.level);
};

By using the addEventListener() method:

var handler = function (event) {
  console.log(event.level);
  window.removeEventListener('batterystatus', handler, true);
};

window.addEventListener('batterystatus', handler, true);

By assigning a function expression to the onbatterystatus property:

window.onbatterystatus = function (event) {
  console.log(event.level);
  window.onbatterystatus = null;
};

Battery Status Event Specification

W3C Working Draft 02 June 2011

Abstract

Status of This Document

Table of Contents

1. Conformance

2. `BatteryStatusEvent` Interface

2.1 Attributes

2.2 Methods

2.3 The batterystatus Event

3. Examples

A. Acknowledgements

B. References

B.1 Normative references

B.2 Informative references

Battery Status Event Specification

W3C Working Draft 02 June 2011

Abstract

Status of This Document

Table of Contents

1. Conformance

2. BatteryStatusEvent Interface

2.1 Attributes

2.2 Methods

2.3 The batterystatus Event

3. Examples

A. Acknowledgements

B. References

B.1 Normative references

B.2 Informative references

2. `BatteryStatusEvent` Interface