contextmenus

  • Revision slug: Mozilla/Add-ons/Firefox_for_Android/API/NativeWindow/contextmenus
  • Revision title: contextmenus
  • Revision id: 501245
  • Created:
  • Creator: wbamberg
  • Is current revision? Yes
  • Comment Editorial reviewMoved From Extensions/Mobile/API/NativeWindow/contextmenus to Mozilla/Add-ons/Firefox_for_Android/API/NativeWindow/contextmenus

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

Returns a reference to the NativeWindow.contextmenus object, which can be used to add items to the Firefox for Android context menu, and subsequently remove them. You can add a menu item to the context menu using NativeWindow.contextmenus.add() and remove it using NativeWindow.contextmenus.remove().

To add a context menu item, you need to supply:

  • name : the name of the item that is displayed to the user
  • selector : determines when the item should be shown. You can use one of a number of predefined selectors, or define your own.
  • callback : a function that is called when the item is selected

NativeWindow.contextmenus.add() returns a menuID which you can subsequently pass into NativeWindow.contextmenus.remove() to remove the item.

A common pattern is for a restartless add-on to add and remove menu items in the add-on's bootstrap.js:

This ensures that the item is always present while the add-on is installed and enabled, and that it is cleaned up properly when the add-on is uninstalled or disabled. But note that bootstrap.js is not attached to a DOM window, so you need to get a window, for example using nsIWindowMediator, before you can use this pattern.

ExampleNativeWindow-contextmenus.png

The following example adds a context menu item which is displayed when any element is selected. When the user selects the context menu item, it displays the HTML source for the element in a toast notification:

var menuID;

function loadIntoWindow(window) {    
  if (!window)    
    return;
  let label = "Show HTML";
  let selector =  window.NativeWindow.contextmenus.SelectorContext("*");
  menuID = window.NativeWindow.contextmenus.add(label, selector, function(target) {      
    window.NativeWindow.toast.show(target.outerHTML, "short");       
  });    
}    
   
function unloadFromWindow(window) {    
  if (!window)    
    return;    
  window.NativeWindow.contextmenus.remove(menuID);      
}

Methods

add
Add a context menu item.
remove
Remove a context menu item.

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">Summary</h2>
<p>Returns a reference to the <code><a href="/en/Extensions/Mobile/API/NativeWindow" title="https://developer.mozilla.org/en/DOM/window.NativeWindow">NativeWindow</a>.contextmenus</code> object, which can be used to add items to the <a href="/en/Mozilla/Firefox_for_Android" title="en/Mozilla/Firefox_for_Android">Firefox for Android</a> context menu, and subsequently remove them. You can add a menu item to the context menu using <code>NativeWindow.contextmenus.add()</code> and remove it using <code>NativeWindow.</code><code>contextmenus</code><code>.remove()</code>.</p>
<p>To add a context menu item, you need to supply:</p>
<ul>
  <li><code>name</code> : the name of the item that is displayed to the user</li>
  <li><code>selector</code> : determines when the item should be shown. You can use one of a number of predefined selectors, or define your own.</li>
  <li><code>callback</code> : a function that is called when the item is selected</li>
</ul>
<p><code>NativeWindow.contextmenus.add() </code>returns a <code>menuID</code> which you can subsequently pass into <code>NativeWindow.contextmenus.remove()</code> to remove the item.</p>
<p>A common pattern is for a <a href="/en/Extensions/Bootstrapped_extensions" title="https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions">restartless</a> add-on to add and remove menu items in the add-on's <code>bootstrap.js</code>:</p>
<ul>
  <li>from the <a href="/en/Extensions/Bootstrapped_extensions#startup%28%29" title="https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions#startup%28%29"><code>startup()</code> function</a>, enumerate windows using <a href="/en/XPCOM_Interface_Reference/nsIWindowMediator" title="https://developer.mozilla.org/en/nsIWindowMediator">nsIWindowMediator</a> and add any menu items needed</li>
  <li>from the <a href="/en/Extensions/Bootstrapped_extensions#shutdown%28%29" title="https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions#shutdown%28%29"><code>shutdown()</code> function</a>, enumerate windows using <a href="/en/XPCOM_Interface_Reference/nsIWindowMediator" title="https://developer.mozilla.org/en/nsIWindowMediator">nsIWindowMediator</a> and remove any menu items added</li>
</ul>
<p>This ensures that the item is always present while the add-on is installed and enabled, and that it is cleaned up properly when the add-on is uninstalled or disabled. But note that <code>bootstrap.js</code> is not attached to a DOM window, so you need to get a window, for example using <a href="/en/XPCOM_Interface_Reference/nsIWindowMediator" title="https://developer.mozilla.org/en/nsIWindowMediator">nsIWindowMediator</a>, before you can use this pattern.</p>
<h2 id="Example">Example<a href="/@api/deki/files/6334/=NativeWindow-contextmenus.png" title="NativeWindow-contextmenus.png"><img align="right" alt="NativeWindow-contextmenus.png" class="internal rwrap" src="/@api/deki/files/6334/=NativeWindow-contextmenus.png?size=webview" style="width: 338px; height: 550px;" /></a></h2>
<p>The following example adds a context menu item which is displayed when any element is selected. When the user selects the context menu item, it displays the HTML source for the element in a toast notification:</p>
<pre class="brush: js">
var menuID;

function loadIntoWindow(window) {&nbsp;&nbsp; &nbsp;
&nbsp; if (!window)&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp; return;
&nbsp; let label = "Show HTML";
&nbsp; let selector =&nbsp; window.NativeWindow.contextmenus.SelectorContext("*");
&nbsp; menuID = window.NativeWindow.contextmenus.add(label, selector, function(target) {&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp; window.NativeWindow.toast.show(target.outerHTML, "short");&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;
&nbsp; });&nbsp;&nbsp; &nbsp;
}&nbsp;&nbsp; &nbsp;
&nbsp; &nbsp;
function unloadFromWindow(window) {&nbsp;&nbsp; &nbsp;
&nbsp; if (!window)&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp; return;&nbsp;&nbsp; &nbsp;
&nbsp; window.NativeWindow.contextmenus.remove(menuID);&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;
}</pre>
<h2 id="Methods">Methods</h2>
<dl>
  <dt>
    <a href="/en/Extensions/Mobile/API/NativeWindow/contextmenus/add" title="en/Extensions/Mobile/API/NativeWindow/contextmenus/add">add</a></dt>
  <dd>
    Add a context menu item.</dd>
  <dt>
    <a href="/en/Extensions/Mobile/API/NativeWindow/contextmenus/remove" title="en/Extensions/Mobile/API/NativeWindow/contextmenus/remove/">remove</a></dt>
  <dd>
    Remove a context menu item.</dd>
</dl>
<h2 id="See_also">See also</h2>
Revert to this revision