W3C home > Mailing lists > Public > public-dap-commits@w3.org > June 2011

2009/dap/system-info battery-status.html,1.29,1.30

From: Anssi Kostiainen via cvs-syncmail <cvsmail@w3.org>
Date: Thu, 30 Jun 2011 09:45:28 +0000
To: public-dap-commits@w3.org
Message-Id: <E1QcDoO-0001Oh-AO@lionel-hutz.w3.org>
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv5357

Modified Files:
	battery-status.html 
Log Message:
remove window.on* and body.on* event handlers; add batterylow and batterycritical event types, rework examples (ACTION-417)

Index: battery-status.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/battery-status.html,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -d -r1.29 -r1.30
--- battery-status.html	29 Jun 2011 05:21:08 -0000	1.29
+++ battery-status.html	30 Jun 2011 09:45:26 -0000	1.30
@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <title>Battery Status Event Specification</title>
+    <title>Battery Status Events Specification</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'>
@@ -35,14 +35,14 @@
         border-bottom: 0;
         color: #459900;
       }
-      #event-type-batterystatus {
+      .event-type-battery {
         border-collapse: collapse;
         width: 100%;
       }
-      #event-type-batterystatus td {
+      .event-type-battery td {
         border-bottom: 1px solid #DDDDDD;
       }
-      #event-type-batterystatus th {
+      .event-type-battery th {
         font-family: initial;
         text-shadow: 1px 1px 0 #666666;
         color: white;
@@ -50,14 +50,14 @@
         text-align: left;
         font-weight: normal;
       }
-      #event-type-batterystatus th, #event-type-batterystatus td {
+      .event-type-battery th, .event-type-battery td {
         padding: 0 5px 0 5px;
       }
     </style>
   </head>
   <body>
     <section id='abstract'>
-      This specification defines a new DOM event type that provides
+      This specification defines new DOM event types that provide
       information about the battery status of the hosting device.
     </section>
     
@@ -74,7 +74,7 @@
     <section class="informative">
       <h2>Introduction</h2>
       <p>
-        The Battery Status Event Specification defines a means for web
+        The Battery Status Events Specification defines a means for web
         developers to programmatically determine the battery status of the
         hosting device and whether the device is plugged in or not. Without
         knowing the battery status of a device, a web developer must design
@@ -87,7 +87,7 @@
         experience.
      </p>
      <p>
-        The Battery Status Event can be used to defer or scale back work when
+        The Battery Status Events can be used to defer or scale back work when
         the device is not plugged in or is low on battery. An archetype of an
         advanced web application, a web-based email client, may check the
         server for new email every few seconds if the device is plugged in,
@@ -117,11 +117,11 @@
               }
             };
 
-            window.onload = function () {
+            window.addEventListener('load', function () {
               var interval = (!mail.interval_current) ? mail.INTERVAL_DEFAULT : mail.interval_current;
               mail.timer = setInterval(function () { mail.check(); }, interval);
               mail.interval_current = interval;
-            };
+            }, false);
           &lt;/script&gt;
         &lt;/head&gt;
         &lt;body&gt;&lt;/body&gt;
@@ -135,8 +135,9 @@
       </p>
       <p>
         Using the <a>BatteryStatusEvent</a> interface, the web application is,
-        for example, able to throttle checking for emails if the device is not
-        plugged in and the battery level is below 10%:
+        for example, able to throttle checking for emails if the device is low
+        on battery and stop checking for emails if the battery is critically
+        low:
       </p>
       <pre class='example sh_javascript'>
         &lt;!DOCTYPE html&gt;
@@ -145,33 +146,43 @@
           &lt;title&gt;Battery-aware Email Client&lt;/title&gt;
           &lt;script&gt;
             var mail = {
-              INTERVAL_LOW_BATTERY: 1000 * 60 * 10,
-              INTERVAL_DEFAULT: 10000,
+              INTERVAL_BATTERY_LOW: 1000 * 60 * 10,
+              INTERVAL_DEFAULT: 1000 * 10,
               interval_current: null,
               timer: 0,
-
+              
               check: function () {
                 console.log('Checking the server for new emails using an interval of ' + 
                             (mail.interval_current/1000) + ' seconds.');
               }
             };
-
-            window.onload = function () {
-              var interval = (!mail.interval_current) ? mail.INTERVAL_DEFAULT : mail.interval_current;
-              mail.timer = setInterval(function () { mail.check(); }, interval);
-              mail.interval_current = interval;
-            };
-
-            window.onbatterystatus = function (battery) {
-              var interval = (!battery.isPlugged &amp;&amp; battery.level &lt; 10) ? 
-                                                    mail.INTERVAL_LOW_BATTERY : mail.INTERVAL_DEFAULT;
-
-              if (interval !== mail.interval_current) {
+            
+            window.addEventListener('load', function () {
+              mail.interval_current = (!mail.interval_current) ? mail.INTERVAL_DEFAULT : mail.interval_current;
+              mail.timer = setInterval(function () { mail.check(); }, mail.interval_current);
+            }, false);
+            
+            window.addEventListener('batterystatus', function (battery) {
+              if (battery.isPlugged &amp;&amp; (mail.interval_current !== mail.INTERVAL_DEFAULT)) {
                 clearTimeout(mail.timer);
-                mail.timer = setInterval(function () { mail.check(); }, interval);
-                mail.interval_current = interval;
+                mail.interval_current = mail.INTERVAL_DEFAULT;
+                mail.timer = setInterval(function () { mail.check(); }, mail.interval_current);
+                console.log('Plugged in, checking the server normally.');
               }
-            };
+            }, false);
+            
+            window.addEventListener('batterylow', function () {
+              clearTimeout(mail.timer);
+              mail.interval_current = mail.INTERVAL_BATTERY_LOW;
+              mail.timer = setInterval(function () { mail.check(); }, mail.interval_current);
+              console.log('Low battery, checking the server less frequently.');
+            }, false);
+            
+            window.addEventListener('batterycritical', function () {
+              clearTimeout(mail.timer);
+              mail.interval_current = null;
+              console.log('Critically low battery, stopped checking the server.');
+            }, false);
           &lt;/script&gt;
         &lt;/head&gt;
         &lt;body&gt;&lt;/body&gt;
@@ -188,34 +199,10 @@
     </section>
     
     <section>
-      <h2><a>Battery</a> Interface</h2>
-      <p>
-        The <a>Battery</a> interface is exposed on the
-        <code>Window</code> and <code>WorkerGlobalScope</code> objects.
-      </p>
-      <p>
-        The <code>body</code> element exposes as an event handler content
-        attribute the <code>onbatterystatus</code> event handler of the
-        <code>Window</code> object. It also mirrors its event handler IDL
-        attribute.
-      </p>
-      <div class='idl' title='Window implements Battery'></div>
-      <div class='idl' title='WorkerGlobalScope implements Battery'></div>
-      <dl title='[NoInterfaceObject] interface Battery'
-          class='idl'>
-        <dt>attribute Function onbatterystatus</dt>
-        <dd>
-          The event handler that MUST be supported, as an IDL attribute, by
-          objects implementing the <code>Battery</code> interface.
-        </dd>
-      </dl>
-    </section>
-    
-    <section>
       <h2><a>BatteryStatusEvent</a> Interface</h2>
       <p>
-        This interface defines the <a>batterystatus</a>
-        event type.
+        This interface defines the <a>batterystatus</a>, <a>batterylow</a> and
+        <a>batterycritical</a> event types.
       <dl title='interface BatteryStatusEvent : Event'
           class='idl'>
         <dt>readonly attribute boolean isPlugged</dt>
@@ -249,10 +236,10 @@
         </dd>
       </dl>
       <p>
-        The <a>batterystatus</a> event type 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]].
+        The <a>batterystatus</a>, <a>batterylow</a> and <a>batterycritical</a>
+        event type 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
@@ -261,32 +248,32 @@
         <code>level</code> arguments MUST initialize the attributes with the
         same names.
       </p>
-      <p>
-        The <a class="product-ua" href="#ua">user agent</a> MUST dispatch a
-        <a>BatteryStatusEvent</a> event 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:
-      </p>
-      <ul>
-        <li>
-          <code>isPlugged</code> changes its value, or
-        </li>
-        <li>
-          <code>level</code> changes by at least 1%
-        </li>
-      </ul>
-      <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>
       
       <section>
         <h3 id='event-batterystatus'>The <dfn class='event'>batterystatus</dfn>
         event</h3>
-        <table id='event-type-batterystatus'>
+        <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:
+        </p>
+        <ul>
+          <li>
+            <code>isPlugged</code> changes its value, or
+          </li>
+          <li>
+            <code>level</code> changes by at least 1%
+          </li>
+        </ul>
+        <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>
             <td>
@@ -325,15 +312,128 @@
           </tr>
         </table>
       </section>
+
+      <section>
+        <h3 id='event-batterylow'>The <dfn class='event'>batterylow</dfn>
+        event</h3>
+        <p>
+          The <a class="product-ua" href="#ua">user agent</a> MUST dispatch
+          this event type 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:
+        </p>
+        <ul>
+          <li>
+            the low battery condition is reached
+          </li>
+        </ul>
+        <p>
+          The definition of a low battery condition is left to the
+          implementation.
+        </p>
+        <table class='event-type-battery'>
+          <tr>
+            <th>Type</th>
+            <td>
+              <code>batterylow</code>
+            </td>
+          </tr>
+          <tr>
+            <th>Interface</th>
+            <td>
+              <a>BatteryStatusEvent</a> if generated by the user agent,
+              <code>Event</code> otherwise.
+            </td>
+          </tr>
+          <tr>
+            <th>Sync / Async</th>
+            <td>Async</td></tr>
+          <tr>
+            <th>Bubbles</th>
+            <td>No</td>
+          </tr>
+          <tr>
+            <th>Target</th>
+            <td><code>defaultView</code></td>
+          </tr>
+          <tr>
+            <th>Cancelable</th>
+            <td>No</td>
+          </tr>
+          <tr>
+            <th>Default action</th>
+            <td>none</td>
+          </tr>
+          <tr>
+            <th>Context info</th>
+            <td><code>Event.target: defaultView</code></td>
+          </tr>
+        </table>
+      </section>
+
+      <section>
+        <h3 id='event-batterycritical'>The <dfn class='event'>batterycritical</dfn>
+        event</h3>
+        <p>
+          The <a class="product-ua" href="#ua">user agent</a> MUST dispatch
+          this event type 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:
+        </p>
+        <ul>
+          <li>
+            the critically low battery condition is reached
+          </li>
+        </ul>
+        <p>
+          The definition of a critically low battery condition is left to the
+          implementation.
+        </p>
+        <table class='event-type-battery'>
+          <tr>
+            <th>Type</th>
+            <td>
+              <code>batterycritical</code>
+            </td>
+          </tr>
+          <tr>
+            <th>Interface</th>
+            <td>
+              <a>BatteryStatusEvent</a> if generated by the user agent,
+              <code>Event</code> otherwise.
+            </td>
+          </tr>
+          <tr>
+            <th>Sync / Async</th>
+            <td>Async</td></tr>
+          <tr>
+            <th>Bubbles</th>
+            <td>No</td>
+          </tr>
+          <tr>
+            <th>Target</th>
+            <td><code>defaultView</code></td>
+          </tr>
+          <tr>
+            <th>Cancelable</th>
+            <td>No</td>
+          </tr>
+          <tr>
+            <th>Default action</th>
+            <td>none</td>
+          </tr>
+          <tr>
+            <th>Context info</th>
+            <td><code>Event.target: defaultView</code></td>
+          </tr>
+        </table>
+      </section>
     </section>
     
     <section class='informative'>
       <h2>Examples</h2>
       <p>
-        Register to receive repeated <a>BatteryStatusEvent</a> events.
-      </p>
-      <p>
-        By using the <code>addEventListener()</code> method:
+        Register to receive repeated <a>BatteryStatusEvent</a> events:
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
@@ -343,47 +443,43 @@
         </pre>
       </div>
       <p>
-        By assigning a function expression to the <code>onbatterystatus</code> property:
+        Register to receive a single <a>BatteryStatusEvent</a> event:
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
-          window.onbatterystatus = function (event) {
+          var handler = function (event) {
             console.log(event.level);
+            window.removeEventListener('batterystatus', handler, true);
           };
+
+          window.addEventListener('batterystatus', handler, true);
         </pre>
       </div>
       <p>
-        Register to receive a single <a>BatteryStatusEvent</a> event.
-      </p>
-      <p>
-        By using the <code>addEventListener()</code> method:
+        Register to receive a <a>BatteryStatusEvent</a> event when the low
+        battery condition is reached:
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
-          var handler = function (event) {
-            console.log(event.level);
-            window.removeEventListener('batterystatus', handler, true);
-          };
-
-          window.addEventListener('batterystatus', handler, true);
+          window.addEventListener('batterylow', function () {
+            console.log('The battery is low.');
+          }, true);
         </pre>
       </div>
       <p>
-        By assigning a function expression to the <code>onbatterystatus</code> property:
+        Register to receive a <a>BatteryStatusEvent</a> event when the 
+        critically low battery condition is reached:
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
-          window.onbatterystatus = function (event) {
-            console.log(event.level);
-            window.onbatterystatus = null;
-          };
+          window.addEventListener('batterycritical', function () {
+            console.log('The battery is critically low.');
+          }, true);
         </pre>
       </div>
       <p>
         The following example updates the indicators to show whether or not
-        the device is plugged in and what is the current battery level using
-        the event handler content attribute <code>onbatterystatus</code>
-        exposed on the <code>body</code> element.
+        the device is plugged in and what is the current battery level:
       </p>
       <div class='example'>
         <pre class='example sh_javascript'>
@@ -392,14 +488,13 @@
           &lt;head&gt;
             &lt;title&gt;Battery Status Event Example&lt;/title&gt;
             &lt;script&gt;
-              function update(battery) {
-                document.querySelector('#plugged').textContent =
-                  battery.isPlugged ? 'plugged' : 'not plugged';
+              window.addEventListener('batterystatus', function (battery) {
+                document.querySelector('#plugged').textContent = battery.isPlugged ? 'plugged' : 'not plugged';
                 document.querySelector('#level').textContent = battery.level;
-              }
+              }, false);
             &lt;/script&gt;
           &lt;/head&gt;
-          &lt;body onbatterystatus="update(this)"&gt;
+          &lt;body&gt;
             &lt;div id="plugged"&gt;(plugged state unknown)&lt;/div&gt;
             &lt;div id="level"&gt;(battery level unknown)&lt;/div&gt;
           &lt;/body&gt;
Received on Thursday, 30 June 2011 09:45:34 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 30 June 2011 09:45:35 GMT