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

2009/dap/system-info battery-status.html,NONE,1.1

From: Anssi Kostiainen via cvs-syncmail <cvsmail@w3.org>
Date: Tue, 05 Apr 2011 16:19:14 +0000
To: public-dap-commits@w3.org
Message-Id: <E1Q78yI-000139-5X@lionel-hutz.w3.org>
Update of /sources/public/2009/dap/system-info
In directory hutz:/tmp/cvs-serv4021

Added Files:
	battery-status.html 
Log Message:
Initial version

--- NEW FILE: battery-status.html ---
<!DOCTYPE html>
<html>
  <head>
    <title>Battery Status Event Specification</title>
    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
    <!-- 
      === NOTA BENE ===
      For the three scripts below, if your spec resides on dev.w3 you can check them
      out in the same tree and use relative links so that they'll work offline,
     -->
    <script src='../ReSpec.js/js/respec.js' class='remove'></script>
    <script class='remove'>
      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "ED",
          
          // the specification's short name, as in http://www.w3.org/TR/short-name/
          shortName:            "battery-status",

          // if your specification has a subtitle that goes below the main
          // formal title, define it here
          // subtitle   :  "an excellent document",

          // if you wish the publication date to be other than today, set this
          // publishDate:  "2009-08-06",

          // if the specification's copyright date is a range of years, specify
          // the start date here:
          // copyrightStart: "2005"

          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
          // and its maturity status
          // previousPublishDate:  "1977-03-15",
          // previousMaturity:  "WD",

          // if there a publicly available Editor's Draft, this is the link
          edDraftURI:           "http://dev.w3.org/2009/dap/system-info/battery-status.html",

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2009-08-05",

          // if you want to have extra CSS, append them to this list
          // it is recommended that the respec.css stylesheet be kept
          extraCSS:             ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],

          // editors, add as many as you like
          // only "name" is required
          editors:  [
              { name: "Anssi Kostiainen", company: "Nokia" }
          ],

          // authors, add as many as you like. 
          // This is optional, uncomment if you have authors as well as editors.
          // only "name" is required. Same format as editors.

          //authors:  [
          //    { name: "Your Name", url: "http://example.org/",
          //      company: "Your Company", companyURL: "http://example.com/" },
          //],
          
          // name of the WG
          wg:           "Device APIs and Policy Working Group",
          
          // URI of the public WG page
          wgURI:        "http://www.w3.org/2009/dap/",
          
          // name (with the @w3c.org) of the public mailing to which comments are due
          wgPublicList: "public-device-apis",
          
          // URI of the patent status for this WG, for Rec-track documents
          // !!!! IMPORTANT !!!!
          // This is important for Rec-track documents, do not copy a patent URI from a random
          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
          // Team Contact.
          wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/43696/status",
      };
    </script>
    <style>
      .event {
        font-family: monospace;
        color: #459900;
      }
      
      pre.idl {
        white-space: pre-wrap;
      }
    </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.
    </section>
    
    <section>
      <h2><a>BatteryStatusEvent</a> Interface</h2>
      <p>
        This interface defines the <a><code>batterystatus</code></a>
        event type.
      <dl title='[NoInterfaceObject] interface BatteryStatusEvent : Event'
          class='idl'>
        <dt>readonly attribute boolean isBattery</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>,
          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>
          Represents how much of the internal power source remains,
          scaled from 0 to 100. A value of 0 indicates that the
          system's battery is depleted, i.e. it is about to be
          suspended. If the implementation is unable to report
          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
            through the <code>DocumentEvent</code> interface 
            [[!DOM-LEVEL-3-EVENTS]].
          <dl class='parameters'>
            <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>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> object.
      </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> interface,
        then the User Agent MUST dispatch a <a>BatteryStatusEvent</a> event on
        the <code>o</code> object.
      </p>
      <p>
        If an event listener is registered with the event type
        <code>batterystatus</code>, then the User Agent MUST dispatch a 
        <a>BatteryStatusEvent</a> event immediately.
      </p>
      <p class='note'>
        Make <em>immediately</em> explicit and align with 
        [[!DOM-LEVEL-3-EVENTS]].
      </p>
      <p>
        User Agents SHOULD dispatch a <a>BatteryStatusEvent</a> event when
        <code>timeRemaining</code> varies by a minute or more.
      </p>
      <p>
        User Agents SHOULD dispatch a <a>BatteryStatusEvent</a> event when 
        <code>isCharging</code> or <code>isBattery</code> changes.
      </p>
      <p>
        User Agents SHOULD dispatch a <a>BatteryStatusEvent</a> event when
        <code>level</code> varies by a 1% or more.
      </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>
      </section>
    </section>
    
    <section class='informative'>
      <h2>Examples</h2>
      <p>
        Register to receive repeated <a>BatteryStatusEvent</a> events:
      </p>
      <div class='example'>
        <pre class='sh_javascript'>
window.addEventListener('batterystatus', function (event) {
  console.log(event.level);
}, true);
        </pre>
      </div>
      <p>
        Register to receive a single <a>BatteryStatusEvent</a> event:
      </p>
      <div class='example'>
        <pre class='sh_javascript'>
function handler(event) {
  console.log(event.level);
}

window.addEventListener('batterystatus', handler, true);
window.removeEventListener('batterystatus', handler, true);
        </pre>
        <p class='note'>
          The event may be dispatched multiple times in the above example.
        </p>
      </div>
    </section>
    
    <section class='appendix'>
      <h2>Acknowledgements</h2>
      <p>
        Many thanks to the people behind the System Information API and Device
        Orientation Event Specification for inspiration. 
      </p>
    </section>
  </body>
</html>
Received on Tuesday, 5 April 2011 16:19:16 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Tuesday, 5 April 2011 16:19:16 GMT