- From: Anssi Kostiainen via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 07 Sep 2011 11:18:13 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv15200
Modified Files:
battery-status.html
Log Message:
proposed alternative design
Index: battery-status.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/battery-status.html,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -d -r1.40 -r1.41
--- battery-status.html 6 Sep 2011 11:12:21 -0000 1.40
+++ battery-status.html 7 Sep 2011 11:18:11 -0000 1.41
@@ -25,6 +25,22 @@
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
};
</script>
+ <script class='remove'>
+ // a monkey patch to add BatteryStatusEventInit dictionary
+ setTimeout(function () {
+ var batteryStatusEventInit =
+ '\n<span class="idlInterface" id="idl-def-BatteryStatusEventInit">' +
+ 'dictionary <span class="idlInterfaceID">BatteryStatusEventInit</span>' +
+ ' : <span class="idlSuperclass"><a>EventInit</a></span> {\n' +
+ ' <span class="idlAttrType"><a>boolean</a></span> isPlugged;\n' +
+ ' <span class="idlAttrType"><a>float?</a></span> level;\n' +
+ ' <span class="idlAttrType"><a>DOMString?</a></span> status;\n' +
+ '};</span></pre>';
+
+ var batteryStatusEvent = document.querySelector('#batterystatusevent-interface > pre.idl');
+ batteryStatusEvent.innerHTML += batteryStatusEventInit;
+ }, 100);
+ </script>
<style type='text/css'>
.event {
font-family: monospace;
@@ -139,8 +155,8 @@
This is an example of poor resource management.
</p>
<p>
- Using the <a>batterylow</a>, <a>batterycritical</a> and
- <a>batteryok</a> events, the web application is, for example, able to
+ 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:
@@ -174,17 +190,19 @@
mail.setTimer(!mail.interval ? mail.INTERVAL_DEFAULT : mail.interval);
}, false);
- window.addEventListener('batterylow', function () {
+ var battery = new BatteryStatusEventSource();
+
+ battery.addEventListener('batterylow', function () {
mail.setTimer(mail.INTERVAL_BATTERY_LOW);
console.log('Low battery, checking the server less frequently.');
}, false);
- window.addEventListener('batterycritical', function () {
+ battery.addEventListener('batterycritical', function () {
mail.setTimer(null);
console.log('Critically low battery, stopped checking the server.');
}, false);
- window.addEventListener('batteryok', function () {
+ battery.addEventListener('batteryok', function () {
mail.setTimer(mail.INTERVAL_DEFAULT);
console.log('Battery ok, checking the server normally.');
}, false);
@@ -204,11 +222,73 @@
</section>
<section>
+ <h2><a>BatteryStatusEventSource</a> Interface</h2>
+ <dl title='[Constructor]
+ interface BatteryStatusEventSource : EventTarget'
+ class='idl'>
+ <dt>attribute Function? onbatterystatus</dt>
+ <dd>
+ </dd>
+ <dt>attribute Function? onbatterylow</dt>
+ <dd>
+ </dd>
+ <dt>attribute Function? onbatterycritical</dt>
+ <dd>
+ </dd>
+ <dt>attribute Function? onbatteryok</dt>
+ <dd>
+ </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.
- <dl title='interface BatteryStatusEvent : Event'
+ </p>
+
+ <dl title='[Constructor(DOMString type, optional BatteryStatusEventInit eventInitDict)]
+ interface BatteryStatusEvent : Event'
class='idl'>
<dt>readonly attribute boolean isPlugged</dt>
<dd>
@@ -239,58 +319,37 @@
report the battery's level, then status MUST be set to
<code>null</code>.
</dd>
- <dt>void initBatteryStatusEvent ()</dt>
- <dd>
- Initializes a <a>BatteryStatusEvent</a> created
- through the <code>DocumentEvent</code> interface
- [[!DOM-LEVEL-3-EVENTS]].
- <dl class='parameters'>
- <dt>DOMString type</dt>
- <dd>
- The type of the event, which is one of <a>batterystatus</a>, <a>batterylow</a>,
- <a>batterycritical</a> or <a>batteryok</a>.
- </dd>
- <dt>boolean bubbles</dt>
- <dd>Whether the event will bubble, as defined in [[!DOM-LEVEL-3-EVENTS]].</dd>
- <dt>boolean cancelable</dt>
- <dd>Whether the event will be cancelable, as defined in [[!DOM-LEVEL-3-EVENTS]].</dd>
- <dt>boolean isPlugged</dt>
- <dd>Whether the device is plugged in or not.</dd>
- <dt>float? level</dt>
- <dd>
- The level of the battery, between 0 and 100. Values inferior to 0 MUST cause <code>level</code> to be set to 0;
- values superior to 100 MUST cause <code>level</code> to be set to 100.
- </dd>
- <dt>DOMString? status</dt>
- <dd>
- One of <code>"critical"</code>, <code>"low"</code>, <code>"ok"</code> or <code>null</code>.
- </dd>
- </dl>
- </dd>
</dl>
- <p>
- The <a>batterystatus</a>, <a>batterylow</a>, <a>batterycritical</a>
- and <a>batteryok</a> event types MUST be available when the
- script's global object [[!HTML5]] is either a <code>Window</code>
- object or an object implementing the <code>WorkerUtils</code>
- interface [[!WEBWORKERS]].
- </p>
- <p>
- The <code>initBatteryStatusEvent()</code> method MUST initialize the
- event in a manner analogous to the <code>initEvent()</code> method in
- [[!DOM-LEVEL-3-EVENTS]]. The <code>isPlugged</code>, <code>level</code>
- and <code>status</code> arguments MUST initialize the attributes with
- the same names.
- </p>
-
+ <section>
+ <h2>Constructor</h2>
+ <p>
+ <code>BatteryStatusEvent(<var>type</var>, <var>eventInitDict</var>)
+ </code> is an event constructor, as defined in [[!DOMCORE]].
+ </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 [[!DOMCORE]], 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 on the <code>Window</code> [[!HTML5]] and
- <code>WorkerGlobalScope</code> [[!WEBWORKERS]] objects when a change
- in the battery status of the hosting device occurs as follows:
+ 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>
@@ -306,19 +365,12 @@
<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
+ 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>
- <p>
- When an event listener is registered with the event type
- <a>batterystatus</a>, then the <a class="product-ua" href="#ua">user
- agent</a> MUST retrieve the relevant information and dispatch a
- <a>BatteryStatusEvent</a> event asynchronously as defined in
- [[!DOM-LEVEL-3-EVENTS]].
- </p>
<table class='event-type-battery'>
<tr>
<th>Type</th>
@@ -338,7 +390,7 @@
<td>Async</td></tr>
<tr>
<th>Bubbles</th>
- <td>No</td>
+ <td>Yes</td>
</tr>
<tr>
<th>Target</th>
@@ -346,7 +398,7 @@
</tr>
<tr>
<th>Cancelable</th>
- <td>No</td>
+ <td>Yes</td>
</tr>
<tr>
<th>Default action</th>
@@ -364,9 +416,9 @@
event</h3>
<p>
The <a class="product-ua" href="#ua">user agent</a> MUST dispatch
- this event type on the <code>Window</code> [[!HTML5]] and
- <code>WorkerGlobalScope</code> [[!WEBWORKERS]] objects when a change
- in the battery status of the hosting device occurs as follows:
+ 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>
@@ -403,7 +455,7 @@
<td>Async</td></tr>
<tr>
<th>Bubbles</th>
- <td>No</td>
+ <td>Yes</td>
</tr>
<tr>
<th>Target</th>
@@ -411,7 +463,7 @@
</tr>
<tr>
<th>Cancelable</th>
- <td>No</td>
+ <td>Yes</td>
</tr>
<tr>
<th>Default action</th>
@@ -429,9 +481,9 @@
event</h3>
<p>
The <a class="product-ua" href="#ua">user agent</a> MUST dispatch
- this event type on the <code>Window</code> [[!HTML5]] and
- <code>WorkerGlobalScope</code> [[!WEBWORKERS]] objects when a change
- in the battery status of the hosting device occurs as follows:
+ 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>
@@ -470,7 +522,7 @@
<td>Async</td></tr>
<tr>
<th>Bubbles</th>
- <td>No</td>
+ <td>Yes</td>
</tr>
<tr>
<th>Target</th>
@@ -478,7 +530,7 @@
</tr>
<tr>
<th>Cancelable</th>
- <td>No</td>
+ <td>Yes</td>
</tr>
<tr>
<th>Default action</th>
@@ -496,9 +548,9 @@
event</h3>
<p>
The <a class="product-ua" href="#ua">user agent</a> MUST dispatch
- this event type on the <code>Window</code> [[!HTML5]] and
- <code>WorkerGlobalScope</code> [[!WEBWORKERS]] objects when a change
- in the battery status of the hosting device occurs as follows:
+ 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>
@@ -529,7 +581,7 @@
<td>Async</td></tr>
<tr>
<th>Bubbles</th>
- <td>No</td>
+ <td>Yes</td>
</tr>
<tr>
<th>Target</th>
@@ -537,7 +589,7 @@
</tr>
<tr>
<th>Cancelable</th>
- <td>No</td>
+ <td>Yes</td>
</tr>
<tr>
<th>Default action</th>
@@ -558,9 +610,11 @@
</p>
<div class='example'>
<pre class='example sh_javascript'>
- window.addEventListener('batterystatus', function (event) {
+ var battery = new BatteryStatusEventSource();
+
+ battery.addEventListener('batterystatus', function (event) {
console.log(event.level);
- }, true);
+ }, false);
</pre>
</div>
<p>
@@ -568,46 +622,53 @@
</p>
<div class='example'>
<pre class='example sh_javascript'>
+ var battery = new BatteryStatusEventSource();
+
var handler = function (event) {
console.log(event.level);
- window.removeEventListener('batterystatus', handler, true);
+ battery.removeEventListener('batterystatus', handler, false);
};
- window.addEventListener('batterystatus', handler, true);
+ battery.addEventListener('batterystatus', handler, false);
</pre>
</div>
<p>
- Register to receive a <a>BatteryStatusEvent</a> event when the low
- battery condition is reached:
+ Register to receive a <a>BatteryStatusEvent</a> of type
+ <a>batterylow</a>:
</p>
<div class='example'>
<pre class='example sh_javascript'>
- window.addEventListener('batterylow', function () {
+ var battery = new BatteryStatusEventSource();
+
+ battery.addEventListener('batterylow', function () {
console.log('The battery is low.');
- }, true);
+ }, false);
</pre>
</div>
<p>
- Register to receive a <a>BatteryStatusEvent</a> event when the
- critically low battery condition is reached:
+ Register to receive a <a>BatteryStatusEvent</a> of type
+ <a>batterycritical</a>:
</p>
<div class='example'>
<pre class='example sh_javascript'>
- window.addEventListener('batterycritical', function () {
+ var battery = new BatteryStatusEventSource();
+
+ battery.addEventListener('batterycritical', function () {
console.log('The battery is critically low.');
- }, true);
+ }, false);
</pre>
</div>
<p>
- Register to receive a <a>BatteryStatusEvent</a> event when the
- battery is plugged in, and the battery is being charged or is
- at its full capacity:
+ Register to receive a <a>BatteryStatusEvent</a> of type
+ <a>batteryok</a>:
</p>
<div class='example'>
<pre class='example sh_javascript'>
- window.addEventListener('batteryok', function () {
+ var battery = new BatteryStatusEventSource();
+
+ battery.addEventListener('batteryok', function () {
console.log('The battery is ok.');
- }, true);
+ }, false);
</pre>
</div>
<p>
@@ -622,10 +683,12 @@
<head>
<title>Battery Status Event Example</title>
<script>
- window.addEventListener('batterystatus', function (battery) {
- document.querySelector('#plugged').textContent = battery.isPlugged ? 'plugged' : 'not plugged';
- document.querySelector('#level').textContent = battery.level;
- document.querySelector('#status').textContent = battery.status;
+ 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);
</script>
</head>
@@ -648,9 +711,9 @@
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 who have sent in substantial feedback
- and comments, and made the Web a better place for everyone while doing
- so.
+ 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.
</p>
</section>
</body>
Received on Wednesday, 7 September 2011 11:18:20 UTC