- From: Anssi Kostiainen via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 02 Dec 2011 09:40:15 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv6304
Modified Files:
battery-status.html
Log Message:
bake in Anne's feedback <http://lists.w3.org/Archives/Public/public-device-apis/2011Dec/0005.html> (LC-2574)
Index: battery-status.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/battery-status.html,v
retrieving revision 1.73
retrieving revision 1.74
diff -u -d -r1.73 -r1.74
--- battery-status.html 1 Dec 2011 11:58:38 -0000 1.73
+++ battery-status.html 2 Dec 2011 09:40:13 -0000 1.74
@@ -2,9 +2,9 @@
<html>
<head>
<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'>
+ <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: "ED",
shortName: "battery-status",
@@ -27,17 +27,19 @@
</script>
</head>
<body>
- <section id='abstract'>
+ <section id="abstract">
This specification defines an API that provides information about the
battery status of the hosting device.
</section>
- <section id='sotd'>
+ <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
+ 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>
@@ -53,8 +55,8 @@
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.
+ 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
@@ -68,9 +70,10 @@
</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:
+ for new emails every ten seconds without knowledge of the battery
+ status:
</p>
- <pre class='example sh_javascript'>
+ <pre class="example sh_javascript">
<!DOCTYPE html>
<html>
<head>
@@ -114,7 +117,7 @@
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'>
+ <pre class="example sh_javascript">
<!DOCTYPE html>
<html>
<head>
@@ -168,10 +171,10 @@
</pre>
</section>
- <section id='conformance'>
+ <section id="conformance">
<p>
This specification defines conformance criteria that apply to a single
- product: the <dfn id="ua">user agent</dfn> that implements the
+ product: the <dfn>user agent</dfn> that implements the
interfaces that it contains.
</p>
<p>
@@ -180,13 +183,29 @@
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>Function</code> interface represents a function in the
- scripting language being used as defined in [[!HTML5]].
+ 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>
+ <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
@@ -201,8 +220,8 @@
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'>
+ <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.
@@ -212,9 +231,9 @@
<section>
<h2><a>BatteryManager</a> Interface</h2>
- <dl title='[NoInterfaceObject]
- interface BatteryManager : EventTarget'
- class='idl'>
+ <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
@@ -247,16 +266,16 @@
full, the implementation is unable to report the battery's level,
or there is no battery attached to the system.
</dd>
- <dt>attribute Function? onchargingchange</dt>
+ <dt>[TreatNonCallableAsNull] attribute Function? onchargingchange</dt>
<dd>
</dd>
- <dt>attribute Function? onchargingtimechange</dt>
+ <dt>[TreatNonCallableAsNull] attribute Function? onchargingtimechange</dt>
<dd>
</dd>
- <dt>attribute Function? ondischargingtimechange</dt>
+ <dt>[TreatNonCallableAsNull] attribute Function? ondischargingtimechange</dt>
<dd>
</dd>
- <dt>attribute Function? onlevelchange</dt>
+ <dt>[TreatNonCallableAsNull] attribute Function? onlevelchange</dt>
<dd>
</dd>
</dl>
@@ -269,48 +288,78 @@
respectively.
</p>
<p>
- When the battery charging state is updated, the <a class="product-ua"
- href="#ua">user agent</a> MUST queue a task which sets the <code>
- charging</code> attribute's value and fires a simple event [[!HTML5]]
- named <code>chargingchange</code> at the <a>BatteryManager</a>
- object.
+ 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 class="product-ua"
- href="#ua">user agent</a> MUST queue a task which sets the <code>
- chargingTime</code> attribute's value and fires a simple event [[!HTML5]]
- named <code>chargingtimechange</code> at the <a>BatteryManager</a>
- object.
+ 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 class="product-ua"
- href="#ua">user agent</a> MUST queue a task which sets the <code>
- dischargingTime</code> attribute's value and fires a simple event [[!HTML5]]
- named <code>dischargingtimechange</code> at the <a>BatteryManager</a>
- object.
+ 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 class="product-ua"
- href="#ua">user agent</a> MUST queue a task which sets the <code>
- level</code> attribute's value and fires a simple event [[!HTML5]]
- named <code>levelchange</code> at the <a>BatteryManager</a>
- object.
+ 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'>
+ <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 sh_javascript'>
+ <div class="example">
+ <pre class="example sh_javascript">
navigator.battery.onlevelchange = function () {
console.log(navigator.battery.level);
};
@@ -320,8 +369,8 @@
Alternatively, the same using the <code>addEventListener()</code>
method:
</p>
- <div class='example'>
- <pre class='example sh_javascript'>
+ <div class="example">
+ <pre class="example sh_javascript">
navigator.battery.addEventListener('levelchange', function () {
console.log(navigator.battery.level);
}, false);
@@ -331,8 +380,8 @@
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'>
+ <div class="example">
+ <pre class="example sh_javascript">
<!DOCTYPE html>
<html>
<head>
@@ -362,7 +411,7 @@
</pre>
</div>
</section>
- <section class='appendix'>
+ <section class="appendix">
<h2>Acknowledgements</h2>
<p>
Big thanks to the Mozilla WebAPI team for their invaluable feedback
Received on Friday, 2 December 2011 09:40:22 UTC