Context Menu

The contextmenu namespace provides the facility to interact with the context menu api to control whether context menus are enabled, listen to events, add items to appear based on the context, and set the theme of the context menu.

Context Menu

Webworks applications can choose to use an in app contextmenu as opposed to the default operating system menu. The contextmenu provides several facilities to developers to allow them to control the elements that appear in the menu, as well as listen to specific events related to the context menu being triggered and displayed.

Enabling

The contextmenu can be enabled by calling the blackberry.ui.contextmenu.enabled property. When set to true, the contextmenu will capture the context menu events, and pass any events that the user has registered for. When set to false the contextmenu will default to the system, and the developer will have no access to the events described below.


Supported Platform(s)

- BlackBerry 10
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.ui.contextmenu.addItem           YY
blackberry.ui.contextmenu.defineCustomContext           YY
blackberry.ui.contextmenu.removeItem           YY
enabled             
CONTEXT_ALL           YY
CONTEXT_LINK           YY
CONTEXT_IMAGE           YY
CONTEXT_IMAGE_LINK           YY
CONTEXT_INPUT           YY
CONTEXT_TEXT           YY
ACTION_CANCEL           YY
ACTION_CLEAR_FIELD           YY
ACTION_COPY           YY
ACTION_COPY_IMAGE_LINK           YY
ACTION_COPY_LINK           YY
ACTION_CUT           YY
INSPECT_ELEMENT           YY
ACTION_OPEN_LINK           YY
ACTION_PASTE           YY
ACTIONE_SAVE_IMAGE           YY
ACTION_SAVE_LINK_AS           YY
ACTION_SELECT           YY
ACTION_VIEW_IMAGE           YY

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.ui.contextmenu" />           YY

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions

static void blackberry.ui.contextmenu.addItem (contexts : String[], action : Object, callback: function())


Allows the developer to add custom items to the context menu. The items will be appended to the end of the list of operating system defined functions. Developers must provide the following parameters to successfully add items to the context menu.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
contexts An array of constants defining which contexts this new item should appear.
action An object which defines the menu item to be added.

actionId: A property that uniquely defines the action to be added to the context menu.
label: A string that will be displayed to the user describing the custom context to be performed. ie: Edit
icon: A path to the an image to display in the context menu
callback A function which runs when the menu item action is executed

Code Example: 
<script type="text/javascript">

function addMyItem() {
    var myItem = {actionId: 'MyItem', label: 'My Item', icon:'http://mysite.com/icon.png'},
        contexts = [blackberry.ui.contextmenu.CONTEXT_IMAGE, blackberry.ui.contextmenu.CONTEXT_INPUT];
    blackberry.ui.contextmenu.addItem(contexts, myItem, function() { console.log('hi') });
}


 //Override the system Copy action by actionId using the ACTION_COPY constant
 function overridePlatformWithIcon() {
  var myItem = {actionId: blackberry.ui.contextmenu.ACTION_COPY, label: 'Custom Copy!',
      icon:'local:///icon.png'},
      contexts = [blackberry.ui.contextmenu.CONTEXT_ALL];

  blackberry.ui.contextmenu.addItem(contexts, myItem, function() {
      alert("Wow you succesfully overrode the platform menu item Copy");
  });
}
 //Override the system Copy action by actionId using the ACTION_SAVE_IMAGE constant
 // this example does not provide a icon, and uses the system default
 function overridePlatformNoIcon() {
  var myItem = {actionId: blackberry.ui.contextmenu.ACTION_SAVE_IMAGE, label: 'Save Image'},
      contexts = [blackberry.ui.contextmenu.CONTEXT_ALL];

  blackberry.ui.contextmenu.addItem(contexts, myItem, function() {
      alert("Custom Save using system icon");
  });
}
</script>

static void blackberry.ui.contextmenu.defineCustomContext (context : String, options : Object)


Allows the developer to define a custom context.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
context A String representing the custom context.
options An Object that contains the various options to set for the custom context.

Code Example: 
<script type="text/javascript">

function defineCustomContext() {
    var options = {
        includeContextItems: [blackberry.ui.contextmenu.CONTEXT_IMAGE],//Includes custom items added for CONTEXT_IMAGE
        includePlatformItems: true,
        includeMenuServiceItems: true
    };

    blackberry.ui.contextmenu.defineCustomContext("myContext", options)
}
</script>

static void blackberry.ui.contextmenu.removeItem (contexts : String[], actionId : String)


Allows the developer to remove previously added custom items from the context menu.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator


Parameters
contexts An array of constants defining which contexts this new item should appear.
actionId An id that uniquely defines the action to be removed from the context menu.

Code Example: 
<script type="text/javascript">

function addMyItem() {
    var myItem = {actionId: 'MyItem', label: 'My Item', icon:'http://mysite.com/icon.png'},
        contexts = [blackberry.ui.contextmenu.CONTEXT_IMAGE, blackberry.ui.contextmenu.CONTEXT_INPUT];
    blackberry.ui.contextmenu.addItem(contexts, myItem);
}

function removeMyItem() {
    var myItem = {actionId: 'MyItem', label: 'My Item', icon:'http://mysite.com/icon.png'},
        contexts = [blackberry.ui.contextmenu.CONTEXT_IMAGE, blackberry.ui.contextmenu.CONTEXT_INPUT];
    blackberry.ui.contextmenu.removeItem(contexts, myItem.actionId);
}

</script>

Properties

static boolean enabled


Context Menu enabled allows the developer to enabled and disable crosscut context menus for their application.


Supported Platforms


Parameters
enabled property that sets the contextmenu to enabled or disabled

Code Example: 
<script type="text/javascript">

function disabledContextMenu() {
    blackberry.ui.contextmenu.enabled = false;
}

if(!blackberry.ui.contextmenu.enabled){
    console.log("context menu is currently disabled");
    }
</script>

Constants

static String CONTEXT_ALL


Constant denoting all contexts.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_LINK


Constant denoting the context of links.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_IMAGE


Constant denoting the context of images.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_IMAGE_LINK


Constant denoting the context of image links.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_INPUT


Constant denoting the context of input fields.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String CONTEXT_TEXT


Constant denoting the context of text.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_CANCEL


Constant denoting the actionId of cancel


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_CLEAR_FIELD


Constant denoting the actionId of clear field.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_COPY


Constant denoting the actionId of copy.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_COPY_IMAGE_LINK


Constant denoting the actionId of copy image link.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_COPY_LINK


Constant denoting the actionId of copy link.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_CUT


Constant denoting the actionId of cut.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String INSPECT_ELEMENT


Constant denoting the actionId of inspect element


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_OPEN_LINK


Constant denoting the actionId of open link.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_PASTE


Constant denoting the actionId of paste.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTIONE_SAVE_IMAGE


Constant denoting the actionId of save image.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_SAVE_LINK_AS


Constant denoting the actionId of save link as.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_SELECT


Constant denoting the actionId of select.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

static String ACTION_VIEW_IMAGE


Constant denoting the actionId of view image.


Supported Platforms
 - BlackBerry 10
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:36 GMT-0500 (EST)