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

2009/dap/system-info battery-status.html,1.12,1.13

From: Anssi Kostiainen via cvs-syncmail <cvsmail@w3.org>
Date: Thu, 26 May 2011 13:09:33 +0000
To: public-dap-commits@w3.org
Message-Id: <E1QPaJh-00025x-Bv@lionel-hutz.w3.org>
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv8023

Modified Files:
	battery-status.html 
Log Message:
bake in Robin's review comments

Index: battery-status.html
===================================================================
RCS file: /sources/public/2009/dap/system-info/battery-status.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- battery-status.html	9 May 2011 09:50:35 -0000	1.12
+++ battery-status.html	26 May 2011 13:09:31 -0000	1.13
@@ -40,13 +40,30 @@
         border-bottom: 0;
         color: #459900;
       }
+      #event-type-batterystatus {
+        border-collapse: collapse;
+        width: 100%;
+      }
+      #event-type-batterystatus td {
+        border-bottom: 1px solid #DDDDDD;
+      }
+      #event-type-batterystatus th {
+        font-family: initial;
+        text-shadow: 1px 1px 0 #666666;
+        color: white;
+        background-color: #90B8DE;
+        text-align: left;
+        font-weight: normal;
+      }
+      #event-type-batterystatus th, #event-type-batterystatus td {
+        padding: 0 5px 0 5px;
+      }
     </style>
   </head>
   <body>
     <section id='abstract'>
       This specification defines a new DOM event type that provides
-      information about the battery status of the hosting device and
-      associated auxiliary devices.
+      information about the battery status of the hosting device.
     </section>
     
     <section id='sotd'>
@@ -59,32 +76,28 @@
       </p>
     </section>
     
+    <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
+        interfaces that it contains.
+      </p>
+    </section>
+    
     <section>
       <h2><a>BatteryStatusEvent</a> Interface</h2>
       <p>
         This interface defines the <a>batterystatus</a>
         event type.
-        <div class='note'>
-          The inclusion of properties <code>isBattery</code>,
-          <code>isCharging</code>, and <code>timeRemaining</code> is under
-          consideration. The working group is looking for high value use
-          cases for the said properties.
-        </div>
       <dl title='[NoInterfaceObject] interface BatteryStatusEvent : Event'
           class='idl'>
-        <dt>readonly attribute boolean isBattery</dt>
+        <dt>readonly attribute boolean isPlugged</dt>
         <dd>
-          Represents whether the current power source is a
-          battery. If the device is currently powered by a battery,
-          then <code>isBattery</code> MUST be set to <code>true</code>,
+          Represents whether the device is plugged in and its battery is
+          currently charging. If the device is current plugged in and
+          and its battery is being charged or is at its full capacity,
+          then <code>isPluged</code> MUST be set to <code>true</code>,
           otherwise <code>false</code>.
-        </dd>
-        <dt>readonly attribute boolean isCharging</dt>
-        <dd>
-          Represents whether the device's battery, if in use, is
-          currently charging. If the current power source is a battery
-          and it is being charged, then <code>isCharging</code>
-          MUST be set to <code>true</code>, otherwise <code>false</code>.
           </dd>
         <dt>readonly attribute float? level</dt>
         <dd>
@@ -95,18 +108,6 @@
           battery's level, then <code>level</code> MUST be
           set to <code>null</code>.
         </dd>
-        <dt>readonly attribute unsigned long? timeRemaining</dt>
-        <dd>
-          Represents the estimated time remaining in seconds
-          before the battery will be depleted, based upon current
-          power usage. If <code>isCharging</code> is
-          <code>true</code>, this value represents the
-          estimated time remaining in seconds before the battery is
-          depleted, based upon current power usage, if external
-          power were removed. If the implementation is unable to
-          report the estimated time remaining,
-          <code>timeRemaining</code> MUST be set to <code>null</code>.
-        </dd>
         <dt>void initBatteryStatusEvent ()</dt>
         <dd>
             Initializes a <a>BatteryStatusEvent</a> created
@@ -116,66 +117,103 @@
             <dt>DOMString type</dt><dd></dd>
             <dt>boolean bubbles</dt><dd></dd>
             <dt>boolean cancelable</dt><dd></dd>
-            <dt>boolean isBattery</dt><dd></dd>
-            <dt>boolean isCharging</dt><dd></dd>
+            <dt>boolean isPlugged</dt><dd></dd>
             <dt>float? level</dt><dd></dd>
-            <dt>unsigned long? timeRemaining</dt><dd></dd>
           </dl>
         </dd>
       </dl>
       <p>
-        The <code>initBatteryStatusEvent()</code> method MUST initialize the
-        event in a manner analogous to the similarly-named method in 
-        [[!DOM-LEVEL-3-EVENTS]].
-      </p>
-      <p>
-        If a change in the battery status of the hosting device occurs,
-        then the User Agent MUST dispatch a <a>BatteryStatusEvent</a>
-        event on the <code>Window</code> [[!HTML5]] object.
+        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]].
       </p>
       <p>
-        If a change in the battery status of an auxiliary device occurs,
-        and the auxiliary device is exposed on <code>o</code> object, and
-        the <code>o</code> implements the <code>EventTarget</code>
-        [[!DOM-LEVEL-3-EVENTS]] interface, then the User Agent MUST dispatch a
-        <a>BatteryStatusEvent</a> event on the <code>o</code> object.
+        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> and
+        <code>level</code> arguments MUST initialize the attributes with the
+        same names.
       </p>
       <p>
-        The <code>onbatterystatus</code> event handler MUST be supported by
-        <code>Window</code> objects, as an IDL attribute on the
-        <code>Window</code> object. Similarly, as an IDL attribute on the
-        <code>o</code> object, if it fulfills the conditions given in the
-        "change in the battery status of an auxiliary device".
+        If a change in the battery status of the hosting device occurs as follows:
       </p>
+      <ul>
+        <li>
+          <code>isPlugged</code> changes, or
+        </li>
+        <li>
+          <code>level</code> varies by a 1% or more
+        </li>
+      </ul>
       <p>
-        If an event listener is registered with the event type
-        <a>batterystatus</a>, then the User Agent MUST dispatch a
-        <a>BatteryStatusEvent</a> event immediately.
+        Then 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>WorkerGlobalObject</code> [[!WEBWORKERS]] objects.
       </p>
       <p class='note'>
-        Make <em>immediately</em> explicit and align with 
-        [[!DOM-LEVEL-3-EVENTS]].
+        TODO: Conditions for event triggering must be testable.
       </p>
       <p>
-        User Agents SHOULD dispatch a <a>BatteryStatusEvent</a> event when
-        <code>timeRemaining</code> varies by a minute or more.
+        The <code>onbatterystatus</code> event handler MUST be supported by
+        <code>Window</code> and <code>WorkerGlobalObject</code> objects, as an
+        IDL attribute on the <code>Window</code> and
+        <code>WorkerGlobalObject</code> objects respectively.
       </p>
-      <p>
-        User Agents SHOULD dispatch a <a>BatteryStatusEvent</a> event when 
-        <code>isCharging</code> or <code>isBattery</code> changes.
+      <p class='note'>
+        TODO: Define <code>onbatterystatus</code> event handler in WebIDL.
       </p>
       <p>
-        User Agents SHOULD dispatch a <a>BatteryStatusEvent</a> event when
-        <code>level</code> varies by a 1% or more.
+        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 dispatch a <a>BatteryStatusEvent</a> event immediately.
+      </p>
+      <p class='note'>
+        TODO: Make <em>immediately</em> explicit and align with 
+        [[!DOM-LEVEL-3-EVENTS]].
       </p>
         
       <section>
         <h3 id='event-batterystatus'>The <dfn class='event'>batterystatus</dfn>
         Event</h3>
-        <p>
-          User Agents MUST dispatch this event type to indicate a change in
-          the battery status.
-        </p>
+        <table id='event-type-batterystatus'>
+          <tr>
+            <th>Type</th>
+            <td>
+              <code>batterystatus</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>
     
@@ -188,7 +226,7 @@
         By using the <code>addEventListener()</code> method:
       </p>
       <div class='example'>
-        <pre class='sh_javascript'>
+        <pre class='example sh_javascript'>
 window.addEventListener('batterystatus', function (event) {
   console.log(event.level);
 }, true);
@@ -198,7 +236,7 @@
         By assigning a function expression to the <code>onbatterystatus</code> property:
       </p>
       <div class='example'>
-        <pre class='sh_javascript'>
+        <pre class='example sh_javascript'>
 window.onbatterystatus = function (event) {
   console.log(event.level);
 };
@@ -211,7 +249,7 @@
         By using the <code>addEventListener()</code> method:
       </p>
       <div class='example'>
-        <pre class='sh_javascript'>
+        <pre class='example sh_javascript'>
 var handler = function (event) {
   console.log(event.level);
   window.removeEventListener('batterystatus', handler, true);
@@ -224,7 +262,7 @@
         By assigning a function expression to the <code>onbatterystatus</code> property:
       </p>
       <div class='example'>
-        <pre class='sh_javascript'>
+        <pre class='example sh_javascript'>
 window.onbatterystatus = function (event) {
   console.log(event.level);
   window.onbatterystatus = null;
Received on Thursday, 26 May 2011 13:09:34 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 26 May 2011 13:09:35 GMT