Revision 439457 of add

  • Revision slug: Extensions/Mobile/API/NativeWindow/menu/add
  • Revision title: add
  • Revision id: 439457
  • Created:
  • Creator: MarkFinkle
  • 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.menu.add() adds a new item to the main menu in Firefox for Android. By specifying an optional parent attribute, a menu item can be added to the sub menu of the parent.

Syntax

var menuID = window.NativeWindow.menu.add(options);

Available from version 20.

options
Javascript object specifying a set of attributes for the item. The current set of supported options are:
  • name - The string displayed by the menu item.
  • icon - An icon to display next to the item's name, specified as a file:// or data: URI. To add a menu item without an icon, supply null here. If you need to specify a chrome:// or resource:// url you need to resolve it to a file://. See example below.
  • callback - The function to be called when the item is selected. It is called with no arguments.
  • checkable - Boolean specifying whether the item should be checkable.
  • parent - The ID of the parent menu item which will show this menu item in a submenu. This argument is needed only if the menu item has to be displayed inside a submenu.
 

var menuID = window.NativeWindow.menu.add(name, icon, callback);

Deprecated as of version 20.

name
The string displayed by the menu item.
icon

An icon to display next to the item's name, specified as a file:// or data: URI. To add a menu item without an icon, supply null here. If you need to specify a chrome:// or resource:// url you need to resolve it to a file://. See example below.

callback
The function to be called when the item is selected. It is called with no arguments.

Returns

menuID
An identifier for the menu item. This may be used to remove the item using NativeWindow.menu.remove().

Example

Example 1: Main level menu item

The following example adds a menu item with the name "Show Toast," which displays a toast notification when clicked:

function showToast(window) {  
  window.NativeWindow.toast.show("Showing you a toast", "short");  
}  
 
var menuID;  

// Available since version 20.
function addMenuItem(window) {  
  menuID = window.NativeWindow.menu.add({  
    name: "Show Toast",  
    icon: null,  
    callback: function(){  
      showToast(window);   
    }  
  ));  
}  

// Deprecated syntax as of version 20.
function addMenuItem(window) {  
  menuID = window.NativeWindow.menu.add("Show Toast", null, function(){  
    showToast(window);   
  });  
}
 
function removeMenuItem(window) {  
  window.NativeWindow.menu.remove(menuID);  
}

Example 2: Menu item with a submenu

The following example adds a menu item with the name "Rotate Phone" which displays a sub menu with two options when clicked:

var parentID;  
var leftID;  
var rightID;  

function addMenuItem(window) {  
  parentID = window.NativeWindow.menu.add({  
    name: "Rotate Phone",  
    icon: resolveGeckoURI("chrome://yourAddonName/content/images/icon.ico"); 
  ));  
}  

// Add submenu.  
function addSubMenuItems(window, parent) {  
  leftID = window.NativeWindow.menu.add({  
    name: "Left",  
    parent: parentID,  
    callback: function() { rotateLeft(); },  
  });  

  rightID = window.NativeWindow.menu.add({  
    name: "Right",  
    parent: parentID,  
    callback: function() { rotateRight(); },  
  });  
}

function resolveGeckoURI(aURI) {
    Components.utils.import("resource://gre/modules/Services.jsm");
    
    if (aURI.startsWith("chrome://"))
    {
        let registry = Cc['@mozilla.org/chrome/chrome-registry;1'].getService(Ci["nsIChromeRegistry"]);
        return registry.convertChromeURL(Services.io.newURI(aURI, null, null)).spec;
    }
    else if (aURI.startsWith("resource://")) {
        let handler = Services.io.getProtocolHandler("resource").QueryInterface(Ci.nsIResProtocolHandler);
        return handler.resolveURI(Services.io.newURI(aURI, null, null));
    }
    return aURI;
}

See Also

Revision Source

<div class="note">
  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.</div>
<h2 id="Summary" name="Summary">Summary</h2>
<p><code>NativeWindow.menu.add()</code> adds a new item to the main menu in <a href="/en/Mozilla/Firefox_for_Android" title="https://developer.mozilla.org/en/Mozilla/Firefox_for_Android">Firefox for Android</a>. By specifying an optional <code>parent</code> attribute, a menu item can be added to the sub menu of the parent.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<p><code><em>var menuID = window.NativeWindow.menu.add(options);</em></code></p>
<div class="geckoVersionNote">
  <p><strong><code><em>Available from version 20.</em></code></strong></p>
</div>
<dl>
  <dt>
    <code>options</code></dt>
  <dd>
    Javascript object specifying a set of attributes for the item. The current set of supported options are:
    <ul>
      <li><code>name</code> - The string displayed by the menu item.</li>
      <li><code>icon</code> - An icon to display next to the item's name, specified as a <code>file://</code> or <code>data:</code> URI. To add a menu item without an icon, supply <code>null</code> here. If you need to specify a chrome:// or resource:// url you need to resolve it to a file://. See example below.</li>
      <li><code>callback</code> - The function to be called when the item is selected. It is called with no arguments.</li>
      <li><code>checkable</code> - Boolean specifying whether the item should be checkable.</li>
      <li><code>parent</code> - The ID of the parent menu item which will show this menu item in a submenu. This argument is needed only if the menu item has to be displayed inside a submenu.</li>
    </ul>
  </dd>
  <dt>
    &nbsp;</dt>
</dl>
<p><code><em>var menuID = window.NativeWindow.menu.add(name, icon, callback); </em></code></p>
<div class="geckoVersionNote">
  <p><strong><code><em>Deprecated as of version 20.</em></code></strong></p>
</div>
<dl>
  <dt>
    <code>name</code></dt>
  <dd>
    The string displayed by the menu item.</dd>
  <dt>
    <code>icon</code></dt>
  <dd>
    <p>An icon to display next to the item's name, specified as a <code>file://</code> or <code>data:</code> URI. To add a menu item without an icon, supply <code>null</code> here. If you need to specify a chrome:// or resource:// url you need to resolve it to a file://. See example below.</p>
  </dd>
  <dt>
    <code>callback</code></dt>
  <dd>
    The function to be called when the item is selected. It is called with no arguments.</dd>
</dl>
<h2 id="Returns" name="Returns">Returns<span id="cke_bm_115S" style="display: none;"> </span></h2>
<dl>
  <dt>
    menuID</dt>
  <dd>
    An identifier for the menu item. This may be used to remove the item using <code>NativeWindow.menu.remove().</code><span id="cke_bm_115E" style="display: none;">&nbsp;</span></dd>
</dl>
<h2 id="Example" name="Example">Example</h2>
<h3 id="Example_1.3A_Main_level_menu_item">Example 1: Main level menu item</h3>
<p>The following example adds a menu item with the name "Show Toast," which displays a toast notification when clicked:</p>
<pre class="brush: js">
function showToast(window) { &nbsp;
&nbsp; window.NativeWindow.toast.show("Showing you a toast", "short"); &nbsp;
} &nbsp;
&nbsp;
var menuID; &nbsp;

// Available since version 20.
function addMenuItem(window) { &nbsp;
&nbsp; menuID = window.NativeWindow.menu.add({ &nbsp;
&nbsp;&nbsp;&nbsp; name: "Show Toast", &nbsp;
&nbsp;&nbsp;&nbsp; icon: null, &nbsp;
&nbsp;&nbsp;&nbsp; callback: function(){ &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; showToast(window);&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp; } &nbsp;
&nbsp; )); &nbsp;
} &nbsp;

// Deprecated syntax as of version 20.
function addMenuItem(window) { &nbsp;
&nbsp; menuID = window.NativeWindow.menu.add("Show Toast", null, function(){ &nbsp;
&nbsp;&nbsp;&nbsp; showToast(window);&nbsp; &nbsp;
&nbsp; }); &nbsp;
}
&nbsp;
function removeMenuItem(window) { &nbsp;
&nbsp; window.NativeWindow.menu.remove(menuID); &nbsp;
}
</pre>
<h3 id="Example_2.3A_Menu_item_with_a_submenu">Example 2: Menu item with a submenu</h3>
<p>The following example adds a menu item with the name "Rotate Phone" which displays a sub menu with two options when clicked:</p>
<pre class="brush: js">
var parentID; &nbsp;
var leftID; &nbsp;
var rightID; &nbsp;

function addMenuItem(window) { &nbsp;
&nbsp; parentID = window.NativeWindow.menu.add({ &nbsp;
&nbsp;&nbsp;&nbsp; name: "Rotate Phone", &nbsp;
&nbsp;&nbsp;&nbsp; icon: resolveGeckoURI("chrome://yourAddonName/content/images/icon.ico");&nbsp;
&nbsp; )); &nbsp;
} &nbsp;

// Add submenu. &nbsp;
function addSubMenuItems(window, parent) { &nbsp;
&nbsp; leftID = window.NativeWindow.menu.add({ &nbsp;
&nbsp;&nbsp;&nbsp; name: "Left", &nbsp;
&nbsp;&nbsp;&nbsp; parent: parentID, &nbsp;
&nbsp;&nbsp;&nbsp; callback: function() { rotateLeft(); }, &nbsp;
&nbsp; }); &nbsp;

&nbsp; rightID = window.NativeWindow.menu.add({ &nbsp;
&nbsp;&nbsp;&nbsp; name: "Right", &nbsp;
&nbsp;&nbsp;&nbsp; parent: parentID, &nbsp;
&nbsp;&nbsp;&nbsp; callback: function() { rotateRight(); }, &nbsp;
&nbsp; }); &nbsp;
}

function resolveGeckoURI(aURI) {
&nbsp;&nbsp; &nbsp;Components.utils.import("resource://gre/modules/Services.jsm");
&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp; &nbsp;if (aURI.startsWith("chrome://"))
&nbsp;&nbsp; &nbsp;{
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;let registry = Cc['@mozilla.org/chrome/chrome-registry;1'].getService(Ci["nsIChromeRegistry"]);
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;return registry.convertChromeURL(Services.io.newURI(aURI, null, null)).spec;
&nbsp;&nbsp; &nbsp;}
&nbsp;&nbsp; &nbsp;else if (aURI.startsWith("resource://")) {
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;let handler = Services.io.getProtocolHandler("resource").QueryInterface(Ci.nsIResProtocolHandler);
&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;return handler.resolveURI(Services.io.newURI(aURI, null, null));
&nbsp;&nbsp; &nbsp;}
&nbsp;&nbsp; &nbsp;return aURI;
}
</pre>
<h2 id="Specification" name="Specification">See Also</h2>
Revert to this revision