mozilla

Revision 501249 of add

  • Revision slug: Mozilla/Add-ons/Firefox_for_Android/API/NativeWindow/contextmenus/add
  • Revision title: add
  • Revision id: 501249
  • Created:
  • Creator: wbamberg
  • Is current revision? Yes
  • Comment Extensions/Mobile/API/NativeWindow/contextmenus/add Mozilla/Add-ons/Firefox_for_Android/API/NativeWindow/contextmenus/add

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.contextmenus.add() adds a new context menu item to Firefox for Android.

Syntax

var menuID = window.NativeWindow.contextmenus.add(name, selector, callback);

name
The string displayed by the context menu item. This takes either a String or Function object. Functions take the top-most element the context menu is being shown for as an argument. For instance, to show the host of a link that is tapped on as your context menu label, you could use:
function(aElement) {
  let uri = null;
  var node = aElement;
  while (node && !uri) {
    uri = NativeWindow.contextmenus._getLink(node);
    node = node.parentNode;
  }
  return uri ? uri.host : "No uri"
}
selector

This determines when the item should be shown. The contextmenus object defines a number of built-in selectors:

SelectorContext Initialized with a CSS selector, and displays the context menu item only if the selected page element matches the selector
linkOpenableContext Displays the context menu item only if the selected page element is any link that Firefox can open (meaning, any URI scheme except mailto://, javascript://, news://, or snews://
linkShareableContext Displays the context menu item only if the selected page element is a link that it makes sense to send to someone else (meaning, any URI scheme except chrome://, about://, file://, javascript://, or resource://)
linkBookmarkableContext Displays the context menu item only if the selected page element is a link that it makes sense to bookmark (meaning, any URI scheme except mailto://)
textContext Displays the context menu item only if the selected page element is a textarea element or an HTMLInputElement element that is a text field (meaning, that it has a type attribute of email, password, search, tel, text, or url)
imageSaveableContext Displays the context menu item only if the selected page element is an image that is loaded and can be saved.
You can create your own selector by passing in any object that has a function matches(element). This function:
  • takes a DOM element as a parameter
  • returns true if the context menu item should be shown, and false otherwise.
 
 
callback
The function to be called when the item is selected. It is passed the selected page element as a DOM element.

Returns

menuID: an identifier for the context menu item. This may be used to remove the item using NativeWindow.contextmenus.remove().

Example

This example adds a context menu item only when the selected element is a link pointing to "*.mozilla.*":

var menuID;

function loadIntoWindow(window) {    
  if (!window)    
    return;
  let label = "Show Text Content";
  let selector = {
    matches: function(element) {
      var domainParts = element.hostname.split(".");
      return (element.href && domainParts[domainParts.length - 2] == "mozilla");
    }
  }
  menuID = window.NativeWindow.contextmenus.add(label, selector, function(target) {      
    window.NativeWindow.toast.show(target.text, "short");       
  });    
}

This example uses the predefined SelectorContext to display the context menu item only if the selected element is the first item in a list:

var menuID;

function loadIntoWindow(window) {    
  if (!window)    
    return;
  let label = "Show List Item";
  let selector =  window.NativeWindow.contextmenus.SelectorContext("li:first-child");
  menuID = window.NativeWindow.contextmenus.add(label, selector, function(target) {      
    window.NativeWindow.toast.show(target.outerHTML, "short");       
  });
}    

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><a href="/en/Extensions/Mobile/API/NativeWindow/contextmenus" title="https://developer.mozilla.org/en/DOM/window.NativeWindow.contextmenus">NativeWindow.contextmenus</a>.add()</code> adds a new context menu item to <a href="/en/Mozilla/Firefox_for_Android" title="https://developer.mozilla.org/en/Mozilla/Firefox_for_Android">Firefox for Android</a>.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<p><code><em>var menuID = window.NativeWindow.contextmenus.add(name, selector, callback);</em></code></p>
<dl>
  <dt>
    <code>name</code></dt>
  <dd>
    The string displayed by the context menu item. This takes either a String or Function object. Functions take the top-most element the context menu is being shown for as an argument. For instance, to show the host of a link that is tapped on as your context menu label, you could use:</dd>
</dl>
<pre>
function(aElement) {
  let uri = null;
  var node = aElement;
  while (node &amp;&amp; !uri) {
    uri = NativeWindow.contextmenus._getLink(node);
    node = node.parentNode;
  }
  return uri ? uri.host : "No uri"
}
</pre>
<dl>
  <dt>
    <code>selector</code></dt>
  <dd>
    <p>This determines when the item should be shown. The <code>contextmenus</code> object defines a number of built-in selectors:</p>
    <table border="1" cellpadding="1" cellspacing="1" style="width: 100%;">
      <tbody>
        <tr>
          <td><span id="the-code"><span class="a"><code>SelectorContext</code></span></span></td>
          <td>Initialized with a CSS selector, and displays the context menu item only if the selected page element matches the selector</td>
        </tr>
        <tr>
          <td><code>linkOpenableContext</code></td>
          <td>Displays the context menu item only if the selected page element is any link that Firefox can open (meaning, any URI scheme except <code>mailto://</code>, <code>javascript://</code>, <code>news://</code>, or <code>snews://</code></td>
        </tr>
        <tr>
          <td><code>linkShareableContext</code></td>
          <td>Displays the context menu item only if the selected page element is a link that it makes sense to send to someone else (meaning, any URI scheme except <code>chrome://</code>, <code>about://</code>, <code>file://</code>, <code>javascript://</code>, or <code>resource://</code>)</td>
        </tr>
        <tr>
          <td><code>linkBookmarkableContext</code></td>
          <td>Displays the context menu item only if the selected page element is a link that it makes sense to bookmark (meaning, any URI scheme except <code>mailto://</code>)</td>
        </tr>
        <tr>
          <td><code>textContext</code></td>
          <td>Displays the context menu item only if the selected page element is a <a href="/en/HTML/HTML_Elements/textarea" title="https://developer.mozilla.org/en/HTML/Element/textarea"><code>textarea</code></a> element or an <a href="/en/DOM/HTMLInputElement" title="https://developer.mozilla.org/en/DOM/HTMLInputElement"><code>HTMLInputElement</code></a> element that is a text field (meaning, that it has a <a href="/en/HTML/Element/Input#attr-type" title="https://developer.mozilla.org/en/HTML/Element/input#attr-type"><code>type</code></a> attribute of <code>email</code>, <code>password</code>, <code>search</code>, <code>tel</code>, <code>text</code>, or <code>url</code>)</td>
        </tr>
        <tr>
          <td><code>imageSaveableContext</code></td>
          <td>Displays the context menu item only if the selected page element is an image that is loaded and can be saved.</td>
        </tr>
      </tbody>
    </table>
  </dd>
  <dd>
    You can create your own selector by passing in any object that has a function <code>matches(element)</code>. This function:
    <ul>
      <li>takes a <a href="/en/DOM/element" title="https://developer.mozilla.org/en/DOM/element">DOM element</a> as a parameter</li>
      <li>returns <code>true</code> if the context menu item should be shown, and <code>false</code> otherwise.</li>
    </ul>
  </dd>
  <dt>
    &nbsp;</dt>
  <dt>
    &nbsp;</dt>
  <dt>
    <code>callback</code></dt>
  <dd>
    The function to be called when the item is selected. It is passed the selected page element as a <a href="/en/DOM/element" title="https://developer.mozilla.org/en/DOM/element">DOM element</a>.</dd>
</dl>
<h3 id="Returns" name="Returns">Returns</h3>
<p><code>menuID</code>: an identifier for the context menu item. This may be used to remove the item using <code>NativeWindow.contextmenus.remove().</code></p>
<h2 id="Example" name="Example">Example</h2>
<p>This example adds a context menu item only when the selected element is a link pointing to "*.mozilla.*":</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 Text Content";
&nbsp; let selector = {
&nbsp;&nbsp;&nbsp; matches: function(element) {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; var domainParts = element.hostname.split(".");
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return (element.href &amp;&amp; domainParts[domainParts.length - 2] == "mozilla");
&nbsp;&nbsp;&nbsp; }
&nbsp; }
&nbsp; menuID = window.NativeWindow.contextmenus.add(label, selector, function(target) {&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp; window.NativeWindow.toast.show(target.text, "short");&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;
&nbsp; });&nbsp;&nbsp; &nbsp;
}
</pre>
<p>This example uses the predefined <code>SelectorContext</code> to display the context menu item only if the selected element is the first item in a list:</p>
<pre class="brush: js">
var menuID;

function loadIntoWindow(window) {    
  if (!window)    
    return;
  let label = "Show List Item";
  let selector =  window.NativeWindow.contextmenus.SelectorContext("li:first-child");
  menuID = window.NativeWindow.contextmenus.add(label, selector, function(target) {      
    window.NativeWindow.toast.show(target.outerHTML, "short");       
  });
}    
</pre>
<h2 id="Specification" name="Specification">See Also</h2>
Revert to this revision