- From: Anssi Kostiainen via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 19 Oct 2011 17:07:35 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info In directory hutz:/tmp/cvs-serv18132 Modified Files: battery-status.html Log Message: align with Mozilla's Battery API Index: battery-status.html =================================================================== RCS file: /sources/public/2009/dap/system-info/battery-status.html,v retrieving revision 1.55 retrieving revision 1.56 diff -u -d -r1.55 -r1.56 --- battery-status.html 14 Sep 2011 14:58:12 -0000 1.55 +++ battery-status.html 19 Oct 2011 17:07:33 -0000 1.56 @@ -1,16 +1,16 @@ <!DOCTYPE html> <html> <head> - <title>Battery Status Events</title> + <title>Battery Status API</title> <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/> <script src='../ReSpec.js/js/respec.js' class='remove'></script> <script class='remove'> var respecConfig = { - specStatus: "WD", + specStatus: "ED", shortName: "battery-status", - publishDate: "2011-09-15", - previousPublishDate: "2011-06-02", - previousMaturity: "WD", + // publishDate: "2011-09-15", + previousPublishDate: "2011-09-15", + previousMaturity: "WD", edDraftURI: "http://dev.w3.org/2009/dap/system-info/battery-status.html", // lcEnd: "2009-08-05", editors: [ @@ -57,8 +57,8 @@ </head> <body> <section id='abstract'> - This specification defines new DOM event types that provide - information about the battery status of the hosting device. + This specification defines an API that provides information about the + battery status of the hosting device. </section> <section id='sotd'> @@ -74,20 +74,19 @@ <section class="informative"> <h2>Introduction</h2> <p> - The Battery Status Events specification defines a means for web + The Battery Status API specification defines a means for web developers to programmatically determine the battery status of the - hosting device and whether the device is plugged in or not. Without - knowing the battery status of a device, a web developer must design - the web application with an assumption of sufficient battery level - for the task at hand. This means the battery of a device may exhaust - faster than desired because web developers are unable to make - decisions based on the battery status. Given knowledge of the - battery status, web developers are able to craft web content and + hosting device. Without knowing the battery status of a device, a web + developer must design the web application with an assumption of + sufficient battery level for the task at hand. This means the battery + of a device may exhaust faster than desired because web developers are + unable to make decisions based on the battery status. Given knowledge + of the battery status, web developers are able to craft web content and applications which are power-efficient, thereby leading to improved user experience. </p> <p> - The Battery Status Events can be used to defer or scale back work when + The Battery Status API can be used to defer or scale back work when the device is not plugged in or is low on battery. An archetype of an advanced web application, a web-based email client, may check the server for new email every few seconds if the device is plugged in, @@ -139,11 +138,10 @@ This is an example of poor resource management. </p> <p> - Using the <a>batterylow</a>, <a>batterycritical</a> and <a>batteryok</a> - event types, the web application is, for example, able to - throttle checking for emails if the device is low on battery, stop - checking for emails if the battery is critically low and resume - normal operation when the battery status is OK: + Using the <a>BatteryManager</a> interface, the web application is, for + example, able to throttle checking for emails if the device is low on + battery, stop checking for emails if the battery is critically low and + resume normal operation when the battery is charging: </p> <pre class='example sh_javascript'> <!DOCTYPE html> @@ -174,21 +172,23 @@ mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval); }, false); - var battery = new BatteryStatusEventSource(); - - battery.addEventListener('batterylow', function () { - mail.setTimer(mail.INTERVAL_BATTERY_LOW); - console.log('Low battery, checking the server less frequently.'); - }, false); + var battery = navigator.battery; - battery.addEventListener('batterycritical', function () { - mail.setTimer(null); - console.log('Critically low battery, stopped checking the server.'); + battery.addEventListener('remainingchange', function () { + if (battery.chargingState === 'discharging' && battery.remaining < 60 * 30) { + mail.setTimer(mail.INTERVAL_BATTERY_LOW); + console.log('30 minutes remaining, checking the server less frequently.'); + } else if (battery.chargingState === 'discharging' && battery.remaining < 60 * 10) { + mail.setTimer(null); + console.log('10 minutes remaining, stop checking the server.'); + } }, false); - battery.addEventListener('batteryok', function () { - mail.setTimer(mail.INTERVAL_DEFAULT); - console.log('Battery ok, checking the server normally.'); + battery.addEventListener('chargingstatechange', function () { + if (battery.chargingState === 'charging') { + mail.setTimer(mail.INTERVAL_DEFAULT); + console.log('Battery is charging, checking the server normally.'); + } }, false); </script> </head> @@ -204,614 +204,158 @@ interfaces that it contains. </p> </section> - <section> - <h2><a>BatteryStatusEventSource</a> Interface</h2> - <dl title='[Constructor] - interface BatteryStatusEventSource : EventTarget' - class='idl'> - <dt>attribute Function? onbatterystatus</dt> + <h2><a>NavigatorBattery</a> Interface</h2> + <p> + The <a>NavigatorBattery</a> interface is exposed on the + <code>Navigator</code> object. + </p> + <div class='idl' title='Navigator implements NavigatorBattery'></div> + <dl title='[NoInterfaceObject] interface NavigatorBattery' class='idl'> + <dt>readonly attribute BatteryManager battery</dt> <dd> + The object that exposes the battery status information. </dd> - <dt>attribute Function? onbatterylow</dt> + </dl> + <dl title='[NoInterfaceObject] + interface BatteryManager : EventTarget' + class='idl'> + <dt>readonly attribute DOMString chargingState</dt> <dd> + Represents the charging state of the battery. The attribute MUST be + set to the string <code>charging</code> if the battery is charging, + to the string <code>discharging</code>, if the battery is + discharging, to the string <code>full</code> if the battery is full, + or to the string <code>unknown</code> otherwise. The attribute MUST + be set to to the string <code>full</code> if the implementation is + unable to report the battery's level, or there is no battery + attached to the system. </dd> - <dt>attribute Function? onbatterycritical</dt> + <dt>readonly attribute float level</dt> <dd> + Represents the current battery level scaled from <code>0</code> to + <code>1.0</code>. The attribute MUST be set to <code>0</code> if the + system's battery is depleted and the system is about to be suspended, + and to <code>1.0</code> if the battery is full, the implementation is + unable to report the battery's level, or there is no battery attached + to the system. </dd> - <dt>attribute Function? onbatteryok</dt> + <dt>readonly attribute long remaining</dt> <dd> + Represents the time remaining in seconds until the system's battery + is depleted and the system is about to be suspended. The attribute + MUST be set to the value positive Infinity, if the implementation is + unable to report the time remaining, or there is no battery attached + to the system. </dd> - </dl> - <p> - The <code>onbatterystatus</code>, <code>onbatterylow</code>, - <code>onbatterycritical</code> and <code>onbatteryok</code> - event handlers, and their corresponding event handler event types - <a>batterystatus</a>, <a>batterylow</a>, <a>batterycritical</a> - and <a>batteryok</a> respectively MUST be supported as IDL attributes - by all objects implementing the <a>BatteryStatusEventSource</a> - interface. - </p> - <section> - <h2>Constructor</h2> - <p> - The <code>BatteryStatusEventSource()</code> constructor MUST be visible - when the script's global object is either a <code>Window</code> - object [[!HTML5]] or an object implementing the <code>WorkerUtils</code> - interface [[!WEBWORKERS]]. - </p> - <p> - When the constructor is invoked, the <a class="product-ua" href="#ua"> - user agent</a> MUST run the following algorithm: - </p> - <ol class="rule"> - <li> - Instantiate a new <a>BatteryStatusEventSource</a> object, and let - <var>battery</var> be that object. - </li> - <li> - Enable <var>battery</var>'s task source. - </li> - <li> - Return <var>battery</var>. - </li> - </ol> - <p class="note"> - When the <var>battery</var> object has no registered event listeners, - its task source can be disabled as an implementation optimization - technique. - </p> - </section> - </section> - - <section> - <h2><a>BatteryStatusEvent</a> Interface</h2> - <p> - This interface defines the <a>batterystatus</a>, <a>batterylow</a>, - <a>batterycritical</a> and <a>batteryok</a> event types. - </p> - - <dl title='[Constructor(DOMString type, optional BatteryStatusEventInit eventInitDict)] - interface BatteryStatusEvent : Event' - class='idl' data-merge='BatteryStatusEventInit'> - <dt>readonly attribute boolean isPlugged</dt> + <dt>attribute Function? onchargingstatechange</dt> <dd> - Represents whether the device is plugged in. If the device is - plugged in and its battery is being charged or is at its full - capacity, then <code>isPlugged</code> MUST be set to - <code>true</code>, otherwise <code>false</code>. If the device - does not have a battery, then <code>isPlugged</code> MUST be set - to <code>true</code>. </dd> - <dt>readonly attribute float? level</dt> + <dt>attribute Function? onlevelchange</dt> <dd> - 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 the - battery's level, or there is no battery attached to the - system, then <code>level</code> MUST be set to - <code>null</code>. </dd> - <dt>readonly attribute DOMString? status</dt> + <dt>attribute Function? onremainingchange</dt> <dd> - One of <code>"critical"</code>, <code>"low"</code>, <code>"ok"</code> - or <code>null</code>. - Represents the battery status of the hosting device, - scaled from <code>critical</code> to <code>ok</code>. - If the implementation is unable to report the battery's level, - then <code>status</code> MUST be set to <code>null</code>. - If the device does not have a battery, then - <code>status</code> MUST be set to <code>ok</code>. - <p> - The following table represents the relationship between - <code>status</code>, <code>isPlugged</code> and - <code>level</code> attributes, and corresponding events. - The definitions of <em>low_threshold</em> and - <em>critical_threshold</em> are left to the implementation. - </p> - <table id="status-table" class="simple"> - <thead> - <tr> - <th> - status - </th> - <th> - isPlugged - </th> - <th> - level - </th> - <th> - Corresponding event - </th> - </tr> - </thead> - <tbody> - <tr> - <td> - <code>critical</code> - </td> - <td> - <code>false</code> - </td> - <td> - 0 ≤ <code>level</code> ≤ <em>critical_threshold</em> - </td> - <td> - <a>batterycritical</a> - </td> - </tr> - <tr> - <td> - <code>low</code> - </td> - <td> - <code>false</code> - </td> - <td> - <em>critical_threshold</em> < <code>level</code> < - <em>low_threshold</em> - </td> - <td> - <a>batterylow</a> - </td> - </tr> - <tr> - <td> - <code>ok</code> - </td> - <td> - <code>false</code> - </td> - <td> - <em>low_threshold</em> ≤ <code>level</code> ≤ 100 - </td> - <td> - <a>batteryok</a> - </td> - </tr> - <tr> - <td> - <code>ok</code> - </td> - <td> - <code>true</code> - </td> - <td> - 0 ≤ <code>level</code> ≤ 100 - </td> - <td> - <a>batteryok</a> - </td> - </tr> - <tr> - <td> - <code>null</code> - </td> - <td> - <code>true</code> or <code>false</code> - </td> - <td> - <code>null</code> - </td> - <td> - </td> - </tr> - </tbody> - </table> </dd> </dl> - <dl title='dictionary BatteryStatusEventInit : EventInit' - class='idl'> - <dt> - boolean isPlugged - </dt> - <dd></dd> - <dt> - float? level - </dt> - <dd></dd> - <dt> - DOMString? status - </dt> - <dd></dd> - </dl> - <section> - <h2>Constructor</h2> - <p> - <code>BatteryStatusEvent(<var>type</var>, <var>eventInitDict</var>) - </code> is an event constructor, as defined in [[!DOM4]]. - </p> - <p> - When the <a class="product-ua" href="#ua">user agent</a> is required - to dispatch the event, then it MUST run the following algorithm: - <ol class="rule"> - <li> - Create an event that uses the <a>BatteryStatusEvent</a> - interface as defined in [[!DOM4]], which bubbles, and is - cancelable, and has no default action. - </li> - <li> - Queue a task to dispatch the newly created event at the - <a>BatteryStatusEventSource</a> object. - </li> - </ol> - </section> - - <section> - <h3 id='event-batterystatus'>The <dfn class='event'>batterystatus</dfn> - event</h3> - <p> - The <a class="product-ua" href="#ua">user agent</a> MUST dispatch - this event type at the <a>BatteryStatusEventSource</a> object when - a change in the battery status of the hosting device occurs as - follows: - </p> - <ul> - <li> - <code>isPlugged</code> changes its value, or - </li> - <li> - <code>level</code> changes by at least 1, or - </li> - <li> - <code>status</code> changes its value - </li> - </ul> - <p> - When the <code>status</code> attribute changes its value to - <code>low</code>, <code>critical</code> or <code>ok</code>, - then the <a class="product-ua" href="#ua">user agent</a> MUST - dispatch the <a>BatteryStatusEvent</a> event of type - <a>batterylow</a>, <a>batterycritical</a> or <a>batteryok</a> - respectively before dispatching the <a>BatteryStatusEvent</a> - event of type <a>batterystatus</a>. - </p> - <table class='event-type-battery'> - <tr> - <th>Type</th> - <td> - <code>batterystatus</code> - </td> - </tr> - <tr> - <th>Interface</th> - <td> - <a>BatteryStatusEvent</a> if generated by the user agent, - <code>Event</code> otherwise. - </td> - </tr> - <tr> - <th>Sync / Async</th> - <td>Async</td></tr> - <tr> - <th>Bubbles</th> - <td>Yes</td> - </tr> - <tr> - <th>Target</th> - <td><code>defaultView</code></td> - </tr> - <tr> - <th>Cancelable</th> - <td>Yes</td> - </tr> - <tr> - <th>Default action</th> - <td>none</td> - </tr> - <tr> - <th>Context info</th> - <td><code>Event.target: defaultView</code></td> - </tr> - </table> - </section> - - <section> - <h3 id='event-batterylow'>The <dfn class='event'>batterylow</dfn> - event</h3> - <p> - The <a class="product-ua" href="#ua">user agent</a> MUST dispatch - this event type at the <a>BatteryStatusEventSource</a> object when - a change in the battery status of the hosting device occurs as - follows: - </p> - <ul> - <li> - the low battery condition is reached, and - </li> - <li> - <code>isPlugged</code> is <code>false</code>. - </li> - </ul> - <p> - The definition of a low battery condition is left to the - implementation. - </p> - <p> - The condition corresponds to the value of <code>low</code> of - the <code>status</code> attribute on the <a>BatteryStatusEvent</a> - interface. - </p> - <table class='event-type-battery'> - <tr> - <th>Type</th> - <td> - <code>batterylow</code> - </td> - </tr> - <tr> - <th>Interface</th> - <td> - <a>BatteryStatusEvent</a> if generated by the user agent, - <code>Event</code> otherwise. - </td> - </tr> - <tr> - <th>Sync / Async</th> - <td>Async</td></tr> - <tr> - <th>Bubbles</th> - <td>Yes</td> - </tr> - <tr> - <th>Target</th> - <td><code>defaultView</code></td> - </tr> - <tr> - <th>Cancelable</th> - <td>Yes</td> - </tr> - <tr> - <th>Default action</th> - <td>none</td> - </tr> - <tr> - <th>Context info</th> - <td><code>Event.target: defaultView</code></td> - </tr> - </table> - </section> - - <section> - <h3 id='event-batterycritical'>The <dfn class='event'>batterycritical</dfn> - event</h3> - <p> - The <a class="product-ua" href="#ua">user agent</a> MUST dispatch - this event type at the <a>BatteryStatusEventSource</a> object when - a change in the battery status of the hosting device occurs as - follows: - </p> - <ul> - <li> - the critically low battery condition is reached, and - </li> - <li> - <code>isPlugged</code> is <code>false</code>. - </li> - </ul> - <p> - In the critically low battery condition the battery level is lower - than in the low battery condition. Otherwise, the definition of a - critically low battery condition is left to the implementation. - </p> - <p> - The condition corresponds to the value of <code>critical</code> of - the <code>status</code> attribute on the <a>BatteryStatusEvent</a> - interface. - </p> - <table class='event-type-battery'> - <tr> - <th>Type</th> - <td> - <code>batterycritical</code> - </td> - </tr> - <tr> - <th>Interface</th> - <td> - <a>BatteryStatusEvent</a> if generated by the user agent, - <code>Event</code> otherwise. - </td> - </tr> - <tr> - <th>Sync / Async</th> - <td>Async</td></tr> - <tr> - <th>Bubbles</th> - <td>Yes</td> - </tr> - <tr> - <th>Target</th> - <td><code>defaultView</code></td> - </tr> - <tr> - <th>Cancelable</th> - <td>Yes</td> - </tr> - <tr> - <th>Default action</th> - <td>none</td> - </tr> - <tr> - <th>Context info</th> - <td><code>Event.target: defaultView</code></td> - </tr> - </table> - </section> - - <section> - <h3 id='event-batteryok'>The <dfn class='event'>batteryok</dfn> - event</h3> - <p> - The <a class="product-ua" href="#ua">user agent</a> MUST dispatch - this event type on the <a>BatteryStatusEventSource</a> object when - a change in the battery status of the hosting device occurs as - follows: - </p> - <ul> - <li> - <code>isPlugged</code> changes its value to <code>true</code>. - </li> - </ul> - <p> - The condition corresponds to the value of <code>ok</code> of the - <code>status</code> attribute on the <a>BatteryStatusEvent</a> - interface. - </p> - <table class='event-type-battery'> - <tr> - <th>Type</th> - <td> - <code>batteryok</code> - </td> - </tr> - <tr> - <th>Interface</th> - <td> - <a>BatteryStatusEvent</a> if generated by the user agent, - <code>Event</code> otherwise. - </td> - </tr> - <tr> - <th>Sync / Async</th> - <td>Async</td></tr> - <tr> - <th>Bubbles</th> - <td>Yes</td> - </tr> - <tr> - <th>Target</th> - <td><code>defaultView</code></td> - </tr> - <tr> - <th>Cancelable</th> - <td>Yes</td> - </tr> - <tr> - <th>Default action</th> - <td>none</td> - </tr> - <tr> - <th>Context info</th> - <td><code>Event.target: defaultView</code></td> - </tr> - </table> - </section> - </section> - - <section class='informative'> - <h2>Examples</h2> <p> - Register to receive repeated <a>BatteryStatusEvent</a> events: + When a <code>Document</code> object is created, + <code>chargingState</code> MUST be set to the string <code>full</code>, + <code>level</code> to the value of <code>1.0</code> and + <code>remaining</code> to the value positive Infinity, if the implementation + is unable to report the battery's charging state, battery's level or + time remaining respectively. </p> - <div class='example'> - <pre class='example sh_javascript'> - var battery = new BatteryStatusEventSource(); - - battery.addEventListener('batterystatus', function (event) { - console.log(event.level); - }, false); - </pre> - </div> <p> - Register to receive a single <a>BatteryStatusEvent</a> event: - </p> - <div class='example'> - <pre class='example sh_javascript'> - var battery = new BatteryStatusEventSource(); - - var handler = function (event) { - console.log(event.level); - battery.removeEventListener('batterystatus', handler, false); - }; - - battery.addEventListener('batterystatus', handler, false); - </pre> - </div> - <p> - Register to receive a <a>BatteryStatusEvent</a> of type - <a>batterylow</a>: + When the value of <code>charging</code>, <code>level</code> or + <code>remaining</code> attribute changes, the + <a class="product-ua" href="#ua">user agent</a> MUST fire a simple + event [[!HTML5]], which does not bubble and is not cancelable, named + <code>chargingstatechange</code>, <code>levelchange</code> or + <code>remainingchange</code> respectively at the <a>BatteryManager</a> + object. </p> - <div class='example'> - <pre class='example sh_javascript'> - var battery = new BatteryStatusEventSource(); - - battery.addEventListener('batterylow', function () { - console.log('The battery is low.'); - }, false); - </pre> + <div class="issue"> + TODO: The <code>remainingchange</code> event should not be fired + too often, so it should be rate limited. For example, firing every + second is probably too often. Otherwise web developers will + need to resort to event throttling which is inefficient. </div> + </section> + + <section class='informative'> + <h2>Examples</h2> <p> - Register to receive a <a>BatteryStatusEvent</a> of type - <a>batterycritical</a>: + This trivial example writes the battery level to the console each time + the level changes: </p> <div class='example'> <pre class='example sh_javascript'> - var battery = new BatteryStatusEventSource(); - - battery.addEventListener('batterycritical', function () { - console.log('The battery is critically low.'); - }, false); + navigator.battery.onlevelchange = function () { + console.log(navigator.battery.level); + }; </pre> </div> <p> - Register to receive a <a>BatteryStatusEvent</a> of type - <a>batteryok</a>: + Alternatively, the same using the <code>addEventListener()</code> + method: </p> <div class='example'> <pre class='example sh_javascript'> - var battery = new BatteryStatusEventSource(); - - battery.addEventListener('batteryok', function () { - console.log('The battery is ok.'); - }, false); + navigator.battery.addEventListener('levelchange', function () { + console.log(navigator.battery.level); + }, false); </pre> </div> <p> - The following example updates the indicators to show whether or not - the device is plugged in and what is the current battery level and - status: + The following example updates the indicators to show the charging + state, level and time remaining in minutes: </p> <div class='example'> <pre class='example sh_javascript'> <!DOCTYPE html> <html> <head> - <title>Battery Status Event Example</title> + <title>Battery Status API Example</title> <script> - var battery = new BatteryStatusEventSource(); - - battery.addEventListener('batterystatus', function (event) { - document.querySelector('#plugged').textContent = event.isPlugged ? 'plugged' : 'not plugged'; - document.querySelector('#level').textContent = event.level; - document.querySelector('#status').textContent = event.status; - }, false); + var battery = navigator.battery; + + battery.onchargingstatechange = function () { + document.querySelector('#chargingState').textContent = battery.chargingState; + }; + + battery.onlevelchange = function () { + document.querySelector('#level').textContent = battery.level; + }; + + battery.onremainingchange = function () { + document.querySelector('#remaining').textContent = battery.remaining / 60; + }; </script> </head> <body> - <div id="plugged">(plugged state unknown)</div> + <div id="chargingState">(charging state unknown)</div> <div id="level">(battery level unknown)</div> - <div id="status">(battery status unknown)</div> + <div id="remaining">(time remaining unknown)</div> </body> </html> </pre> </div> </section> - <section class='appendix'> <h2>Acknowledgements</h2> <p> - Many thanks to the people behind the System Information API and Device - Orientation Event specification for inspiration. Also thanks to the - nice folks bringing us the Page Visibility specification, which - motivated the editor of this specification to write the introduction - chapter discussing some real-world high value use cases that apply - equally to this specification. Special thanks to all the participants - of the Device APIs Working Group and others who have sent in - substantial feedback and comments, and made the Web a better place for - everyone while doing so. + Big thanks to the Mozilla WebAPI team for their invaluable feedback + based on prototype implementations. Many thanks to the people behind + the System Information API and Device Orientation Event specification + for the initial inspiration. Also thanks to the nice folks bringing us + the Page Visibility specification, which motivated the editor of this + specification to write the introduction chapter discussing some + real-world high value use cases that apply equally to this + specification. Special thanks to all the participants of the Device + APIs Working Group and others who have sent in substantial feedback + and comments, and made the Web a better place for everyone by + doing so. </p> </section> </body>
Received on Wednesday, 19 October 2011 17:07:39 UTC