mozilla

Revision 376635 of add

  • Revision slug: Extensions/Mobile/API/NativeWindow/menu/add
  • Revision title: add
  • Revision id: 376635
  • Created:
  • Creator: sriramramani
  • Is current revision? No
  • Comment A new syntax for "add" option

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
JSON 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.
  • 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.

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: null  
  ));  
}  

// 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(); },  
  });  
}

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>
    JSON 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.</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.</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>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>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: null &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;
}
</pre>
<h2 id="Specification" name="Specification">See Also</h2>
Revert to this revision