- From: Anssi Kostiainen via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 05 Apr 2011 16:19:14 +0000
- To: public-dap-commits@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 UTC