- From: Robin Berjon via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 20 Apr 2011 16:38:58 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/system-info/battery-status
In directory hutz:/tmp/cvs-serv10230/battery-status
Added Files:
FPWD.html
Log Message:
FPWD
--- NEW FILE: FPWD.html ---
<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'>
<html lang="en" dir="ltr">
<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,
-->
<style>
.event {
font-family: monospace;
color: #459900;
}
a.internalDFN:link, a.internalDFN:visited {
font-family: monospace;
border-bottom: 0;
color: #459900;
}
</style>
<style type="text/css">
/*****************************************************************
* ReSpec CSS
* Robin Berjon (robin at berjon dot com)
* v0.05 - 2009-07-31
*****************************************************************/
/* --- INLINES --- */
em.rfc2119 {
text-transform: lowercase;
font-variant: small-caps;
font-style: normal;
color: #900;
}
h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
border: none;
}
dfn {
font-weight: bold;
}
a.internalDFN {
color: inherit;
border-bottom: 1px solid #99c;
text-decoration: none;
}
a.externalDFN {
color: inherit;
border-bottom: medium dotted #ccc;
text-decoration: none;
}
a.bibref {
text-decoration: none;
}
code {
color: #ff4500;
}
/* --- WEB IDL --- */
pre.idl {
border-top: 1px solid #90b8de;
border-bottom: 1px solid #90b8de;
padding: 1em;
line-height: 120%;
}
pre.idl::before {
content: "WebIDL";
display: block;
width: 150px;
background: #90b8de;
color: #fff;
font-family: initial;
padding: 3px;
font-weight: bold;
margin: -1em 0 1em -1em;
}
.idlType {
color: #ff4500;
font-weight: bold;
text-decoration: none;
}
/*.idlModule*/
/*.idlModuleID*/
/*.idlInterface*/
.idlInterfaceID {
font-weight: bold;
color: #005a9c;
}
.idlSuperclass {
font-style: italic;
color: #005a9c;
}
/*.idlAttribute*/
.idlAttrType, .idlFieldType {
color: #005a9c;
}
.idlAttrName, .idlFieldName {
color: #ff4500;
}
.idlAttrName a, .idlFieldName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlMethod*/
.idlMethType {
color: #005a9c;
}
.idlMethName {
color: #ff4500;
}
.idlMethName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlParam*/
.idlParamType {
color: #005a9c;
}
.idlParamName {
font-style: italic;
}
.extAttr {
color: #666;
}
/*.idlConst*/
.idlConstType {
color: #005a9c;
}
.idlConstName {
color: #ff4500;
}
.idlConstName a {
color: #ff4500;
border-bottom: 1px dotted #ff4500;
text-decoration: none;
}
/*.idlException*/
.idlExceptionID {
font-weight: bold;
color: #c00;
}
.idlTypedefID, .idlTypedefType {
color: #005a9c;
}
.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
color: #c00;
font-weight: normal;
}
.excName a {
font-family: monospace;
}
.idlRaises a.idlType, .excName a.idlType {
border-bottom: 1px dotted #c00;
}
.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
width: 45px;
text-align: center;
}
.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
.idlImplements a {
font-weight: bold;
}
dl.attributes, dl.methods, dl.constants, dl.fields {
margin-left: 2em;
}
.attributes dt, .methods dt, .constants dt, .fields dt {
font-weight: normal;
}
.attributes dt code, .methods dt code, .constants dt code, .fields dt code {
font-weight: bold;
color: #000;
font-family: monospace;
}
.attributes dt code, .fields dt code {
background: #ffffd2;
}
.attributes dt .idlAttrType code, .fields dt .idlFieldType code {
color: #005a9c;
background: transparent;
font-family: inherit;
font-weight: normal;
font-style: italic;
}
.methods dt code {
background: #d9e6f8;
}
.constants dt code {
background: #ddffd2;
}
.attributes dd, .methods dd, .constants dd, .fields dd {
margin-bottom: 1em;
}
table.parameters, table.exceptions {
border-spacing: 0;
border-collapse: collapse;
margin: 0.5em 0;
width: 100%;
}
table.parameters { border-bottom: 1px solid #90b8de; }
table.exceptions { border-bottom: 1px solid #deb890; }
.parameters th, .exceptions th {
color: #fff;
padding: 3px 5px;
text-align: left;
font-family: initial;
font-weight: normal;
text-shadow: #666 1px 1px 0;
}
.parameters th { background: #90b8de; }
.exceptions th { background: #deb890; }
.parameters td, .exceptions td {
padding: 3px 10px;
border-top: 1px solid #ddd;
vertical-align: top;
}
.parameters tr:first-child td, .exceptions tr:first-child td {
border-top: none;
}
.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
width: 100px;
}
.parameters td.prmType {
width: 120px;
}
table.exceptions table {
border-spacing: 0;
border-collapse: collapse;
width: 100%;
}
/* --- TOC --- */
.toc a {
text-decoration: none;
}
a .secno {
color: #000;
}
/* --- TABLE --- */
table.simple {
border-spacing: 0;
border-collapse: collapse;
border-bottom: 3px solid #005a9c;
}
.simple th {
background: #005a9c;
color: #fff;
padding: 3px 5px;
text-align: left;
}
.simple th[scope="row"] {
background: inherit;
color: inherit;
border-top: 1px solid #ddd;
}
.simple td {
padding: 3px 10px;
border-top: 1px solid #ddd;
}
.simple tr:nth-child(even) {
background: #f0f6ff;
}
/* --- DL --- */
.section dd > p:first-child {
margin-top: 0;
}
.section dd > p:last-child {
margin-bottom: 0;
}
.section dd {
margin-bottom: 1em;
}
.section dl.attrs dd, .section dl.eldef dd {
margin-bottom: 0;
}
/* --- EXAMPLES --- */
pre.example {
border-top: 1px solid #ff4500;
border-bottom: 1px solid #ff4500;
padding: 1em;
margin-top: 1em;
}
pre.example::before {
content: "Example";
display: block;
width: 150px;
background: #ff4500;
color: #fff;
font-family: initial;
padding: 3px;
font-weight: bold;
margin: -1em 0 1em -1em;
}
/* --- EDITORIAL NOTES --- */
.issue {
padding: 1em;
margin: 1em 0em 0em;
border: 1px solid #f00;
background: #ffc;
}
.issue::before {
content: "Issue";
display: block;
width: 150px;
margin: -1.5em 0 0.5em 0;
font-weight: bold;
border: 1px solid #f00;
background: #fff;
padding: 3px 1em;
}
.note {
margin: 1em 0em 0em;
padding: 1em;
border: 2px solid #cff6d9;
background: #e2fff0;
}
.note::before {
content: "Note";
display: block;
width: 150px;
margin: -1.5em 0 0.5em 0;
font-weight: bold;
border: 1px solid #cff6d9;
background: #fff;
padding: 3px 1em;
}
/* --- Best Practices --- */
div.practice {
border: solid #bebebe 1px;
margin: 2em 1em 1em 2em;
}
span.practicelab {
margin: 1.5em 0.5em 1em 1em;
font-weight: bold;
font-style: italic;
}
span.practicelab { background: #dfffff; }
span.practicelab {
position: relative;
padding: 0 0.5em;
top: -1.5em;
}
p.practicedesc {
margin: 1.5em 0.5em 1em 1em;
}
@media screen {
p.practicedesc {
position: relative;
top: -2em;
padding: 0;
margin: 1.5em 0.5em -1em 1em;
}
/* --- SYNTAX HIGHLIGHTING --- */
pre.sh_sourceCode {
background-color: white;
color: black;
font-style: normal;
font-weight: normal;
}
pre.sh_sourceCode .sh_keyword { color: #005a9c; font-weight: bold; } /* language keywords */
pre.sh_sourceCode .sh_type { color: #666; } /* basic types */
pre.sh_sourceCode .sh_usertype { color: teal; } /* user defined types */
pre.sh_sourceCode .sh_string { color: red; font-family: monospace; } /* strings and chars */
pre.sh_sourceCode .sh_regexp { color: orange; font-family: monospace; } /* regular expressions */
pre.sh_sourceCode .sh_specialchar { color: #ffc0cb; font-family: monospace; } /* e.g., \n, \t, \\ */
pre.sh_sourceCode .sh_comment { color: #A52A2A; font-style: italic; } /* comments */
pre.sh_sourceCode .sh_number { color: purple; } /* literal numbers */
pre.sh_sourceCode .sh_preproc { color: #00008B; font-weight: bold; } /* e.g., #include, import */
pre.sh_sourceCode .sh_symbol { color: blue; } /* e.g., *, + */
pre.sh_sourceCode .sh_function { color: black; font-weight: bold; } /* function calls and declarations */
pre.sh_sourceCode .sh_cbracket { color: red; } /* block brackets (e.g., {, }) */
pre.sh_sourceCode .sh_todo { font-weight: bold; background-color: #00FFFF; } /* TODO and FIXME */
/* Predefined variables and functions (for instance glsl) */
pre.sh_sourceCode .sh_predef_var { color: #00008B; }
pre.sh_sourceCode .sh_predef_func { color: #00008B; font-weight: bold; }
/* for OOP */
pre.sh_sourceCode .sh_classname { color: teal; }
/* line numbers (not yet implemented) */
pre.sh_sourceCode .sh_linenum { display: none; }
/* Internet related */
pre.sh_sourceCode .sh_url { color: blue; text-decoration: underline; font-family: monospace; }
/* for ChangeLog and Log files */
pre.sh_sourceCode .sh_date { color: blue; font-weight: bold; }
pre.sh_sourceCode .sh_time, pre.sh_sourceCode .sh_file { color: #00008B; font-weight: bold; }
pre.sh_sourceCode .sh_ip, pre.sh_sourceCode .sh_name { color: #006400; }
/* for Prolog, Perl... */
pre.sh_sourceCode .sh_variable { color: #006400; }
/* for LaTeX */
pre.sh_sourceCode .sh_italics { color: #006400; font-style: italic; }
pre.sh_sourceCode .sh_bold { color: #006400; font-weight: bold; }
pre.sh_sourceCode .sh_underline { color: #006400; text-decoration: underline; }
pre.sh_sourceCode .sh_fixed { color: green; font-family: monospace; }
pre.sh_sourceCode .sh_argument { color: #006400; }
pre.sh_sourceCode .sh_optionalargument { color: purple; }
pre.sh_sourceCode .sh_math { color: orange; }
pre.sh_sourceCode .sh_bibtex { color: blue; }
/* for diffs */
pre.sh_sourceCode .sh_oldfile { color: orange; }
pre.sh_sourceCode .sh_newfile { color: #006400; }
pre.sh_sourceCode .sh_difflines { color: blue; }
/* for css */
pre.sh_sourceCode .sh_selector { color: purple; }
pre.sh_sourceCode .sh_property { color: blue; }
pre.sh_sourceCode .sh_value { color: #006400; font-style: italic; }
/* other */
pre.sh_sourceCode .sh_section { color: black; font-weight: bold; }
pre.sh_sourceCode .sh_paren { color: red; }
pre.sh_sourceCode .sh_attribute { color: #006400; }
</style><link charset="utf-8" type="text/css" rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-WD"></head>
<body style="display: inherit;"><div class="head"><p><a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a></p><h1 class="title" id="title">Battery Status Event Specification</h1><h2 id="w3c-working-draft-21-april-2011">W3C Working Draft 21 April 2011</h2><dl><dt>This version:</dt><dd><a href="http://www.w3.org/TR/2011/WD-battery-status-20110421/">http://www.w3.org/TR/2011/WD-battery-status-20110421/</a></dd><dt>Latest published version:</dt><dd><a href="http://www.w3.org/TR/battery-status/">http://www.w3.org/TR/battery-status/</a></dd><dt>Latest editor's draft:</dt><dd><a href="http://dev.w3.org/2009/dap/system-info/battery-status.html">http://dev.w3.org/2009/dap/system-info/battery-status.html</a></dd><dt>Editor:</dt><dd><span>Anssi Kostiainen</span>, Nokia</dd>
</dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2011 <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p><hr></div>
<div class="introductory section" id="abstract"><h2>Abstract</h2>
This specification defines a new DOM event type that provides
information about the battery status of the hosting device and
associated auxiliary devices.
</div><div id="sotd" class="introductory section"><h2>Status of This Document</h2><p><em>This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at http://www.w3.org/TR/.</em></p>
<p>
The functionality described in this specification was initially specified as part of the
<a href="http://www.w3.org/TR/system-info-api/">System Information API</a> but has been
extracted in order to be more readily available, more straightforward to implement, and
in order to produce a specification that could be implemented on its own merits without
interference with other, often unrelated, features.
</p>
<p>This document was published by the <a href="http://www.w3.org/2009/dap/">Device APIs and Policy Working Group</a> as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to <a href="mailto:public-device-apis@w3.org">public-device-apis@w3.org</a> (<a href="mailto:public-device-apis-request@w3.org?subject=subscribe">subscribe</a>, <a href="http://lists.w3.org/Archives/Public/public-device-apis/">archives</a>). All feedback is welcome.</p><p>Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.</p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/200/01/pp-impl/43696/status" rel="disclosure">public list of any patent disclosures</a> made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section 6 of the W3C Patent Policy</a>.</p></div><div class="section" id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a class="tocxref" href="#batterystatusevent-interface"><span class="secno">1. </span><span class="idlType formerLink idlType"><code>BatteryStatusEvent</code></span> Interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes"><span class="secno">1.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref"href="#methods"><span class="secno">1.2 </span>Methods</a></li><li class="tocline"><a class="tocxref" href="#the-batterystatus---------event"><span class="secno">1.3 </span>The <span class="event">batterystatus</span>
Event</a></li></ul></li><li class="tocline"><a class="tocxref" href="#examples"><span class="secno">2. </span>Examples</a></li><li class="tocline"><a class="tocxref" href="#acknowledgements"><span class="secno">A. </span>Acknowledgements</a></li><li class="tocline"><a class="tocxref" href="#references"><span class="secno">B. </span>References</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><span class="secno">B.1 </span>Normative references</a></li><li class="tocline"><a class="tocxref" href="#informative-references"><span class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
<div class="section" id="batterystatusevent-interface">
<!--OddPage--><h2><span class="secno">1. </span><a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> Interface</h2>
<p>
This interface defines the <a class="internalDFN" href="#dfn-batterystatus">batterystatus</a>
event type.
</p><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>
<pre class="idl"><span class="idlInterface" id="idl-def-BatteryStatusEvent">[<span class="extAttr">NoInterfaceObject</span>]
interface <span class="idlInterfaceID">BatteryStatusEvent</span> : <span class="idlSuperclass"><a>Event</a></span> {
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-BatteryStatusEvent-isBattery">isBattery</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>boolean</a></span> <span class="idlAttrName"><a href="#widl-BatteryStatusEvent-isCharging">isCharging</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>float</a>?</span> <span class="idlAttrName"><a href="#widl-BatteryStatusEvent-level">level</a></span>;</span>
<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a>unsigned long</a>?</span> <span class="idlAttrName"><a href="#widl-BatteryStatusEvent-timeRemaining">timeRemaining</a></span>;</span>
<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-BatteryStatusEvent-initBatteryStatusEvent">initBatteryStatusEvent</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">type</span></span>, <span class="idlParam"><span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">bubbles</span></span>, <span class="idlParam"><span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">cancelable</span></span>, <span class="idlParam"><span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">isBattery</span></span>, <span class="idlParam"><span class="idlParamType"><a>boolean</a></span> <span class="idlParamName">isCharging</span></span>, <span class="idlParam"><span class="idlParamType"><a>float</a>?</span> <span class="idlParamName">level</span></span>, <span class="idlParam"><span class="idlParamType"><a>unsigned long</a>?</span> <span class="idParamName">timeRemaining</span></span>);</span>
};</span>
</pre><div class="section" id="attributes"><h3><span class="secno">1.1 </span>Attributes</h3><dl class="attributes"><dt id="widl-BatteryStatusEvent-isBattery"><code>isBattery</code> of type <span class="idlAttrType"><a>boolean</a></span>, readonly</dt><dd>
Represents whether the current power source is a
battery. If the device is currently powered by a battery,
then <code>isBattery</code> <em title="must" class="rfc2119">must</em> be set to <code>true</code>,
otherwise <code>false</code>.
<div><em>No exceptions.</em></div></dd><dt id="widl-BatteryStatusEvent-isCharging"><code>isCharging</code> of type <span class="idlAttrType"><a>boolean</a></span>, readonly</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>
<em title="must" class="rfc2119">must</em> be set to <code>true</code>, otherwise <code>false</code>.
<div><em>No exceptions.</em></div></dd><dt id="widl-BatteryStatusEvent-level"><code>level</code> of type <span class="idlAttrType"><a>float</a></span>, readonly, nullable</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> <em title="must" class="rfc2119">must</em> be
set to <code>null</code>.
<div><em>No exceptions.</em></div></dd><dt id="widl-BatteryStatusEvent-timeRemaining"><code>timeRemaining</code> of type <span class="idlAttrType"><a>unsigned long</a></span>, readonly, nullable</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> <em title="must" class="rfc2119">must</em> be set to <code>null</code>.
<div><em>No exceptions.</em></div></dd></dl></div><div class="section" id="methods"><h3><span class="secno">1.2 </span>Methods</h3><dl class="methods"><dt id="widl-BatteryStatusEvent-initBatteryStatusEvent"><code>initBatteryStatusEvent</code></dt><dd>
Initializes a <a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> created
through the <code>DocumentEvent</code> interface
[<cite><a href="#bib-DOM-LEVEL-3-EVENTS" rel="biblioentry" class="bibref">DOM-LEVEL-3-EVENTS</a></cite>].
<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">type</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">bubbles</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">cancelable</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">isBattery</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">isCharging</td><td class="prmType"><code><a>boolean</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><t class="prmDesc"></td></tr><tr><td class="prmName">level</td><td class="prmType"><code><a>float</a></code></td><td class="prmNullTrue">✔</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">timeRemaining</td><td class="prmType"><code><a>unsigned long</a></code></td><td class="prmNullTrue">✔</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>No exceptions.</em></div><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></div>
<p>
The <code>initBatteryStatusEvent()</code> method <em title="must" class="rfc2119">must</em> initialize the
event in a manner analogous to the similarly-named method in
[<cite><a href="#bib-DOM-LEVEL-3-EVENTS" rel="biblioentry" class="bibref">DOM-LEVEL-3-EVENTS</a></cite>].
</p>
<p>
If a change in the battery status of the hosting device occurs,
then the User Agent <em title="must" class="rfc2119">must</em> dispatch a <a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a>
event on the <code>Window</code> [<cite><a href="#bib-HTML5" rel="biblioentry" class="bibref">HTML5</a></cite>] 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>
[<cite><a href="#bib-DOM-LEVEL-3-EVENTS" rel="biblioentry" class="bibref">DOM-LEVEL-3-EVENTS</a></cite>] interface, then the User Agent <em title="must" class="rfc2119">must</em> dispatch a
<a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> event on the <code>o</code> object.
</p>
<p>
The <code>onbatterystatus</code> event handler <em title="must" class="rfc2119">must</em> 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".
</p>
<p>
If an event listener is registered with the event type
<a class="internalDFN" href="#dfn-batterystatus">batterystatus</a>, then the User Agent <em title="must" class="rfc2119">must</em> dispatch a
<a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> event immediately.
</p>
<p class="note">
Make <em>immediately</em> explicit and align with
[<cite><a href="#bib-DOM-LEVEL-3-EVENTS" rel="biblioentry" class="bibref">DOM-LEVEL-3-EVENTS</a></cite>].
</p>
<p>
User Agents <em title="should" class="rfc2119">should</em> dispatch a <a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> event when
<code>timeRemaining</code> varies by a minute or more.
</p>
<p>
User Agents <em title="should" class="rfc2119">should</em> dispatch a <a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> event when
<code>isCharging</code> or <code>isBattery</code> changes.
</p>
<p>
User Agents <em title="should" class="rfc2119">should</em> dispatch a <a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> event when
<code>level</code> varies by a 1% or more.
</p>
<div class="section" id="the-batterystatus---------event">
<h3 id="event-batterystatus"><span class="secno">1.3 </span>The <dfn id="dfn-batterystatus" class="event">batterystatus</dfn>
Event</h3>
<p>
User Agents <em title="must" class="rfc2119">must</em> dispatch this event type to indicate a change in
the battery status.
</p>
</div>
</div>
<div id="examples" class="informative section">
<!--OddPage--><h2><span class="secno">2. </span>Examples</h2><p><em>This section is non-normative.</em></p>
<p>
Register to receive repeated <a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> events.
</p>
<p>
By using the <code>addEventListener()</code> method:
</p>
<div class="example">
<pre class="sh_javascript sh_sourceCode">window<span class="sh_symbol">.</span><span class="sh_function">addEventListener</span><span class="sh_symbol">(</span><span class="sh_string">'batterystatus'</span><span class="sh_symbol">,</span> <span class="sh_keyword">function</span> <span class="sh_symbol">(</span>event<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
console<span class="sh_symbol">.</span><span class="sh_function">log</span><span class="sh_symbol">(</span>event<span class="sh_symbol">.</span>level<span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span><span class="sh_symbol">,</span> <span class="sh_keyword">true</span><span class="sh_symbol">);</span>
</pre>
</div>
<p>
By assigning a function expression to the <code>onbatterystatus</code> property:
</p>
<div class="example">
<pre class="sh_javascript sh_sourceCode">window<span class="sh_symbol">.</span>onbatterystatus <span class="sh_symbol">=</span> <span class="sh_keyword">function</span> <span class="sh_symbol">(</span>event<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
console<span class="sh_symbol">.</span><span class="sh_function">log</span><span class="sh_symbol">(</span>event<span class="sh_symbol">.</span>level<span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span><span class="sh_symbol">;</span>
</pre>
</div>
<p>
Register to receive a single <a class="idlType" href="#idl-def-BatteryStatusEvent"><code>BatteryStatusEvent</code></a> event.
</p>
<p>
By using the <code>addEventListener()</code> method:
</p>
<div class="example">
<pre class="sh_javascript sh_sourceCode"><span class="sh_keyword">var</span> handler <span class="sh_symbol">=</span> <span class="sh_keyword">function</span> <span class="sh_symbol">(</span>event<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
console<span class="sh_symbol">.</span><span class="sh_function">log</span><span class="sh_symbol">(</span>event<span class="sh_symbol">.</span>level<span class="sh_symbol">);</span>
window<span class="sh_symbol">.</span><span class="sh_function">removeEventListener</span><span class="sh_symbol">(</span><span class="sh_string">'batterystatus'</span><span class="sh_symbol">,</span> handler<span class="sh_symbol">,</span> <span class="sh_keyword">true</span><span class="sh_symbol">);</span>
<span class="sh_cbracket">}</span><span class="sh_symbol">;</span>
window<span class="sh_symbol">.</span><span class="sh_function">addEventListener</span><span class="sh_symbol">(</span><span class="sh_string">'batterystatus'</span><span class="sh_symbol">,</span> handler<span class="sh_symbol">,</span> <span class="sh_keyword">true</span><span class="sh_symbol">);</span>
</pre>
</div>
<p>
By assigning a function expression to the <code>onbatterystatus</code> property:
</p>
<div class="example">
<pre class="sh_javascript sh_sourceCode">window<span class="sh_symbol">.</span>onbatterystatus <span class="sh_symbol">=</span> <span class="sh_keyword">function</span> <span class="sh_symbol">(</span>event<span class="sh_symbol">)</span> <span class="sh_cbracket">{</span>
console<span class="sh_symbol">.</span><span class="sh_function">log</span><span class="sh_symbol">(</span>event<span class="sh_symbol">.</span>level<span class="sh_symbol">);</span>
window<span class="sh_symbol">.</span>onbatterystatus <span class="sh_symbol">=</span> <span class="sh_keyword">null</span><span class="sh_symbol">;</span>
<span class="sh_cbracket">}</span><span class="sh_symbol">;</span>
</pre>
</div>
</div>
<div id="acknowledgements" class="appendix section">
<!--OddPage--><h2><span class="secno">A. </span>Acknowledgements</h2>
<p>
Many thanks to the people behind the System Information API and Device
Orientation Event Specification for inspiration.
</p>
</div>
<div class="appendix section" id="references"><!--OddPage--><h2><span class="secno">B. </span>References</h2><div class="section" id="normative-references"><h3><span class="secno">B.1 </span>Normative references</h3><dl class="bibliography"><dt id="bib-DOM-LEVEL-3-EVENTS">[DOM-LEVEL-3-EVENTS]</dt><dd>Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. <a href="http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071221"><cite>Document Object Model (DOM) Level 3 Events Specification.</cite></a> 21 December 2007. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071221">http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071221</a>
</dd><dt id="bib-HTML5">[HTML5]</dt><dd>Ian Hickson; David Hyatt. <a href="http://www.w3.org/TR/2010/WD-html5-20100304/"><cite>HTML 5.</cite></a> 4 March 2010. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2010/WD-html5-20100304/">http://www.w3.org/TR/2010/WD-html5-20100304/</a>
</dd></dl></div><div class="section" id="informative-references"><h3><span class="secno">B.2 </span>Informative references</h3><p>No informative references.</p></div></div></body></html>
Received on Wednesday, 20 April 2011 16:39:02 UTC