Revision 493927 of show

  • Revision slug: Extensions/Mobile/API/NativeWindow/doorhanger/show
  • Revision title: show
  • Revision id: 493927
  • Created:
  • Creator: Don.Dominic.mathew
  • Is current revision? No
  • Comment

Revision Content

The NativeWindow object is only available to privileged code running on Firefox for Android, and is intended for use by Firefox for Android add-ons.

Summary

NativeWindow.doorhanger.show() displays a doorhanger attached to a Firefox for Android tab.

Syntax

NativeWindow.doorhanger.show(message, value, buttons, tabID, options);

message
The message displayed in the doorhanger.
value

This is a string-based tag for the doorhanger, used as an argument to NativeWindow.doorhanger.hide().

buttons
This is an array of button objects, once for each choice to offer the user. Each button has two attributes:
  • label: a string to display on the button
  • callback: a function that will be called when the button is selected
tabID

The ID of the tab the doorhanger should be attached to. You can retrieve the tabID using the BrowserApp object: for example, window.BrowserApp.selectedTab.id returns the ID of the active tab.

options
Additional options for the doorhanger. Two options are currently defined:
  • timeout: a time in milliseconds. The notification will not automatically dismiss before this time.
  • persistence: an integer. The notification will not automatically dismiss for this many page loads. If persistence is set to -1, the doorhanger will never automatically dismiss.

Example

In the example below, an add-on adds a new menu item labeled "Offer cake" which constructs and shows a new doorhanger when selected.

The doorhanger contains two buttons, which just show different toast messages when selected.

var menuID;  
 
function offerCake(window) {  
  let buttons = [  
    {  
      label: "Yes, please!",  
      callback: function () {  
        window.NativeWindow.toast.show("yum", "short");  
      }  
    },  
    {  
      label: "Not today",  
      callback: function () {  
        window.NativeWindow.toast.show("still hungry", "short");  
      }  
    }  
  ];  
 
  let message = "How about some cake?";  
  let options = {  
    persistence: 1  
  };  
 
  window.NativeWindow.doorhanger.show(message, "cake-request", buttons, window.BrowserApp.selectedTab.id, options);  
}  
 
function loadIntoWindow(window) {  
  if (!window)  
    return;  
  menuID = window.NativeWindow.menu.add("Offer cake", null, function(){    
    offerCake(window);     
  });  
}  
 
function unloadFromWindow(window) {  
  if (!window)  
    return;  
  window.NativeWindow.menu.remove(menuID);    
}

See Also

Revision Source

<div class="note">
  The <a href="/en/Extensions/Mobile/API/NativeWindow" title="https://developer.mozilla.org/en/DOM/window.NativeWindow">NativeWindow</a> object is only available to privileged code running on Firefox for Android, and is intended for use by Firefox for Android add-ons.</div>
<h2 id="Summary" name="Summary">Summary</h2>
<p><code><a href="/en/Extensions/Mobile/API/NativeWindow/doorhanger" title="https://developer.mozilla.org/en/DOM/window.NativeWindow.doorhanger">NativeWindow.doorhanger</a>.show()</code> displays a doorhanger attached to a <a href="/en/Mozilla/Firefox_for_Android" title="https://developer.mozilla.org/en/Mozilla/Firefox_for_Android">Firefox for Android</a> tab.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<p><em><code>NativeWindow.doorhanger.show(message, value, buttons, tabID, options);</code></em></p>
<dl>
  <dt>
    <code>message</code></dt>
  <dd>
    The message displayed in the doorhanger.</dd>
  <dt>
    <code>value</code></dt>
  <dd>
    <p>This is a string-based tag for the doorhanger, used as an argument to <em><code>NativeWindow.doorhanger.hide()</code></em>.</p>
  </dd>
  <dt>
    <code>buttons</code></dt>
  <dd>
    This is an array of button objects, once for each choice to offer the user. Each button has two attributes:
    <ul>
      <li><code>label</code>: a string to display on the button</li>
      <li><code>callback</code>: a function that will be called when the button is selected</li>
    </ul>
  </dd>
  <dt>
    <code>tabID</code></dt>
  <dd>
    <p>The ID of the tab the doorhanger should be attached to. You can retrieve the tabID using the <code>BrowserApp</code> object: for example, <span><span><code>window.BrowserApp.selectedTab.id</code> returns the ID of the active tab.</span></span></p>
  </dd>
  <dt>
    <code>options</code></dt>
  <dd>
    Additional options for the doorhanger. Two options are currently defined:
    <ul>
      <li><code>timeout</code>:<span id="the-code"><span class="c"> a time in milliseconds. The notification will not</span><span class="c"> automatically dismiss before this time.</span></span></li>
      <li><code>persistence</code>: an integer. The notification will not automatically dismiss for this many page loads. If persistence is set to -1, the doorhanger will never automatically dismiss.</li>
    </ul>
  </dd>
</dl>
<h2 id="Example" name="Example">Example</h2>
<p>In the example below, an add-on adds a new menu item labeled "Offer cake" which constructs and shows a new doorhanger when selected.</p>
<p>The doorhanger contains two buttons, which just show different toast messages when selected.</p>
<pre class="brush: js">var menuID;  
 
function offerCake(window) {  
  let buttons = [  
    {  
      label: "Yes, please!",  
      callback: function () {  
        window.NativeWindow.toast.show("yum", "short");  
      }  
    },  
    {  
      label: "Not today",  
      callback: function () {  
        window.NativeWindow.toast.show("still hungry", "short");  
      }  
    }  
  ];  
 
  let message = "How about some cake?";  
  let options = {  
    persistence: 1  
  };  
 
  window.NativeWindow.doorhanger.show(message, "cake-request", buttons, window.BrowserApp.selectedTab.id, options);  
}  
 
function loadIntoWindow(window) {  
  if (!window)  
    return;  
  menuID = window.NativeWindow.menu.add("Offer cake", null, function(){    
    offerCake(window);     
  });  
}  
 
function unloadFromWindow(window) {  
  if (!window)  
    return;  
  window.NativeWindow.menu.remove(menuID);    
}
</pre>
<h2 id="Specification" name="Specification">See Also</h2>
Revert to this revision