Mobile/Fennec/Extensions/UserInterface/Context Menu: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(new)
 
m (minor fixes)
Line 16: Line 16:
== Target types ==
== Target types ==


The '''type''' attribute contains a space-delimited list of type names.  If the the element that the user touches matches any of the included types, then the menu item will be displayed.  Otherwise  
The '''type''' attribute contains a space-delimited list of type names.  If the the target element (the page element the user touched) matches any of the included types, then the menu item will be visible.  Otherwise it will be hidden.


The available types are:
The available types are:
Line 27: Line 27:
; video: (new in Fennec 2.0b1) A <video> element.
; video: (new in Fennec 2.0b1) A <video> element.
; link-saveable: (new in Fennec 2.0a1) Any link type except mailto:, javascript:, and news:.
; link-saveable: (new in Fennec 2.0a1) Any link type except mailto:, javascript:, and news:.
; link-shareable, image-shareable, video-shareable: (new in Fennec 2.0a1): Any link type except chrome:, about:, file:, javascript:, or resource:.
; link-shareable, image-shareable, video-shareable: (new in Fennec 2.0a1) Any link type except chrome:, about:, file:, javascript:, or resource:.
 
== Adding new target types ==


'''New in Fennec 2.0a1:''' If the built-in types do not work for your add-on,
'''New in Fennec 2.0a1:''' If the built-in types do not work for your add-on,
Line 38: Line 40:
the target DOM element.  It can modify the popupState to add new data that
the target DOM element.  It can modify the popupState to add new data that
will be passed to the commands' onclick handlers (see below).  The callback
will be passed to the commands' onclick handlers (see below).  The callback
can return ''true'' if the element "matches" the new type, or ''false''
can return ''true'' if the target element "matches" the new type, or ''false''
otherwise.
otherwise.


Line 67: Line 69:


  ShowTitle.onclick = function() {
  ShowTitle.onclick = function() {
  var state = ContextHelper.popupState || ContextHelper.popupNode;
   var text = ContextHelper.popupNode.title || ContextHelper.popupNode.title || 'no text';
   var text = ContextHelper.popupNode.title || ContextHelper.popupNode.title || 'no text';
   setTimeout(function() {
   setTimeout(function() {
Line 77: Line 78:
  };
  };


Here is a reference to the ContextHelper API:
=== ContextHelper properties ===


'''Fennec 1.1'''
==== Fennec 1.1 ====


; ContextHelper.popupNode: The DOM element that received the long-tap gesture.
; ContextHelper.popupNode: The DOM element that received the long-tap gesture.
; ContextHelper.linkURL: The address of the link.
; ContextHelper.linkURL: The address of the link.
; ContextHelper.mediaURL: The address of the image.
; ContextHelper.mediaURL: The address of the image.
; ContextHelper.onSaveableLink: (boolean) true if the link is not a javascript/mailto/news link.
; ContextHelper.popupState.linkProtocol: The URI scheme of the link address.
; ContextHelper.onSaveableLink: ''true'' if the link is not a javascript/mailto/news link.


'''Fennec 2.0'''
==== Fennec 2.0 ====


; ContextHelper.popupState: An object containing more information about the target element.
; ContextHelper.popupState: An object containing more information about the target element.
Line 92: Line 94:
; ContextHelper.popupState.label: A string describing the target element.
; ContextHelper.popupState.label: A string describing the target element.
; ContextHelper.popupState.linkTitle: The text of the link.
; ContextHelper.popupState.linkTitle: The text of the link.
; ContextHelper.popupState.linkURL: The address of the link (or null).
; ContextHelper.popupState.linkURL: The address of the link.
; ContextHelper.popupState.linkProtocol: The URI scheme of the link href (or null).
; ContextHelper.popupState.linkProtocol: The URI scheme of the link address.
; ContextHelper.popupState.mediaURL: The image's src address (or null).
; ContextHelper.popupState.mediaURL: The image or video's source address.


== Sample Code ==
== Sample Code ==


* [http://bitbucket.org/mbrubeck/showtitle/src/tip/content/ Show Image Title source code]
* [http://bitbucket.org/mbrubeck/showtitle/src/tip/content/ Show Image Title source code]

Revision as of 20:25, 2 September 2010

fennec-contextpanel-02-300x239.png

The context menu appears when a user does a "long tap" (touch and hold) on a link, image, or other page/UI element. See Mark Finkle's blog post for more details.

To add a new command to the context menu, add a richlistitem element to the #context-commands list. For example, the Show Image Title add-on uses a XUL overlay like this:

 <richlistbox id="context-commands">
   <richlistitem id="showtitle-context-command"
                 class="context-command"
                 type="image"
                 onclick="ShowTitle.onclick();">
     <label value="Show Title"/>
   </richlistitem>
 </richlistbox>

Target types

The type attribute contains a space-delimited list of type names. If the the target element (the page element the user touched) matches any of the included types, then the menu item will be visible. Otherwise it will be hidden.

The available types are:

image
An image (<img>) element.
image-loaded
An image that has finished loading succesfully.
link
A link (<a href="...">) element.
mailto
A link to a mailto: URI.
callto
A link to a telphone URI (callto:, tel:, sip:, or voipto:).
video
(new in Fennec 2.0b1) A <video> element.
link-saveable
(new in Fennec 2.0a1) Any link type except mailto:, javascript:, and news:.
link-shareable, image-shareable, video-shareable
(new in Fennec 2.0a1) Any link type except chrome:, about:, file:, javascript:, or resource:.

Adding new target types

New in Fennec 2.0a1: If the built-in types do not work for your add-on, you can use ContextHandler.registerType to add one of your own:

 ContextHandler.registerType(name, callback); // Requires Fennec 2.0a1 or higher

registerType takes two arguments: the type name (a string), and a callback function. The callback should take two arguments: the popupState object and the target DOM element. It can modify the popupState to add new data that will be passed to the commands' onclick handlers (see below). The callback can return true if the target element "matches" the new type, or false otherwise.

ContextHandler.registerType must be called in the content process using a loadFrameScript.

For example, if we want to change the "Show Image Title" example above to show the menu item only for images that actually have titles, then we could change type="image" to type="show-title" in the XUL, and add the following code in a content script:

 ContextHandler.registerType("show-title", function(popupState, element) {
   if (element.title) {
     popupState.title = element.title;
     return true;
   }
   // Otherwise, do not show commands with type="show-title":
   return false;
 });

Handling context command clicks

When the user taps a context command, its onclick handler is called. This handler can use the ContextHelper object to get more information about the element that was the target of the long-tap gesture.

ContextHelper is changing in Fennec 2.0. The "popupNode" property is no longer accessible because of Electrolysis, so it is replaced by the new "popupState" object.

The "Show Image Title" example above uses a handler like this, which works in both 1.1 and 2.0:

ShowTitle.onclick = function() {
  var text = ContextHelper.popupNode.title || ContextHelper.popupNode.title || 'no text';
  setTimeout(function() {
    var promptService =
      Components.classes['@mozilla.org/embedcomp/prompt-service;1'].
        getService(Components.interfaces.nsIPromptService);
    promptService.alert(null, 'Image Title', text);
  }, 0);
};

ContextHelper properties

Fennec 1.1

ContextHelper.popupNode
The DOM element that received the long-tap gesture.
ContextHelper.linkURL
The address of the link.
ContextHelper.mediaURL
The address of the image.
ContextHelper.popupState.linkProtocol
The URI scheme of the link address.
ContextHelper.onSaveableLink
true if the link is not a javascript/mailto/news link.

Fennec 2.0

ContextHelper.popupState
An object containing more information about the target element.
ContextHelper.popupState.types
An array of the type names that the target element matched.
ContextHelper.popupState.label
A string describing the target element.
ContextHelper.popupState.linkTitle
The text of the link.
ContextHelper.popupState.linkURL
The address of the link.
ContextHelper.popupState.linkProtocol
The URI scheme of the link address.
ContextHelper.popupState.mediaURL
The image or video's source address.

Sample Code