Copyright © 2011 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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 First Public 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.
BatteryStatusEvent InterfaceThis interface defines the batterystatus event type.
isBattery,
isCharging, and timeRemaining is under
consideration. The working group is looking for high value use
cases for the said properties.
[NoInterfaceObject]
interface BatteryStatusEvent : Event {
readonly attribute boolean isBattery;
readonly attribute boolean isCharging;
readonly attribute float? level;
readonly attribute unsigned long? timeRemaining;
void initBatteryStatusEvent (DOMString type, boolean bubbles, boolean cancelable, boolean isBattery, boolean isCharging, float? level, unsigned long? timeRemaining);
};
isBattery of type boolean, readonlyisBattery must be set to true,
otherwise false.
isCharging of type boolean, readonlyisCharging
must be set to true, otherwise false.
level of type float, readonly, nullablelevel must be
set to null.
timeRemaining of type unsigned long, readonly, nullableisCharging is
true, this value represents the
estimated time remaining in seconds before the battery is
depleted, based upon current power usage, if external
power were removed. If the implementation is unable to
report the estimated time remaining,
timeRemaining must be set to null.
initBatteryStatusEventBatteryStatusEvent created
through the DocumentEvent interface
[DOM-LEVEL-3-EVENTS].
| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| type | DOMString | ✘ | ✘ | |
| bubbles | boolean | ✘ | ✘ | |
| cancelable | boolean | ✘ | ✘ | |
| isBattery | boolean | ✘ | ✘ | |
| isCharging | boolean | ✘ | ✘ | |
| level | float | ✔ | ✘ | |
| timeRemaining | unsigned long | ✔ | ✘ |
void
The initBatteryStatusEvent() method must initialize the
event in a manner analogous to the similarly-named method in
[DOM-LEVEL-3-EVENTS].
If a change in the battery status of the hosting device occurs,
then the User Agent must dispatch a BatteryStatusEvent
event on the Window [HTML5] object.
If a change in the battery status of an auxiliary device occurs,
and the auxiliary device is exposed on o object, and
the o implements the EventTarget
[DOM-LEVEL-3-EVENTS] interface, then the User Agent must dispatch a
BatteryStatusEvent event on the o object.
The onbatterystatus event handler must be supported by
Window objects, as an IDL attribute on the
Window object. Similarly, as an IDL attribute on the
o object, if it fulfills the conditions given in the
"change in the battery status of an auxiliary device".
If an event listener is registered with the event type
batterystatus, then the User Agent must dispatch a
BatteryStatusEvent event immediately.
Make immediately explicit and align with [DOM-LEVEL-3-EVENTS].
User Agents should dispatch a BatteryStatusEvent event when
timeRemaining varies by a minute or more.
User Agents should dispatch a BatteryStatusEvent event when
isCharging or isBattery changes.
User Agents should dispatch a BatteryStatusEvent event when
level varies by a 1% or more.
User Agents must dispatch this event type to indicate a change in the battery status.
This section is non-normative.
Register to receive repeated BatteryStatusEvent events.
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); };
Register to receive a single BatteryStatusEvent event.
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; };
Many thanks to the people behind the System Information API and Device Orientation Event Specification for inspiration.
No informative references.