[] (0) Remove the showNotification() API due to lack of interest from…

… implementors.

git-svn-id: http://svn.whatwg.org/webapps@2597 340c8d12-0b0e-0410-8428-c7bf67bfef74

index

@@ -674,8 +674,7 @@
    <ol>
     <li><a href=#simple-dialogs><span class=secno>5.5.1 </span>Simple dialogs</a></li>
     <li><a href=#printing><span class=secno>5.5.2 </span>Printing</a></li>
     <li><a href=#dialogs-implemented-using-separate-documents><span class=secno>5.5.3 </span>Dialogs implemented using separate documents</a></li>
     <li><a href=#notifications><span class=secno>5.5.4 </span>Notifications</a></ol></li>
     <li><a href=#dialogs-implemented-using-separate-documents><span class=secno>5.5.3 </span>Dialogs implemented using separate documents</a></ol></li>
   <li><a href=#system-state-and-capabilities><span class=secno>5.6 </span>System state and capabilities</a>
    <ol>
     <li><a href=#client-identification><span class=secno>5.6.1 </span>Client identification</a></li>

   </dd>


   <dt>The <dfn id=sandboxed-annoyances-browsing-context-flag>sandboxed annoyances browsing context flag</dfn></dt>
<!-- XXX-NOTIFY
   <dt>The <dfn>sandboxed annoyances browsing context flag</dfn></dt>

   <dd>

    <p>This flag prevents content from <a href=#sandboxNotifications>showing notifications</a> outside of
    the <a href=#nested-browsing-context>nested browsing context</a>.</p>
    <p>This flag prevents content from <a
    href="#sandboxNotifications">showing notifications</a> outside of
    the <span>nested browsing context</span>.</p>

   </dd>
-->


   <dt>The <dfn id=sandboxed-origin-browsing-context-flag>sandboxed origin browsing context flag</dfn>, unless
  void <a href=#dom-print title=dom-print>print</a>();
  any <a href=#dom-showmodaldialog title=dom-showModalDialog>showModalDialog</a>(in DOMString url);
  any <a href=#dom-showmodaldialog title=dom-showModalDialog>showModalDialog</a>(in DOMString url, in any arguments);<!--
  any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url, in any arguments, in DOMString features);-->
  void <a href=#dom-shownotification title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description);
  void <a href=#dom-shownotification title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);
  any <span title="dom-showModalDialog">showModalDialog</span>(in DOMString url, in any arguments, in DOMString features);--><!-- XXX-NOTIFY
  void <span title="dom-showNotification">showNotification</span>(in DOMString title, in DOMString subtitle, in DOMString description);
  void <span title="dom-showNotification">showNotification</span>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);-->

  // <a href=#crossDocumentMessages>cross-document messaging</a>
  void <a href=#dom-window-postmessage-2 title=dom-window-postMessage-2>postMessage</a>(in any message, in DOMString targetOrigin);
  close the browsing context.</p>


  <h4 id=notifications><span class=secno>5.5.4 </span>Notifications</h4>
<!-- XXX-NOTIFY
  <h4>Notifications</h4>

<!-- v2 feature requests:
<!- - v2 feature requests:

   - ability to snooze a notification so it comes again later
      - shouldn't be on all messages, only those for which it makes
        sense
      - possibly just provide a new argument that takes an array of
        (label, callback) tuples so that sites can implement this
        themselves
      - full HTML notifications

  -->
  - ->

  <p>Notifications are short, transient messages that bring the user's
  attention to new information, or remind the user of scheduled
  rendering area unless the user explicitly indicates that the site
  can be trusted.</p>

  <p>To this end, each <a href=#origin-0>origin</a> can be flagged as being a
  <dfn id=trusted-notification-source>trusted notification source</dfn>. By default origins should
  <p>To this end, each <span>origin</span> can be flagged as being a
  <dfn>trusted notification source</dfn>. By default origins should
  not be flagged as such, but user agents may allow users to whitelist
  origins or groups of origins as being <a href=#trusted-notification-source title="trusted
  notification source">trusted notification sources</a>. Only
  origins or groups of origins as being <span title="trusted
  notification source">trusted notification sources</span>. Only
  origins flagged as trusted in this way are allowed to show
  notification UI outside of their tab.</p>

  <p class=example>For example, a user agent could allow a user to
  <p class="example">For example, a user agent could allow a user to
  mark all subdomains and ports of example.org as trusted
  notification sources. Then, mail.example.org and
  calendar.example.org would both be able to show notifications,
  without the user having to flag them individually.</p>

  <p>The <dfn id=dom-shownotification title=dom-showNotification><code>showNotification(<var title="">title</var>, <var title="">subtitle</var>, <var title="">description</var>, <var title="">onclick</var>)</code></dfn> method, when invoked, must
  <p>The <dfn title="dom-showNotification"><code>showNotification(<var
  title="">title</var>, <var title="">subtitle</var>, <var
  title="">description</var>, <var
  title="">onclick</var>)</code></dfn> method, when invoked, must
  cause the user agent to show a notification.</p>

  <p id=sandboxNotifications>If the method was invoked from a <a href=#concept-script title=concept-script>script</a>
  whose <a href="#script's-browsing-context" title="script's browsing context">browsing
  context</a> has the <a href=#sandboxed-annoyances-browsing-context-flag>sandboxed annoyances browsing context
  flag</a> set, then the notification must be shown within that
  <a href=#browsing-context>browsing context</a>. The notification is said to be a
  <dfn id=sandboxed-notification>sandboxed notification</dfn>.</p>

  <p>Otherwise, if the <a href=#origin-0>origin</a> of the <a href="#script's-browsing-context" title="script's browsing context">browsing context</a> of the
  <a href=#concept-script title=concept-script>script</a> that invoked the method is <em>not</em> flagged as being a
  <a href=#trusted-notification-source>trusted notification source</a>, then the notification
  should be rendered within the <a href=#top-level-browsing-context>top-level browsing
  context</a> of the <a href="#script's-browsing-context">script's browsing context</a>. The
  notification is said to be a <dfn id=normal-notification>normal notification</dfn>. User
  agents should provide a way to set the origin's <a href=#trusted-notification-source>trusted
  notification source</a> flag from the notification, so that the
  user can benefit from notifications even when the user agent is not
  the active application.</p>

  <p>Otherwise, the <a href=#origin-0>origin</a> is flagged as a <a href=#trusted-notification-source>trusted
  notification source</a>, and the notification should be shown
  <p id="sandboxNotifications">If the method was invoked from a <span
  title="concept-script">script</span> whose <span title="script's
  browsing context">browsing context</span> has the <span>sandboxed
  annoyances browsing context flag</span> set, then the notification
  must be shown within that <span>browsing context</span>. The
  notification is said to be a <dfn>sandboxed notification</dfn>.</p>

  <p>Otherwise, if the <span>origin</span> of the <span
  title="script's browsing context">browsing context</span> of the
  <span title="concept-script">script</span> that invoked the method
  is <em>not</em> flagged as being a <span>trusted notification
  source</span>, then the notification should be rendered within the
  <span>top-level browsing context</span> of the <span>script's
  browsing context</span>. The notification is said to be a
  <dfn>normal notification</dfn>. User agents should provide a way to
  set the origin's <span>trusted notification source</span> flag from
  the notification, so that the user can benefit from notifications
  even when the user agent is not the active application.</p>

  <p>Otherwise, the <span>origin</span> is flagged as a <span>trusted
  notification source</span>, and the notification should be shown
  using the platform conventions for system-wide notifications. The
  notification is said to be a <dfn id=trusted-notification>trusted notification</dfn>. User
  agents may provide a way to unset the origin's <a href=#trusted-notification-source>trusted
  notification source</a> flag from within the notification, so as
  notification is said to be a <dfn>trusted notification</dfn>. User
  agents may provide a way to unset the origin's <span>trusted
  notification source</span> flag from within the notification, so as
  to allow users to easily disable notifications from sites that abuse
  the privilege.</p>

  <div class=example>
  <div class="example">

   <p>For example, if a site contains a gadget of a mail application
   in a sandboxed <code><a href=#the-iframe-element>iframe</a></code> and that frame triggers a
   in a sandboxed <code>iframe</code> and that frame triggers a
   notification upon the receipt of a new e-mail message, that
   notification would be displayed on top of the gadget only.</p>


  </div>

  <div class=example>
  <div class="example">

   <p>The style of notifications varies from platform to platform. On
   some, it is typically displayed as a "toast" window that slides in

  </div>

  <p>When a <a href=#normal-notification>normal notification</a> (but not a
  <a href=#sandboxed-notification>sandboxed notification</a>) is shown, the user agent may
  bring the user's attention to the <a href=#top-level-browsing-context>top-level browsing
  context</a> of the <a href="#script's-browsing-context" title="script's browsing
  context">browsing context</a> of the <a href=#concept-script title=concept-script>script</a> that invoked the
  method, if that would be useful; but user agents should not use
  system-wide notification mechanisms to do so.</p>
  <p>When a <span>normal notification</span> (but not a
  <span>sandboxed notification</span>) is shown, the user agent may
  bring the user's attention to the <span>top-level browsing
  context</span> of the <span title="script's browsing
  context">browsing context</span> of the <span
  title="concept-script">script</span> that invoked the method, if
  that would be useful; but user agents should not use system-wide
  notification mechanisms to do so.</p>

  <p>When a <span>trusted notification</span> is shown, the user agent
  should bring the user's attention to the notification and the <span
  title="script's browsing context">browsing context</span> of the
  <span title="concept-script">script</span> that invoked the method,
  as per the platform conventions for attracting the user's attention
  to applications.</p>

  <p>When a <a href=#trusted-notification>trusted notification</a> is shown, the user agent
  should bring the user's attention to the notification and the <a href="#script's-browsing-context" title="script's browsing context">browsing context</a> of the
  <a href=#concept-script title=concept-script>script</a> that invoked the method, as per the platform conventions for
  attracting the user's attention to applications.</p>

  <div class=example>
  <div class="example">

   <p>In the case of <a href=#normal-notification title="normal notification">normal
   notifications</a>, typically the only attention-grabbing device
   <p>In the case of <span title="normal notification">normal
   notifications</span>, typically the only attention-grabbing device
   that would be employed would be something like flashing the tab's
   caption, or making it bold, or some such.</p>

   <p>In addition, in the case of a <a href=#trusted-notification>trusted notification</a>,
   <p>In addition, in the case of a <span>trusted notification</span>,
   the entire window could flash, or the browser's application icon
   could bounce or flash briefly, or a short sound effect could be
   played.</p>

  <p>Notifications should include the following content:</p>

  <ul><li>The <var title="">title</var>, <var title="">subtitle</var>,
  <ul>

   <li>The <var title="">title</var>, <var title="">subtitle</var>,
   and <var title="">description</var> strings passed to the
   method. They may be truncated or abbreviated if necessary.</li>

   <li>The <a href=#meta-application-name title=meta-application-name>application
   name</a>, if available, or else the <a href=#document.title title=dom-document-title>document title</a>, of the
   <a href=#active-document>active document</a> of the <a href="#script's-browsing-context" title="script's browsing
   context">browsing context</a> of the <a href=#concept-script title=concept-script>script</a> that invoked the
   method.</li>

   <li>An icon chosen from the <a href=#external-resource-link title="external resource
   link">external resource links</a> of type <code title=rel-icon><a href=#rel-icon>icon</a></code>, if any are available.</li>

  </ul><p>If a new notification from one <a href=#browsing-context>browsing context</a> has
  <var title="">title</var>, <var title="">subtitle</var>, and <var title="">description</var> strings that are identical to the <var title="">title</var>, <var title="">subtitle</var>, and <var title="">description</var> strings of an already-active notification
  from the same <a href=#browsing-context>browsing context</a> or another <a href=#browsing-context title="browsing context">browsing context</a> with the same
  <a href=#origin-0>origin</a>, the user agent should not display the new
   <li>The <span title="meta-application-name">application
   name</span>, if available, or else the <span
   title="dom-document-title">document title</span>, of the
   <span>active document</span> of the <span title="script's browsing
   context">browsing context</span> of the <span
   title="concept-script">script</span> that invoked the method.</li>

   <li>An icon chosen from the <span title="external resource
   link">external resource links</span> of type <code
   title="rel-icon">icon</code>, if any are available.</li>

  </ul>

  <p>If a new notification from one <span>browsing context</span> has
  <var title="">title</var>, <var title="">subtitle</var>, and <var
  title="">description</var> strings that are identical to the <var
  title="">title</var>, <var title="">subtitle</var>, and <var
  title="">description</var> strings of an already-active notification
  from the same <span>browsing context</span> or another <span
  title="browsing context">browsing context</span> with the same
  <span>origin</span>, the user agent should not display the new
  notification, but should instead add an indicator to the
  already-active notification that another identical notification
  would otherwise have been shown.</p>

  <div class=example>
  <div class="example">

   <p>For instance, if a user has his mail application open in three
   windows, and thus the same "New Mail" notification is fired three
  <p>Notifications should have a lifetime based on the platform
  conventions for notifications. However, the lifetime of a
  notification should not begin until the user has had the opportunity
  to see it, so if a notification is spawned for a <a href=#browsing-context>browsing
  context</a> that is hidden, it should be shown for its complete
  lifetime once the user brings that <a href=#browsing-context>browsing context</a>
  to see it, so if a notification is spawned for a <span>browsing
  context</span> that is hidden, it should be shown for its complete
  lifetime once the user brings that <span>browsing context</span>
  into view.</p>

  <p>User agents should support multiple notifications at once.</p>

  <p>User agents should support user interaction with notifications,
  if and as appropriate given the platform conventions. If a user
  activates a notification, and the <var title="">onclick</var>
  callback argument was present and is not null, then the <a href="#script's-browsing-context" title="script's browsing context">browsing context</a> of the
  <a href=#concept-script title=concept-script>script</a> of the function given by
  callback argument was present and is not null, then the <span
  title="script's browsing context">browsing context</span> of the
  <span title="concept-script">script</span> of the function given by
  <var title="">onclick</var> should be brought to the user's
  attention, and the <var title="">onclick</var> callback should then
  be invoked.</p>

-->


  <h3 id=system-state-and-capabilities><span class=secno>5.6 </span>System state and capabilities</h3>