index.html 40.1 KB

Raw Blame History Permalink

<!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01 Transitional//EN' 'http://www.w3.org/TR/html4/loose.dtd'>
<html lang="en" dir="ltr"    >
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>Web Notifications</title>


  <style type="text/css">
/*
    XXX this is not up to date with the needs of various other parts, it will require
        to be synched up with the latest developments
        It may be that this will be split up so that only the parts that are acually used
        by the document get to be included (e.g. WebIDL).
*/

/*****************************************************************
 * ReSpec 2 CSS
 * Robin Berjon, 2010-01-04
 *****************************************************************/

/* --- 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:  medium 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 {
    color:  #005a9c;
}
.idlAttrName {
    color:  #ff4500;
}
.idlAttrName 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 {
    margin-left:    2em;
}

.attributes dt, .methods dt, .constants dt {
    font-weight:    normal;
}

.attributes dt code, .methods dt code, .constants dt code {
    font-weight:    bold;
    color:  #000;
    font-family:    monospace;
}

.attributes dt code {
    background:  #ffffd2;
}

.attributes dt .idlAttrType 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 {
    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;
    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 {
    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;
}


/* --- SYNTAX HIGHLIGHTING --- */
/* Pretty printing styles. Used with prettify.js. */
.str { color: #080; }
.kwd { color: #008; }
.com { color: #800; }
.typ { color: #606; }
.lit { color: #066; }
.pun { color: #660; }
.pln { color: #000; }
.tag { color: #008; }
.atn { color: #606; }
.atv { color: #080; }
.dec { color: #606; }
pre.prettyprint { padding: 2px; border: 1px solid #888 }

/* Specify class=linenums on a pre to get line numbering */
ol.linenums { margin-top: 0; margin-bottom: 0 } /* IE indents via margin-left */
li.L0, li.L1, li.L2, li.L3, li.L5, li.L6, li.L7, li.L8 { list-style-type: none }
/* Alternate shading for lines */
li.L1, li.L3, li.L5, li.L7, li.L9 { background: #eee }

@media print {
  .str { color: #060; }
  .kwd { color: #006; font-weight: bold; }
  .com { color: #600; font-style: italic; }
  .typ { color: #404; font-weight: bold; }
  .lit { color: #044; }
  .pun { color: #440; }
  .pln { color: #000; }
  .tag { color: #006; font-weight: bold; }
  .atn { color: #404; }
  .atv { color: #060; }
}
</style><link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-WD.css" type="text/css" media="all" charset="utf-8">
  <body><div class="head">
    <p>

      <a href="http://www.w3.org/"><img width="72" height="48" src="http://www.w3.org/Icons/w3c_home" alt="W3C"></a>


    </p>
    <h1 class="title" id="title" >Web Notifications</h1>

    <h2 id="w3c-working-draft-01-march-2011"><acronym title="World Wide Web Consortium">W3C</acronym> Working Draft 01 March 2011</h2>
    <dl>

        <dt>This Version:</dt><dd>   <a href="http://www.w3.org/TR/2011/WD-notifications-20110301/">http://www.w3.org/TR/2011/WD-notifications-20110301/</a></dd>
        <dt>Latest Published Version:</dt><dd>   <a href="http://www.w3.org/TR/notifications/">http://www.w3.org/TR/notifications/</a></dd>

          <dt>Latest Editor's Draft:</dt><dd>
   <a href="http://dev.w3.org/2006/webapi/WebNotifications/publish/Notifications.html">http://dev.w3.org/2006/webapi/WebNotifications/publish/Notifications.html</a></dd>


    <dt>Editor:</dt>

      <dd class="Editor"><span ><span class="name" >John Gregg</span>,

            <a class="company" href="http://www.google.com/" rel="foaf:workplaceHomepage">Google</a>


         &lt;<a class="email" href="mailto:johnnyg@google.com" rel="foaf:mbox">johnnyg@google.com</a>&gt;

      </span></dd>


    </dl>


    <p class="copyright">

      <a class="license" href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright" rel="license">Copyright</a> ©
      2011

      <span><a class="publisher" href="http://www.w3.org/"><acronym title="World Wide Web Consortium"><acronym title="World Wide Web Consortium">W3C</acronym></acronym></a></span><sup>®</sup>
      (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology"><acronym title="Massachusetts Institute of Technology">MIT</acronym></acronym></a>,
      <a href="http://www.ercim.eu/"><acronym title="European Research Consortium for Informatics and Mathematics"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></acronym></a>,
      <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved.
      <acronym title="World Wide Web Consortium">W3C</acronym> <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 id="abstract" class="introductory section"    ><h2>Abstract</h2>
    <p>
      This document defines an API for displaying simple notifications to the user.
    </p>
  </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 <acronym title="World Wide Web Consortium">W3C</acronym> publications and the latest revision
      of this technical report can be found in the <a href="http://www.w3.org/TR/"><acronym title="World Wide Web Consortium">W3C</acronym> technical reports
      index</a> at http://www.w3.org/TR/.</em></p>

      <p>
        This document was published by the <a href="http://www.w3.org/2010/web-notifications/">Web Notification Working Group</a> as
        a
        First Public Working Draft.
         This document is intended to become a <acronym title="World Wide Web Consortium">W3C</acronym> Recommendation.
        If you wish to make comments regarding this document, please send them to
        <a href="mailto:public-web-notification@w3.org">public-web-notification@w3.org</a>
        (<a href="mailto:public-web-notification-request@w3.org?subject=subscribe">subscribe</a>,
        <a href="http://lists.w3.org/Archives/Public/public-web-notification/">archives</a>).


        All feedback is welcome.
      </p>

        <p>
          Publication as a Working Draft does not imply endorsement by the <acronym title="World Wide Web Consortium">W3C</acronym> 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>Although this is an initial draft and the group is open to changing the design,
the group has so far not received feedback asking it to do so.</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 <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>.

        <acronym title="World Wide Web Consortium">W3C</acronym> maintains a <a href="http://www.w3.org/2004/01/pp-impl/45313/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 <acronym title="World Wide Web Consortium">W3C</acronym> Patent Policy</a>.
      </p>
    </div><div id="toc"   class="section"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a href="#definitions" class="tocxref"><span class="secno">1. </span>Definitions</a></li><li class="tocline"><a href="#requirements" class="tocxref"><span class="secno">2. </span>Requirements and use cases</a></li><li class="tocline"><a href="#introduction" class="tocxref"><span class="secno">3. </span>Introduction</a><ul class="toc"><li class="tocline"><a href="#security" class="tocxref"><span class="secno">3.1 </span>Security</a></li></ul></li><li class="tocline"><a href="#permissions" class="tocxref"><span class="secno">4. </span>Permissions</a></li><li class="tocline"><a href="#idl-if-Notification" class="tocxref"><span class="secno">5. </span>The Notification interface</a><ul class="toc"><li class="tocline"><a href="#methods" class="tocxref"><span class="secno">5.1 </span>Methods</a></li><li class="tocline"><a href="#attributes" class="tocxref"><span class="secno">5.2 </span>Attributes</a></li><li class="tocline"><a href="#directionality" class="tocxref"><span class="secno">5.3 </span>Directionality</a></li><li class="tocline"><a href="#event-handler-attributes" class="tocxref"><span class="secno">5.4 </span>Event handler attributes</a></li>
<li class="tocline"><a href="#notification-constructor" class="tocxref"><span class="secno">5.5 </span>Constructor</a></li>
</ul></li><li class="tocline"><a href="#algorithms" class="tocxref"><span class="secno">6. </span>Queueing and displaying notifications</a><ul class="toc"><li class="tocline"><a href="#queueing-notifications" class="tocxref"><span class="secno">6.1 </span>Queueing notifications</a></li><li class="tocline"><a href="#displaying" class="tocxref"><span class="secno">6.2 </span>Displaying notifications</a></li><li class="tocline"><a href="#replacing" class="tocxref"><span class="secno">6.3 </span>Replacing a notification</a></li></ul></li><li class="tocline"><a href="#interactions" class="tocxref"><span class="secno">7. </span>Interacting with notifications</a><ul class="toc"><li class="tocline"><a href="#using-events" class="tocxref"><span class="secno">7.1 </span>Using events</a></li></ul></li><li class="tocline"><a href="#references" class="tocxref"><span class="secno">A. </span>References</a><ul class="toc"><li class="tocline"><a href="#normative-references" class="tocxref"><span class="secno">A.1 </span>Normative references</a></li></ul></li></ul></div>

  <div id="definitions"   class="section"><!--OddPage--><h2><span class="secno">1. </span>Definitions</h2>


    <ul>
      <li><em>ambient notification</em>: A notification which appears and disappears automatically without user action.</li>
      <li><em>interactive notification</em>: A notification which can receive events from user actions and deliver them to the application which created the notification.</li>
      <li><em>persistent notification</em>: A notification which is displayed until the user explicitly dismisses it.</li>
      <li><em>notification platform</em>: A notification platform is a system outside the user agent which provides desktop notifications.  Examples include Growl on MacOS, NotifyOSD on Linux, and the Windows notification API.</li>
      <li><em>simple notification</em>: A notification which consists only of an icon and one or two lines of text.</li>
      <li><em>web notification</em>: A notification which consists of Web platform content, such as HTML or SVG.</li>
    </ul>
  </div>

  <div id="requirements"   class="section"><!--OddPage--><h2><span class="secno">2. </span>Requirements and use cases</h2>

    This specification must meet the following requirements:
    <ul>
      <li>An implementation which uses only the existing notification platforms in major platforms to display notifications must be able to comply with the specification.</li>
      <li>The specification must allow compliant implementations regardless of platform or device.</li>
      <li>The specification must provide controls to users in order to prevent unwanted notifications to be displayed.</li>
      <li>The specification must define an event model for interactive notifications.</li>
      <li>The specification must address security issues.</li>
      <li>The specification should not require any implementation to display persistent notifications.</li>
      <li>The specification should be compatible with other Web technologies, such as HTML and SVG.</li>
    </ul>

    The specification attempts to address the following use cases:
    <ul>
      <li>An application alerts the user "you've got mail" in the form of an ambient notification, with no interaction necessary.</li>
      <li>An application alerts the user "you've got mail" as an interactive notification which allows the user to easily return to the inbox.</li>
      <li>A calendar application alerts the user for an upcoming meeting, and allows the user to easily specify a "snooze" delay of several possible time periods.</li>
      <li>A system alerts the user "your printer is out of paper".</li>
      <li>An application with multiple simultaneous execution contexts (like a multi-tab email application) wants to show notifications without creating duplicate notifications.</li>
    </ul>
  </div>

  <div id="introduction" class="informative section"  ><!--OddPage--><h2><span class="secno">3. </span>Introduction</h2><em>This section is non-normative.</em>

    <p>
      This specification provides an API to generate <em>simple notifications</em> to
      alert users outside of the web page.  It does not specify exactly how a user
      agent should display these notifications; the best presentation depends on the device
      where the user agent is run.  When this specificiation refers to displaying
      notifications on the "desktop", it generally refers to some static display
      area outside the web page, but may take several forms, including:
      </p><ul>
        <li>a corner of the user's display,</li>
        <li>an area within the chrome of the user agent,</li>
        <li>the "home" screen of a mobile device,</li>
        <li><em>et al.</em></li>
      </ul>
      This specification does not define exactly how the user agent should display
      the notification, and the API is designed to be flexible with respect to
      presentation options.
    <p></p>
    <p>
      This specification is designed to be compatible with existing notification platforms
      as much as possible, but also to be platform-independent.  Since the common platforms
      do not provide the same functionality, this spec will indicate what events are guaranteed
      and which are not.  In particular, notifications as specified here only can contain
      text and icon content.  In the future, notifications generated from Web content may
      wish to contain Web content themselves, but that is outside the scope of this document.
    </p>
    <p>
      In general, the event model for notifications is best-effort; while the Notification
      object offers an "onclick" event, applications may enhance their functionality by
      listening for that event, but <em>must not depend on receiving it</em>,
      in case the underlying notification platform does not provide that capability.
    </p>

    <div class="section" id="security"  ><h3><span class="secno">3.1 </span>Security</h3><em>This section is non-normative.</em>

      <p>
	Notifications should only be presented when the user has indicated they are desired;
	without this they could create a negative experience for the user.
      </p>
      </div>
  </div>

  <div id="permissions"   class="section"><!--OddPage--><h2><span class="secno">4. </span>Permissions</h2>

    <p>
      Permissions for notifications must be controlled using the Feature Permissions interface
      where Notifications are a privileged feature with unique id 'notifications'. [<cite><a class="bibref" rel="biblioentry" href="#bib-PERMISSIONS">PERMISSIONS</a></cite>]
    </p>

    <p>
      Throughout this document, "notification permission is allowed" shall mean that
      the permission level of the 'notifications' feature for the current
      security origin is <code>USER_ALLOWED</code>  or <code>DEFAULT_ALLOWED</code>
      in the meaning of [<cite><a class="bibref" rel="biblioentry" href="#bib-PERMISSIONS">PERMISSIONS</a></cite>], and "notification permission is denied" shall mean
      that the current permission level has some other value.
    </p>
  </div>

  <div id="idl-if-Notification"   class="section"><!--OddPage--><h2><span class="secno">5. </span>The Notification interface</h2>
    <p>
      The Notification interface represents a single notification to be shown to the user. It extends the EventTarget interface defined in [<cite><a class="bibref" rel="biblioentry" href="#bib-DOM-LEVEL-3-EVENTS">DOM-LEVEL-3-EVENTS</a></cite>].
    </p>
    <pre class="idl"><span class="idlInterface" id="idl-def-Notification">[<a href="#notification-constructor"><span class="extAttr">Constructor</span></a>]
interface <span class="idlInterfaceID">Notification</span> : <span class="idlSuperclass"><a>EventTarget</a></span> {
<span class="idlMethod">    <span class="idlMethType"><span><a>void</a></span></span>         <span class="idlMethName"><a href="#widl-Notification-show">show</a></span> ();
</span><span class="idlMethod">    <span class="idlMethType"><span><a>void</a></span></span>         <span class="idlMethName"><a href="#widl-Notification-cancel">cancel</a></span> ();
</span>
<span class="idlAttribute">    attribute <span class="idlAttrType"><span><a>Function</a></span></span> <span class="idlAttrName"><a href="#widl-Notification-onclick">onclick</a></span>;
</span><span class="idlAttribute">    attribute <span class="idlAttrType"><span><a>Function</a></span></span> <span class="idlAttrName"><a href="#widl-Notification-onshow">onshow</a></span>;
</span><span class="idlAttribute">    attribute <span class="idlAttrType"><span><a>Function</a></span></span> <span class="idlAttrName"><a href="#widl-Notification-onerror">onerror</a></span>;
</span><span class="idlAttribute">    attribute <span class="idlAttrType"><span><a>Function</a></span></span> <span class="idlAttrName"><a href="#widl-Notification-onclose">onclose</a></span>;
</span><span class="idlAttribute">    attribute <span class="idlAttrType"><span><a>DOMString</a></span></span> <span class="idlAttrName"><a href="#widl-Notification-replaceId">replaceId</a></span>;
</span><span class="idlAttribute">    attribute <span class="idlAttrType"><span><a>DOMString</a></span></span> <span class="idlAttrName"><a href="#widl-Notification-dir">dir</a></span>;
</span>};
</span></pre>

<div class="section" id="methods"  ><h3><span class="secno">5.1 </span>Methods</h3>
<dl>
<dt id="widl-Notification-cancel">
  <code>cancel</code>
</dt>
<dd>

	      <p>
	        Requests the user agent to not show this notification. If the notification
	        has already been displayed, the user agent must remove it from the display;
	        if it has not yet be displayed, the user agent must prevent its being
	        displayed.
	      </p>


  <div><em>No Parameters.</em></div>


  <div><em>No exceptions.</em></div>

  <div>
    <em>Return type:</em> <code>void</code>
  </div>
</dd><dt id="widl-Notification-show">
  <code>show</code>
</dt>
<dd>

	      <p>
	        Requests the user agent to show the notification to the user. Depending on
	        desktop space, user idleness, or other factors as determined by the user
	        agent, this may happen immediately or be postponed, but must eventually
	        be done, following the algorithm for queueing a notification below.
	      </p>
	      <p>
	        A user agent must not show any notifications if notification permission is denied.
	        If notification permission is denied when <code>show()</code> is invoked,
	        an <code>error</code> event must be fired on this notification object.
	      </p>


  <div><em>No Parameters.</em></div>


  <div><em>No exceptions.</em></div>

  <div>
    <em>Return type:</em> <code>void</code>
  </div>
</dd></dl></div><div class="section" id="attributes"  ><h3><span class="secno">5.2 </span>Attributes</h3><dl><dt id="widl-Notification-dir">
  <code>dir</code>
  of type

  <span class="idlAttrType">DOMString</span>
</dt>
<dd>

	      <p>
	        The <code>dir</code> attribute specifies the directionality of the notification.
	      </p>


    <div><em>No exceptions.</em></div>

</dd><dt id="widl-Notification-onclick">
  <code>onclick</code>
  of type

  <span class="idlAttrType">Function</span>
</dt>
<dd>

	      <p>
	        An event listener function corresponding to the event type "click".  This event
	        listener is must be invoked when the user clicks on a notification.
	      </p>
	      <p>
	        <em>
	        This event is not guaranteed if the underlying notification platform does not support receiving
	        click events.
	        </em>
	      </p>


    <div><em>No exceptions.</em></div>

</dd><dt id="widl-Notification-onclose">
  <code>onclose</code>
  of type

  <span class="idlAttrType">Function</span>
</dt>
<dd>

	      <p>
	        An event listener function corresponding to the event type "close".  This
	        event listener must be invoked after the "show" event, at the point
	        when the notification is dismissed by the user, closed by script, or closed by the notification
	        platform.
	      </p>


    <div><em>No exceptions.</em></div>

</dd><dt id="widl-Notification-onerror">
  <code>onerror</code>
  of type

  <span class="idlAttrType">Function</span>
</dt>
<dd>

	      <p>
	        An event listener function corresponding to the event type "error".  This
	        event listener must be invoked after the <code>show()</code> method is called, if the
	        notification cannot be displayed to the user because of an error.
	      </p>


    <div><em>No exceptions.</em></div>

</dd><dt id="widl-Notification-onshow">
  <code>onshow</code>
  of type

  <span class="idlAttrType">Function</span>
</dt>
<dd>

	      <p>
	        An event listener function corresponding to the event type "show".  This
	        event listener must be invoked after the <code>show()</code> method is called, at the
	        point when the notification actually becomes visible to the user.
	      </p>
	      <p>
	        <em>
	        If the underlying notification platform does not show the notification immediately,
	        this event may precede the notification becoming visible; however the notification
	        will never become visible before this event is dispatched.
	        </em>
	      </p>


    <div><em>No exceptions.</em></div>

</dd><dt id="widl-Notification-replaceId">
  <code>replaceId</code>
  of type

  <span class="idlAttrType">DOMString</span>
</dt>
<dd>

	      <p>
	        A value which identifies this notification for replacement by another notification
	        serving the same purpose.  The user agent should not allow two notifications created
	        by the same security origin and having the same <code>replaceId</code> value to be
	        shown simultaneously.
	      </p>


    <div><em>No exceptions.</em></div>

</dd></dl></div>

    <div class="section" id="directionality"  ><h3><span class="secno">5.3 </span>Directionality</h3>

      <p>
	The <code>dir</code> attribute of the <code>Notification</code> interface has
	has all the properties of the <code>dir</code> attribute as defined in [<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>], however
	since the notification does not have a parent element, it must receive a default
	value elsewhere, as follows.
      </p>
      <p>
        In environments where the global object is represented by the <code>Window</code>
	object, if the notification's directionality state is not <em>ltr</em> or <em>rtl</em>,
	the directionality must be the same as	the <code>Document</code> object associated
	with the global <code>Window</code> object.

	In other environments, if the notification's directionality state is not <em>ltr</em> or <em>rtl</em>,
	the directionality should be <em>ltr</em>.
      </p>
    </div>


    <div class="section" id="event-handler-attributes"  ><h3><span class="secno">5.4 </span>Event handler attributes</h3>

      <p>The following are event handler attributes (and their corresponding event handler event types, as defined by
       [<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>]) that must be supported as DOM attributes by the Notification object.</p>
      <table>
	<thead style="border-bottom: medium solid;">
	  <tr>
	    <th>event handler attribute</th>
	    <th>event handler event type</th>
	  </tr>
	</thead>
	<tbody><tr>
	  <td><code>onclick</code></td>
	  <td><code>click</code></td>
	</tr>
	<tr>
	  <td><code>onshow</code></td>
	  <td><code>show</code></td>
	</tr>
	<tr>
	  <td><code>onerror</code></td>
	  <td><code>error</code></td>
	</tr>
	<tr>
	  <td><code>onclose</code></td>
	  <td><code>close</code></td>
	</tr>
      </tbody></table>
    </div>

<div class="section" id="notification-constructor">
<h3><span class="secno">5.5 </span>Constructor</h3>
    <pre class="idl"><span class="idlMethod">    <span class="idlMethType"><span><a href="#idl-def-Notification" class="idlType"><code>Notification</code></a></span></span> <span class="idlMethName">Notification</span> (<span class="idlParam"> in <span class="idlParamType"><span><a>DOMString</a></span></span> <span class="idlParamName">iconUrl</span></span>, <span class="idlParam"> in <span class="idlParamType"><span><a>DOMString</a></span></span> <span class="idlParamName">title</span></span>, <span class="idlParam"> in <span class="idlParamType"><span><a>DOMString</a></span></span> <span class="idlParamName">body</span></span>);</span></pre>
<dl>
<dt></dt>
<dd>

          <p>Returns a new simple notification object with the provided content.</p>

  <table class="parameters">
    <tbody><tr><th>Parameter</th><th>Type</th><th>Description</th>

    </tr><tr>
      <td class="prmName">iconUrl</td>
      <td class="prmType"><code>DOMString</code></td>


      <td class="prmDesc">
	             URL of the icon to be shown with this notification.
	             The parameter must be resolved relative to the current document base URL or worker script URL.
              </td>
    </tr>

    <tr>
      <td class="prmName">title</td>
      <td class="prmType"><code>DOMString</code></td>


      <td class="prmDesc">
	            Primary text, or title, of the notification.  The user agent may ignore any markup in this string and treat it as plain text.
              </td>
    </tr>

    <tr>
      <td class="prmName">body</td>
      <td class="prmType"><code>DOMString</code></td>

      <td class="prmDesc">
	            Secondary text, or body, of the notification.  The user agent may ignore any markup in this string and treat it as plain text.
              </td>
    </tr>

  </tbody></table>

  <div><em>No exceptions.</em></div>

</dd>
</dl>
          <p>
          When the <code>Notification()</code> constructor is invoked, the user agent must return a new Notification object.
          </p>
</div>
  </div>

  <div id="algorithms"   class="section"><!--OddPage--><h2><span class="secno">6. </span>Queueing and displaying notifications</h2>

    <div class="section" id="queueing-notifications"  ><h3><span class="secno">6.1 </span>Queueing notifications</h3>

      <p>
	If the device allows notifications to displayed immediately without limitations on
	the number of concurrent notifications, it must display a notification immediately
	whenever <code>show</code> is called and notification permission is allowed.
      </p>

      <p>
	If the device does have limitations on the number of concurrent notifications,
	when <code>show</code> is called and notification permission is allowed,
	the user agent must either immediately call to a notifications platform which
	supports queueing, or use the following algorithm.
      </p>
      <p>
	The user agent must keep a <em>queue of pending notifications</em> and a <em>list of active notifications</em>.
      </p>
      <ol>
	<li>Get the replacement id of the notification to be shown, and let it be replaceId.</li>
	<li>
	  If replaceId is defined, examine all the notifications in the <em>list of active notifications</em>.
	  If any notification in the list has the same source origin and has replacement id equal to replaceId,
	  do the following steps and then terminate this algorithm.  Let <em>existing</em> be the notification in the list
	  which matches.
	  <ol>
	    <li>Replace <em>existing</em> with the new notification using the <a href="#replacing" class="sec-ref">replacing a notification</a> algorithm.</li>
	    <li>If the replacement returned error information, stop.</li>
	    <li>Remove <em>existing</em> from the <em>list of active notifications</em>.</li>
	    <li>Add the new notification to the <em>list of active notifications</em>.</li>
  </ol>
	</li>
	<li>Add the notification to the <em>queue of pending notifications</em>.</li>
	<li>Wait until there is available space on the device.</li>
	<li>Display the first notification in the <em>queue of pending notifications</em> using
	  the <a href="#displaying" class="sec-ref">displaying a notification</a> algorithm.</li>
      </ol>
      <p>
	When the available display space changes on the device such that a new notification may be
	displayed, for example due to a previous notification being dismissed, the user agent should
	<a href="#displaying" class="sec-ref">display</a> the first notification in the queue using the procedure described above.
      </p>
    </div>

    <div class="section" id="displaying"  ><h3><span class="secno">6.2 </span>Displaying notifications</h3>

      <p>
	When a user agent is to <em>display a notification</em>, the user agent should perform the following steps:
	</p><ol>
	  <li>
	    Fetch the resource given by <code>iconUrl</code> using the algorithm defined in [<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>].
	  </li>
	  <li>
	    If the fetch algorithm returns error information, fire the <code>error</code> event on the notification
	    object and stop executing this algorithm.
	  </li>
	  <li>Fire the <code>show</code> event on the notification object.</li>
	  <li>Show the notification on the device, such as by calling the appropriate notification platform.</li>
	</ol>
      <p></p>
    </div>

    <div class="section" id="replacing"  ><h3><span class="secno">6.3 </span>Replacing a notification</h3>

      <p>
	When a user agent is to <em>replace a notification</em>, the user agent should perform the following steps.
	Let <em>old</em> be the notification to be replaced by <em>new</em>.
	</p><ol>
	  <li>
	    Fetch the icon resource in <em>new</em> using the algorithm defined in [<cite><a class="bibref" rel="biblioentry" href="#bib-HTML5">HTML5</a></cite>].
	  </li>
	  <li>
	    If the fetch algorithm returns error information, fire the <code>error</code> event on the <em>new</em> notification
	    object and stop executing this algorithm, returning the error information.  The <em>old</em> notification is not affected.
	  </li>
	  <li>Fire the <code>close</code> event on the <em>old</em> notification object.</li>
	  <li>Fire the <code>show</code> event on the <em>new</em> notification object.</li>
	  <li>If the underlying notification platform supports replacement, replace <em>old</em> with <em>new</em> on the device.</li>
	  <li>If the underlying notification platform does not support replacment, remove <em>old</em> from the device and show <em>new</em> on the device.</li>
	</ol>
      <p></p>
    </div>
  </div>
  <div id="interactions" class="informative section"  ><!--OddPage--><h2><span class="secno">7. </span>Interacting with notifications</h2><em>This section is non-normative.</em>

    <div class="section" id="using-events"  ><h3><span class="secno">7.1 </span>Using events</h3><em>This section is non-normative.</em>

      <p>
	Notification objects dispatch events during their lifecycle, which authors can use
	to generate desired behaviors.
      </p>
      <p>
	The <code>show</code> event occurs when the notification is shown to the user --
	this may be at some time after the <code>show()</code> method is called in the case
	of limited display space and a queue.
      </p>

      <p>
	In the following example, this event is used to guarantee that regardless of when
	the notification is shown, it is displayed for only 15 seconds.
      </p>

      <pre class="example" title="">var notification = new Notification("mail.png", "New Email Received");
notification.onshow = function() { setTimeout(notification.cancel(), 15000); }
notification.show();</pre>

      <p>
	The <code>close</code> events occurs when the notification is dismissed by the user.
	Authors may use this event to perform actions when notifications are acknowledged.
      </p>
      <p>
	In the following example, when a meeting reminder notification is acknowledged, the
	application suppresses other forms of reminders.
      </p>

      <pre class="example" title="">var notification = new Notification("calendar.png", "Meeting about to begin", "Room 101");
notification.onclose = function() { cancelReminders(event); }
notification.show();</pre>
    </div>
  </div>


<div id="references" class="appendix section"  ><!--OddPage--><h2><span class="secno">A. </span>References</h2><div class="section" id="normative-references"  ><h3><span class="secno">A.1 </span>Normative references</h3><dl class="bibliography" ><dt id="bib-DOM-LEVEL-3-EVENTS">[DOM-LEVEL-3-EVENTS]</dt><dd >Doug Schepers; Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. <a href="http://www.w3.org/TR/2010/WD-DOM-Level-3-Events-20100907"><cite>Document Object Model (DOM) Level 3 Events Specification.</cite></a> 07 September 2010. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2010/WD-DOM-Level-3-Events-20100907">http://www.w3.org/TR/2010/WD-DOM-Level-3-Events-20100907</a></dd><dt id="bib-HTML5">[HTML5]</dt><dd >Ian Hickson. <a href="http://dev.w3.org/html5/spec/"><cite>HTML5.</cite></a> Editor’s Draft. (Work in progress.) URL: <a href="http://dev.w3.org/html5/spec/">http://dev.w3.org/html5/spec/</a> </dd><dt id="bib-PERMISSIONS">[PERMISSIONS]</dt><dd >John Gregg. <a href="http://dev.w3.org/2006/webapi/WebNotifications/publish/FeaturePermissions.html"><cite>Feature Permissions.</cite></a> 12 October 2010. Editor’s Draft. (Work in progress.) URL: <a href="http://dev.w3.org/2006/webapi/WebNotifications/publish/FeaturePermissions.html">http://dev.w3.org/2006/webapi/WebNotifications/publish/FeaturePermissions.html</a></dd></dl></div></div></body></html>