dap commit: rename ReSpec source to Overview.src.html, add a generated spec Overview.html

changeset:   369:662d11531e98
tag:         tip
user:        Anssi Kostiainen <anssi.kostiainen@nokia.com>
date:        Fri Feb 01 10:41:39 2013 +0200
files:       battery/Overview.html battery/Overview.src.html
description:
rename ReSpec source to Overview.src.html, add a generated spec Overview.html


diff -r fa88fd8083d5 -r 662d11531e98 battery/Overview.html
--- a/battery/Overview.html	Fri Feb 01 10:29:37 2013 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,440 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>Battery Status API</title>
-    <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
-    <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
-    <script class="remove">
-      var respecConfig = {
-          specStatus:           "ED",
-          shortName:            "battery-status",
-          //publishDate:          "2012-05-08",
-          previousPublishDate:  "2012-05-08",
-          previousMaturity:     "CR",
-          edDraftURI:           "http://dvcs.w3.org/hg/dap/raw-file/default/battery/Overview.html",
-          // lcEnd:                "2011-12-20",
-          crEnd:                "2012-07-01",
-          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",
-          testSuiteURI: "http://w3c-test.org/dap/battery/tests/"
-      };
-    </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 sh_javascript">
-        &lt;!DOCTYPE html&gt;
-        &lt;html&gt;
-        &lt;head&gt;
-          &lt;title&gt;Email Client&lt;/title&gt;
-          &lt;script&gt;
-            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);
-          &lt;/script&gt;
-        &lt;/head&gt;
-        &lt;body&gt;&lt;/body&gt;
-        &lt;/html&gt;
-
-      </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 sh_javascript">
-        &lt;!DOCTYPE html&gt;
-        &lt;html&gt;
-        &lt;head&gt;
-          &lt;title&gt;Battery-aware Email Client&lt;/title&gt;
-          &lt;script&gt;
-            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 &lt; 60 * 30 || battery.level &lt; 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 &lt; 60 * 10 || battery.level &lt; 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);
-          &lt;/script&gt;
-        &lt;/head&gt;
-        &lt;body&gt;&lt;/body&gt;
-        &lt;/html&gt;
-      </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#eventhandler">
-        EventHandler</a></code> interface represents a callback used for event
-        handlers 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.
-        </dd>
-        <dt>readonly attribute unrestricted double chargingTime</dt>
-        <dd>
-          Represents the time remaining in seconds until the system's battery
-          is fully charged.
-        </dd>
-        <dt>readonly attribute unrestricted 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.
-        </dd>
-        <dt>readonly attribute double level</dt>
-        <dd>
-          Represents the current battery level scaled from 0 to 1.0.
-        </dd>
-        <dt class="no-docs">
-          attribute EventHandler onchargingchange
-        </dt>
-        <dd>
-        </dd>
-        <dt class="no-docs">
-          attribute EventHandler onchargingtimechange
-        </dt>
-        <dd>
-        </dd>
-        <dt class="no-docs">
-          attribute EventHandler ondischargingtimechange
-        </dt>
-        <dd>
-        </dd>
-        <dt class="no-docs">
-          attribute EventHandler 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>
-        The <code>charging</code> 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. 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><a>chargingchange</a></code> at the
-        <a>BatteryManager</a> object.
-      </p>
-      <p>
-        The <code>chargingTime</code> 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. 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><a>chargingtimechange</a></code> at the
-        <a>BatteryManager</a> object.
-      </p>
-      <p>
-        The <code>dischargingTime</code> 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. 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><a>dischargingtimechange</a></code> at the
-        <a>BatteryManager</a> object.
-      </p>
-      <p>
-        The <code>level</code> 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. 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><a>levelchange</a></code> at
-        the <a>BatteryManager</a> object.
-      </p>
-      <div class="note">
-        The definition of how often the <code><a>chargingtimechange</a></code>,
-        <code><a>dischargingtimechange</a></code>, and <code><a>levelchange</a>
-        </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><dfn>chargingchange</dfn></code></td>
-            </tr>
-            <tr>
-              <td><strong><code>onchargingtimechange</code></strong></td>
-              <td><code><dfn>chargingtimechange</dfn></code></td>
-            </tr>
-            <tr>
-              <td><strong><code>ondischargingtimechange</code></strong></td>
-              <td><code><dfn>dischargingtimechange</dfn></code></td>
-            </tr>
-            <tr>
-              <td><strong><code>onlevelchange</code></strong></td>
-              <td><code><dfn>levelchange</dfn></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>
-      <pre class="example sh_javascript">
-        navigator.battery.onlevelchange = function () {
-          console.log(navigator.battery.level);
-        };
-      </pre>
-      <p>
-        Alternatively, the same using the <code>addEventListener()</code>
-        method:
-      </p>
-      <pre class="example sh_javascript">
-      navigator.battery.addEventListener('levelchange', function () {
-        console.log(navigator.battery.level);
-      }, false);
-      </pre>
-      <p>
-        The following example updates the indicators to show the charging
-        state, level and time remaining in minutes:
-      </p>
-      <pre class="example sh_javascript">
-        &lt;!DOCTYPE html&gt;
-        &lt;html&gt;
-        &lt;head&gt;
-          &lt;title&gt;Battery Status API Example&lt;/title&gt;
-          &lt;script&gt;
-            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;
-            };
-          &lt;/script&gt;
-        &lt;/head&gt;
-        &lt;body&gt;
-          &lt;div id="charging"&gt;(charging state unknown)&lt;/div&gt;
-          &lt;div id="level"&gt;(battery level unknown)&lt;/div&gt;
-          &lt;div id="dischargingTime"&gt;(discharging time unknown)&lt;/div&gt;
-        &lt;/body&gt;
-        &lt;/html&gt;
-      </pre>
-    </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 fa88fd8083d5 -r 662d11531e98 battery/Overview.src.html
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/battery/Overview.src.html	Fri Feb 01 10:41:39 2013 +0200
@@ -0,0 +1,440 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Battery Status API</title>
+    <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
+    <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
+    <script class="remove">
+      var respecConfig = {
+          specStatus:           "ED",
+          shortName:            "battery-status",
+          //publishDate:          "2012-05-08",
+          previousPublishDate:  "2012-05-08",
+          previousMaturity:     "CR",
+          edDraftURI:           "http://dvcs.w3.org/hg/dap/raw-file/default/battery/Overview.html",
+          // lcEnd:                "2011-12-20",
+          crEnd:                "2012-07-01",
+          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",
+          testSuiteURI: "http://w3c-test.org/dap/battery/tests/"
+      };
+    </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 sh_javascript">
+        &lt;!DOCTYPE html&gt;
+        &lt;html&gt;
+        &lt;head&gt;
+          &lt;title&gt;Email Client&lt;/title&gt;
+          &lt;script&gt;
+            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);
+          &lt;/script&gt;
+        &lt;/head&gt;
+        &lt;body&gt;&lt;/body&gt;
+        &lt;/html&gt;
+
+      </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 sh_javascript">
+        &lt;!DOCTYPE html&gt;
+        &lt;html&gt;
+        &lt;head&gt;
+          &lt;title&gt;Battery-aware Email Client&lt;/title&gt;
+          &lt;script&gt;
+            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 &lt; 60 * 30 || battery.level &lt; 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 &lt; 60 * 10 || battery.level &lt; 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);
+          &lt;/script&gt;
+        &lt;/head&gt;
+        &lt;body&gt;&lt;/body&gt;
+        &lt;/html&gt;
+      </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#eventhandler">
+        EventHandler</a></code> interface represents a callback used for event
+        handlers 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.
+        </dd>
+        <dt>readonly attribute unrestricted double chargingTime</dt>
+        <dd>
+          Represents the time remaining in seconds until the system's battery
+          is fully charged.
+        </dd>
+        <dt>readonly attribute unrestricted 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.
+        </dd>
+        <dt>readonly attribute double level</dt>
+        <dd>
+          Represents the current battery level scaled from 0 to 1.0.
+        </dd>
+        <dt class="no-docs">
+          attribute EventHandler onchargingchange
+        </dt>
+        <dd>
+        </dd>
+        <dt class="no-docs">
+          attribute EventHandler onchargingtimechange
+        </dt>
+        <dd>
+        </dd>
+        <dt class="no-docs">
+          attribute EventHandler ondischargingtimechange
+        </dt>
+        <dd>
+        </dd>
+        <dt class="no-docs">
+          attribute EventHandler 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>
+        The <code>charging</code> 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. 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><a>chargingchange</a></code> at the
+        <a>BatteryManager</a> object.
+      </p>
+      <p>
+        The <code>chargingTime</code> 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. 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><a>chargingtimechange</a></code> at the
+        <a>BatteryManager</a> object.
+      </p>
+      <p>
+        The <code>dischargingTime</code> 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. 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><a>dischargingtimechange</a></code> at the
+        <a>BatteryManager</a> object.
+      </p>
+      <p>
+        The <code>level</code> 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. 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><a>levelchange</a></code> at
+        the <a>BatteryManager</a> object.
+      </p>
+      <div class="note">
+        The definition of how often the <code><a>chargingtimechange</a></code>,
+        <code><a>dischargingtimechange</a></code>, and <code><a>levelchange</a>
+        </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><dfn>chargingchange</dfn></code></td>
+            </tr>
+            <tr>
+              <td><strong><code>onchargingtimechange</code></strong></td>
+              <td><code><dfn>chargingtimechange</dfn></code></td>
+            </tr>
+            <tr>
+              <td><strong><code>ondischargingtimechange</code></strong></td>
+              <td><code><dfn>dischargingtimechange</dfn></code></td>
+            </tr>
+            <tr>
+              <td><strong><code>onlevelchange</code></strong></td>
+              <td><code><dfn>levelchange</dfn></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>
+      <pre class="example sh_javascript">
+        navigator.battery.onlevelchange = function () {
+          console.log(navigator.battery.level);
+        };
+      </pre>
+      <p>
+        Alternatively, the same using the <code>addEventListener()</code>
+        method:
+      </p>
+      <pre class="example sh_javascript">
+      navigator.battery.addEventListener('levelchange', function () {
+        console.log(navigator.battery.level);
+      }, false);
+      </pre>
+      <p>
+        The following example updates the indicators to show the charging
+        state, level and time remaining in minutes:
+      </p>
+      <pre class="example sh_javascript">
+        &lt;!DOCTYPE html&gt;
+        &lt;html&gt;
+        &lt;head&gt;
+          &lt;title&gt;Battery Status API Example&lt;/title&gt;
+          &lt;script&gt;
+            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;
+            };
+          &lt;/script&gt;
+        &lt;/head&gt;
+        &lt;body&gt;
+          &lt;div id="charging"&gt;(charging state unknown)&lt;/div&gt;
+          &lt;div id="level"&gt;(battery level unknown)&lt;/div&gt;
+          &lt;div id="dischargingTime"&gt;(discharging time unknown)&lt;/div&gt;
+        &lt;/body&gt;
+        &lt;/html&gt;
+      </pre>
+    </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 Friday, 1 February 2013 08:42:09 UTC