- From: Mercurial notifier <cvsmail@w3.org>
- Date: Wed, 08 Feb 2012 12:52:35 +0000
- To: public-dap-commits@w3.org
changeset: 52:4e685ba4490f
tag: tip
user: Anssi Kostiainen <anssi.kostiainen@nokia.com>
date: Wed Feb 08 14:52:12 2012 +0200
files: battery/Overview.html battery/index.html
description:
rename index.html to Overview.html
diff -r 276c406c06cc -r 4e685ba4490f battery/Overview.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/battery/Overview.html Wed Feb 08 14:52:12 2012 +0200
@@ -0,0 +1,433 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Battery Status API</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
+ <script src='http://respec.specifiction.com/js/profiles/w3c-common.js' class='remove'></script>
+ <script class="remove">
+ var respecConfig = {
+ specStatus: "ED",
+ shortName: "battery-status",
+ //publishDate: "2011-11-29",
+ previousPublishDate: "2011-11-29",
+ previousMaturity: "LC",
+ edDraftURI: "http://dvcs.w3.org/hg/dap/raw-file/tip/battery/index.html",
+ lcEnd: "2011-12-20",
+ editors: [
+ { name: "Anssi Kostiainen", company: "Nokia", companyURL: "http://nokia.com/" },
+ { name: "Mounir Lamouri", company: "Mozilla", companyURL: "http://mozilla.org/" }
+ ],
+ inlineCSS: true,
+ noIDLIn: true,
+ extraCSS: ["../ReSpec.js/css/respec.css"],
+ wg: "Device APIs Working Group",
+ wgURI: "http://www.w3.org/2009/dap/",
+ wgPublicList: "public-device-apis",
+ wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
+ };
+ </script>
+ </head>
+ <body>
+ <section id="abstract">
+ This specification defines an API that provides information about the
+ battery status of the hosting device.
+ </section>
+
+ <section id="sotd">
+ <p>
+ The functionality described in this specification was initially
+ specified as part of the
+ <a href="http://www.w3.org/TR/system-info-api/">System Information
+ API</a> 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.
+ </p>
+ </section>
+
+ <section class="informative">
+ <h2>Introduction</h2>
+ <p>
+ The Battery Status API specification defines a means for web
+ developers to programmatically determine the battery status of the
+ 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 API can be used to defer or scale back work when
+ the device is not charging 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 charging,
+ but do so less frequently if the device is not charging or is low on
+ battery. Another example is a web-based word processor which could
+ monitor the battery level and save changes before the battery runs
+ out to prevent data loss.
+ </p>
+ <p>
+ The following example shows how a web-based email client could check
+ for new emails every ten seconds without knowledge of the battery
+ status:
+ </p>
+ <pre class="example highlight">
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Email Client</title>
+ <script>
+ var mail = {
+ INTERVAL_DEFAULT: 1000 * 10,
+ interval: null,
+ timer: 0,
+
+ check: function () {
+ console.log('Checking the server for new emails using an interval of ' +
+ (mail.interval / 1000) + ' seconds.');
+ },
+
+ setTimer: function (interval) {
+ if (interval === mail.interval) { return; }
+ if (mail.timer !== 0) { clearTimeout(mail.timer); }
+ if (interval) { mail.timer = setInterval(function () { mail.check(); }, interval); }
+ mail.interval = interval;
+ }
+ };
+
+ window.addEventListener('load', function () {
+ mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
+ }, false);
+ </script>
+ </head>
+ <body></body>
+ </html>
+
+ </pre>
+ <p>
+ The script will always check for emails every ten seconds, even if the
+ battery level is critically low and the device is not charging.
+ This is an example of poor resource management.
+ </p>
+ <p>
+ 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 highlight">
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Battery-aware Email Client</title>
+ <script>
+ var mail = {
+ INTERVAL_BATTERY_LOW: 1000 * 60 * 10,
+ INTERVAL_DEFAULT: 1000 * 10,
+ interval: null,
+ timer: 0,
+
+ check: function () {
+ console.log('Checking the server for new emails using an interval of ' +
+ (mail.interval / 1000) + ' seconds.');
+ },
+
+ setTimer: function (interval) {
+ if (interval === mail.interval) { return; }
+ if (mail.timer !== 0) { clearTimeout(mail.timer); }
+ if (interval) { mail.timer = setInterval(function () { mail.check(); }, interval); }
+ mail.interval = interval;
+ }
+ };
+
+ window.addEventListener('load', function () {
+ mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
+ }, false);
+
+ var battery = navigator.battery;
+
+ battery.addEventListener('dischargingtimechange', function () {
+ if (battery.dischargingTime < 60 * 30 || battery.level < 0.1) {
+ mail.setTimer(mail.INTERVAL_BATTERY_LOW);
+ console.log('30 minutes remaining or level below 10%, checking the server less frequently.');
+ } else if (battery.dischargingTime < 60 * 10 || battery.level < 0.05) {
+ mail.setTimer(null);
+ console.log('10 minutes remaining or level below 5%, stop checking the server.');
+ }
+ }, false);
+
+ battery.addEventListener('chargingchange', function () {
+ if (battery.charging) {
+ mail.setTimer(mail.INTERVAL_DEFAULT);
+ console.log('Battery is charging, checking the server normally.');
+ }
+ }, false);
+ </script>
+ </head>
+ <body></body>
+ </html>
+ </pre>
+ </section>
+
+ <section id="conformance">
+ <p>
+ This specification defines conformance criteria that apply to a single
+ product: the <dfn>user agent</dfn> that implements the
+ interfaces that it contains.
+ </p>
+ <p>
+ Implementations that use ECMAScript to implement the APIs defined in
+ this specification must implement them in a manner consistent with the
+ ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]],
+ as this specification uses that specification and terminology.
+ </p>
+ </section>
+ <section>
+ <h2>Terminology</h2>
+ <p>
+ The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#function">
+ Function</a></code> interface represents a function in the scripting
+ language being used as defined in [[!HTML5]].
+ </p>
+ <p>
+ The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
+ queue a task</a></dfn> and
+ <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
+ fires a simple event</a></dfn> are defined in [[!HTML5]].
+ </p>
+ <p>
+ The terms <dfn> <a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
+ event handlers</a></dfn> and
+ <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
+ event handler event types</a></dfn> are defined in [[!HTML5]].
+ </p>
+ </section>
+ <section>
+ <h2>Security and privacy considerations</h2>
+ <p>
+ The API defined in this specification is used to determine the battery
+ status of the hosting device. The information disclosed has minimal
+ impact on privacy or fingerprinting, and therefore is exposed without
+ permission grants. For example, authors cannot directly know if there
+ is a battery or not in the hosting device.
+ </p>
+ </section>
+ <section>
+ <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>
+ </dl>
+ </section>
+
+ <section>
+ <h2><a>BatteryManager</a> Interface</h2>
+ <dl title="[NoInterfaceObject]
+ interface BatteryManager : EventTarget"
+ class="idl">
+ <dt>readonly attribute boolean charging</dt>
+ <dd>
+ Represents if the system's battery is charging. The attribute MUST be
+ set to false if the battery is discharging, and set to true, if the
+ battery is charging, the implementation is unable to report the
+ state, or there is no battery attached to the system, or otherwise.
+ </dd>
+ <dt>readonly attribute double chargingTime</dt>
+ <dd>
+ Represents the time remaining in seconds until the system's battery
+ is fully charged. The attribute MUST be set to 0, if the battery is
+ full or there is no battery attached to the system, and to the value
+ positive Infinity if the battery is discharging, the implementation
+ is unable to report the remaining charging time, or otherwise.
+ </dd>
+ <dt>readonly attribute double dischargingTime</dt>
+ <dd>
+ Represents the time remaining in seconds until the system's battery
+ is completely discharged and the system is about to be suspended. The
+ attribute MUST be set to the value positive Infinity, if the battery
+ is charging, the implementation is unable to report the remaining
+ discharging time, there is no battery attached to the system, or
+ otherwise.
+ </dd>
+ <dt>readonly attribute double level</dt>
+ <dd>
+ Represents the current battery level scaled from 0 to 1.0. The
+ attribute MUST be set to 0 if the system's battery is depleted and
+ the system is about to be suspended, and to 1.0 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>[TreatNonCallableAsNull] attribute Function? onchargingchange</dt>
+ <dd>
+ </dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onchargingtimechange</dt>
+ <dd>
+ </dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? ondischargingtimechange</dt>
+ <dd>
+ </dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onlevelchange</dt>
+ <dd>
+ </dd>
+ </dl>
+ <p>
+ When a <code>BatteryManager</code> object is created,
+ <code>charging</code> MUST be set to true, <code>chargingTime</code>
+ to 0, <code>level</code> to 1.0 and <code>dischargingTime</code> to
+ the value positive Infinity, if the implementation is unable to report
+ the battery's charging state, charging time, level or remaining time
+ respectively.
+ </p>
+ <p>
+ When the battery charging state is updated, the <a>user agent</a> MUST
+ <a>queue a task</a> which sets the <code>charging</code> attribute's
+ value and <a>fires a simple event</a> named <code>chargingchange</code>
+ at the <a>BatteryManager</a> object.
+ </p>
+ <p>
+ When the battery charging time is updated, the <a>user agent</a> MUST
+ <a>queue a task</a> which sets the <code>chargingTime</code>
+ attribute's value and <a>fires a simple event</a> named
+ <code>chargingtimechange</code> at the <a>BatteryManager</a> object.
+ </p>
+ <p>
+ When the battery discharging time is updated, the <a>user agent</a>
+ MUST <a>queue a task</a> which sets the <code> dischargingTime</code>
+ attribute's value and <a>fires a simple event </a> named
+ <code>dischargingtimechange</code> at the <a>BatteryManager</a> object.
+ </p>
+ <p>
+ When the battery level is updated, the <a>user agent</a> MUST
+ <a>queue a task</a> which sets the <code> level</code> attribute's
+ value and <a>fires a simple event</a> named <code>levelchange</code>
+ at the <a>BatteryManager</a> object.
+ </p>
+ <div class="note">
+ The definition of how often the <code>chargingtimechange</code>,
+ <code>dischargingtimechange</code>, and <code>levelchange</code> events
+ are fired is left to the implementation.
+ </div>
+ <section>
+ <h2>Event handlers</h2>
+ <p>
+ The following are the <a>event handlers</a> (and their corresponding
+ <a>event handler event types</a>) that MUST be supported as
+ attributes by the <a>BatteryManager</a> object:
+ </p>
+ <table class="simple">
+ <thead>
+ <tr>
+ <th>event handler</th>
+ <th>event handler event type</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><strong><code>onchargingchange</code></strong></td>
+ <td><code>chargingchange</code></td>
+ </tr>
+ <tr>
+ <td><strong><code>onchargingtimechange</code></strong></td>
+ <td><code>chargingtimechange</code></td>
+ </tr>
+ <tr>
+ <td><strong><code>ondischargingchange</code></strong></td>
+ <td><code>dischargingchange</code></td>
+ </tr>
+ <tr>
+ <td><strong><code>onlevelchange</code></strong></td>
+ <td><code>levelchange</code></td>
+ </tr>
+ </tbody>
+ </table>
+ </section>
+ </section>
+
+ <section class="informative">
+ <h2>Examples</h2>
+ <p>
+ This trivial example writes the battery level to the console each time
+ the level changes:
+ </p>
+ <div class="example">
+ <pre class="example highlight">
+ navigator.battery.onlevelchange = function () {
+ console.log(navigator.battery.level);
+ };
+ </pre>
+ </div>
+ <p>
+ Alternatively, the same using the <code>addEventListener()</code>
+ method:
+ </p>
+ <div class="example">
+ <pre class="example highlight">
+ navigator.battery.addEventListener('levelchange', function () {
+ console.log(navigator.battery.level);
+ }, false);
+ </pre>
+ </div>
+ <p>
+ The following example updates the indicators to show the charging
+ state, level and time remaining in minutes:
+ </p>
+ <div class="example">
+ <pre class="example highlight">
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>Battery Status API Example</title>
+ <script>
+ var battery = navigator.battery;
+
+ battery.onchargingchange = function () {
+ document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
+ };
+
+ battery.onlevelchange = function () {
+ document.querySelector('#level').textContent = battery.level;
+ };
+
+ battery.ondischargingtimechange = function () {
+ document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
+ };
+ </script>
+ </head>
+ <body>
+ <div id="charging">(charging state unknown)</div>
+ <div id="level">(battery level unknown)</div>
+ <div id="dischargingTime">(discharging time unknown)</div>
+ </body>
+ </html>
+ </pre>
+ </div>
+ </section>
+ <section class="appendix">
+ <h2>Acknowledgements</h2>
+ <p>
+ The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and
+ the Mozilla WebAPI team in general 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>
+</html>
diff -r 276c406c06cc -r 4e685ba4490f battery/index.html
--- a/battery/index.html Wed Feb 08 14:35:22 2012 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,433 +0,0 @@
-<!DOCTYPE html>
-<html>
- <head>
- <title>Battery Status API</title>
- <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
- <script src='http://respec.specifiction.com/js/profiles/w3c-common.js' class='remove'></script>
- <script class="remove">
- var respecConfig = {
- specStatus: "ED",
- shortName: "battery-status",
- //publishDate: "2011-11-29",
- previousPublishDate: "2011-11-29",
- previousMaturity: "LC",
- edDraftURI: "http://dvcs.w3.org/hg/dap/raw-file/tip/battery/index.html",
- lcEnd: "2011-12-20",
- editors: [
- { name: "Anssi Kostiainen", company: "Nokia", companyURL: "http://nokia.com/" },
- { name: "Mounir Lamouri", company: "Mozilla", companyURL: "http://mozilla.org/" }
- ],
- inlineCSS: true,
- noIDLIn: true,
- extraCSS: ["../ReSpec.js/css/respec.css"],
- wg: "Device APIs Working Group",
- wgURI: "http://www.w3.org/2009/dap/",
- wgPublicList: "public-device-apis",
- wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
- };
- </script>
- </head>
- <body>
- <section id="abstract">
- This specification defines an API that provides information about the
- battery status of the hosting device.
- </section>
-
- <section id="sotd">
- <p>
- The functionality described in this specification was initially
- specified as part of the
- <a href="http://www.w3.org/TR/system-info-api/">System Information
- API</a> 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.
- </p>
- </section>
-
- <section class="informative">
- <h2>Introduction</h2>
- <p>
- The Battery Status API specification defines a means for web
- developers to programmatically determine the battery status of the
- 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 API can be used to defer or scale back work when
- the device is not charging 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 charging,
- but do so less frequently if the device is not charging or is low on
- battery. Another example is a web-based word processor which could
- monitor the battery level and save changes before the battery runs
- out to prevent data loss.
- </p>
- <p>
- The following example shows how a web-based email client could check
- for new emails every ten seconds without knowledge of the battery
- status:
- </p>
- <pre class="example highlight">
- <!DOCTYPE html>
- <html>
- <head>
- <title>Email Client</title>
- <script>
- var mail = {
- INTERVAL_DEFAULT: 1000 * 10,
- interval: null,
- timer: 0,
-
- check: function () {
- console.log('Checking the server for new emails using an interval of ' +
- (mail.interval / 1000) + ' seconds.');
- },
-
- setTimer: function (interval) {
- if (interval === mail.interval) { return; }
- if (mail.timer !== 0) { clearTimeout(mail.timer); }
- if (interval) { mail.timer = setInterval(function () { mail.check(); }, interval); }
- mail.interval = interval;
- }
- };
-
- window.addEventListener('load', function () {
- mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
- }, false);
- </script>
- </head>
- <body></body>
- </html>
-
- </pre>
- <p>
- The script will always check for emails every ten seconds, even if the
- battery level is critically low and the device is not charging.
- This is an example of poor resource management.
- </p>
- <p>
- 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 highlight">
- <!DOCTYPE html>
- <html>
- <head>
- <title>Battery-aware Email Client</title>
- <script>
- var mail = {
- INTERVAL_BATTERY_LOW: 1000 * 60 * 10,
- INTERVAL_DEFAULT: 1000 * 10,
- interval: null,
- timer: 0,
-
- check: function () {
- console.log('Checking the server for new emails using an interval of ' +
- (mail.interval / 1000) + ' seconds.');
- },
-
- setTimer: function (interval) {
- if (interval === mail.interval) { return; }
- if (mail.timer !== 0) { clearTimeout(mail.timer); }
- if (interval) { mail.timer = setInterval(function () { mail.check(); }, interval); }
- mail.interval = interval;
- }
- };
-
- window.addEventListener('load', function () {
- mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
- }, false);
-
- var battery = navigator.battery;
-
- battery.addEventListener('dischargingtimechange', function () {
- if (battery.dischargingTime < 60 * 30 || battery.level < 0.1) {
- mail.setTimer(mail.INTERVAL_BATTERY_LOW);
- console.log('30 minutes remaining or level below 10%, checking the server less frequently.');
- } else if (battery.dischargingTime < 60 * 10 || battery.level < 0.05) {
- mail.setTimer(null);
- console.log('10 minutes remaining or level below 5%, stop checking the server.');
- }
- }, false);
-
- battery.addEventListener('chargingchange', function () {
- if (battery.charging) {
- mail.setTimer(mail.INTERVAL_DEFAULT);
- console.log('Battery is charging, checking the server normally.');
- }
- }, false);
- </script>
- </head>
- <body></body>
- </html>
- </pre>
- </section>
-
- <section id="conformance">
- <p>
- This specification defines conformance criteria that apply to a single
- product: the <dfn>user agent</dfn> that implements the
- interfaces that it contains.
- </p>
- <p>
- Implementations that use ECMAScript to implement the APIs defined in
- this specification must implement them in a manner consistent with the
- ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]],
- as this specification uses that specification and terminology.
- </p>
- </section>
- <section>
- <h2>Terminology</h2>
- <p>
- The <code><a href="http://dev.w3.org/html5/spec/webappapis.html#function">
- Function</a></code> interface represents a function in the scripting
- language being used as defined in [[!HTML5]].
- </p>
- <p>
- The concepts <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#queue-a-task">
- queue a task</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#fire-a-simple-event">
- fires a simple event</a></dfn> are defined in [[!HTML5]].
- </p>
- <p>
- The terms <dfn> <a href="http://dev.w3.org/html5/spec/webappapis.html#event-handlers">
- event handlers</a></dfn> and
- <dfn><a href="http://dev.w3.org/html5/spec/webappapis.html#event-handler-event-type">
- event handler event types</a></dfn> are defined in [[!HTML5]].
- </p>
- </section>
- <section>
- <h2>Security and privacy considerations</h2>
- <p>
- The API defined in this specification is used to determine the battery
- status of the hosting device. The information disclosed has minimal
- impact on privacy or fingerprinting, and therefore is exposed without
- permission grants. For example, authors cannot directly know if there
- is a battery or not in the hosting device.
- </p>
- </section>
- <section>
- <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>
- </dl>
- </section>
-
- <section>
- <h2><a>BatteryManager</a> Interface</h2>
- <dl title="[NoInterfaceObject]
- interface BatteryManager : EventTarget"
- class="idl">
- <dt>readonly attribute boolean charging</dt>
- <dd>
- Represents if the system's battery is charging. The attribute MUST be
- set to false if the battery is discharging, and set to true, if the
- battery is charging, the implementation is unable to report the
- state, or there is no battery attached to the system, or otherwise.
- </dd>
- <dt>readonly attribute double chargingTime</dt>
- <dd>
- Represents the time remaining in seconds until the system's battery
- is fully charged. The attribute MUST be set to 0, if the battery is
- full or there is no battery attached to the system, and to the value
- positive Infinity if the battery is discharging, the implementation
- is unable to report the remaining charging time, or otherwise.
- </dd>
- <dt>readonly attribute double dischargingTime</dt>
- <dd>
- Represents the time remaining in seconds until the system's battery
- is completely discharged and the system is about to be suspended. The
- attribute MUST be set to the value positive Infinity, if the battery
- is charging, the implementation is unable to report the remaining
- discharging time, there is no battery attached to the system, or
- otherwise.
- </dd>
- <dt>readonly attribute double level</dt>
- <dd>
- Represents the current battery level scaled from 0 to 1.0. The
- attribute MUST be set to 0 if the system's battery is depleted and
- the system is about to be suspended, and to 1.0 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>[TreatNonCallableAsNull] attribute Function? onchargingchange</dt>
- <dd>
- </dd>
- <dt>[TreatNonCallableAsNull] attribute Function? onchargingtimechange</dt>
- <dd>
- </dd>
- <dt>[TreatNonCallableAsNull] attribute Function? ondischargingtimechange</dt>
- <dd>
- </dd>
- <dt>[TreatNonCallableAsNull] attribute Function? onlevelchange</dt>
- <dd>
- </dd>
- </dl>
- <p>
- When a <code>BatteryManager</code> object is created,
- <code>charging</code> MUST be set to true, <code>chargingTime</code>
- to 0, <code>level</code> to 1.0 and <code>dischargingTime</code> to
- the value positive Infinity, if the implementation is unable to report
- the battery's charging state, charging time, level or remaining time
- respectively.
- </p>
- <p>
- When the battery charging state is updated, the <a>user agent</a> MUST
- <a>queue a task</a> which sets the <code>charging</code> attribute's
- value and <a>fires a simple event</a> named <code>chargingchange</code>
- at the <a>BatteryManager</a> object.
- </p>
- <p>
- When the battery charging time is updated, the <a>user agent</a> MUST
- <a>queue a task</a> which sets the <code>chargingTime</code>
- attribute's value and <a>fires a simple event</a> named
- <code>chargingtimechange</code> at the <a>BatteryManager</a> object.
- </p>
- <p>
- When the battery discharging time is updated, the <a>user agent</a>
- MUST <a>queue a task</a> which sets the <code> dischargingTime</code>
- attribute's value and <a>fires a simple event </a> named
- <code>dischargingtimechange</code> at the <a>BatteryManager</a> object.
- </p>
- <p>
- When the battery level is updated, the <a>user agent</a> MUST
- <a>queue a task</a> which sets the <code> level</code> attribute's
- value and <a>fires a simple event</a> named <code>levelchange</code>
- at the <a>BatteryManager</a> object.
- </p>
- <div class="note">
- The definition of how often the <code>chargingtimechange</code>,
- <code>dischargingtimechange</code>, and <code>levelchange</code> events
- are fired is left to the implementation.
- </div>
- <section>
- <h2>Event handlers</h2>
- <p>
- The following are the <a>event handlers</a> (and their corresponding
- <a>event handler event types</a>) that MUST be supported as
- attributes by the <a>BatteryManager</a> object:
- </p>
- <table class="simple">
- <thead>
- <tr>
- <th>event handler</th>
- <th>event handler event type</th>
- </tr>
- </thead>
- <tbody>
- <tr>
- <td><strong><code>onchargingchange</code></strong></td>
- <td><code>chargingchange</code></td>
- </tr>
- <tr>
- <td><strong><code>onchargingtimechange</code></strong></td>
- <td><code>chargingtimechange</code></td>
- </tr>
- <tr>
- <td><strong><code>ondischargingchange</code></strong></td>
- <td><code>dischargingchange</code></td>
- </tr>
- <tr>
- <td><strong><code>onlevelchange</code></strong></td>
- <td><code>levelchange</code></td>
- </tr>
- </tbody>
- </table>
- </section>
- </section>
-
- <section class="informative">
- <h2>Examples</h2>
- <p>
- This trivial example writes the battery level to the console each time
- the level changes:
- </p>
- <div class="example">
- <pre class="example highlight">
- navigator.battery.onlevelchange = function () {
- console.log(navigator.battery.level);
- };
- </pre>
- </div>
- <p>
- Alternatively, the same using the <code>addEventListener()</code>
- method:
- </p>
- <div class="example">
- <pre class="example highlight">
- navigator.battery.addEventListener('levelchange', function () {
- console.log(navigator.battery.level);
- }, false);
- </pre>
- </div>
- <p>
- The following example updates the indicators to show the charging
- state, level and time remaining in minutes:
- </p>
- <div class="example">
- <pre class="example highlight">
- <!DOCTYPE html>
- <html>
- <head>
- <title>Battery Status API Example</title>
- <script>
- var battery = navigator.battery;
-
- battery.onchargingchange = function () {
- document.querySelector('#charging').textContent = battery.charging ? 'charging' : 'not charging';
- };
-
- battery.onlevelchange = function () {
- document.querySelector('#level').textContent = battery.level;
- };
-
- battery.ondischargingtimechange = function () {
- document.querySelector('#dischargingTime').textContent = battery.dischargingTime / 60;
- };
- </script>
- </head>
- <body>
- <div id="charging">(charging state unknown)</div>
- <div id="level">(battery level unknown)</div>
- <div id="dischargingTime">(discharging time unknown)</div>
- </body>
- </html>
- </pre>
- </div>
- </section>
- <section class="appendix">
- <h2>Acknowledgements</h2>
- <p>
- The group is deeply indebted to Mounir Lamouri, Jonas Sicking, and
- the Mozilla WebAPI team in general 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>
-</html>
Received on Wednesday, 8 February 2012 12:54:25 UTC