Certify and Increase Opportunity.
Be
Govt. Certified Blackberry Apps Developer
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.
Context Information
Context information is available from the window object through a contextmenu event “window.oncontextmenu”. This event is triggered whenever there is a context menu request from the client. This event provides all the contextual information needed to store the context yourself and save what element the context menu was triggered on. This allows you to perform a multitude of different actions once a context menu has been requested.
Code Example:
<script type="text/javascript">
function addMenuItemToCustomContext() {
var myItem = {actionId: '7', label: 'itemForCustom', icon:'local:///img/myIcon.png'},
contexts = ["myContext"];
blackberry.ui.contextmenu.addItem(contexts, myItem);
}
function addAdditionalItemsFromCustomContext) {
var options = {
includeContextItems: [blackberry.ui.contextmenu.CONTEXT_IMAGE, blackberry.ui.contextmenu.CONTEXT_IMAGE_LINK],
includePlatformItems: true,
includeMenuService: true
};
blackberry.ui.contextmenu.defineCustomContext("myContext", options);
}
function removeAdditionalItemsFromCustomContext) {
var options = {
includeContextItems: [],
includePlatformItems: false,
includeMenuService: false
};
blackberry.ui.contextmenu.defineCustomContext("myContext", options);
}
</script>
<div data-webworks-context="myContext">I am a custom context!</div>
|
Learning Resources:
Sample – Using Custom Context Sample that demonstrates how to use the BlackBerry Custom Context API [BlackBerry on GitHub].
<script type="text/javascript">
// Update the path from a small icon to a full image
function translateIcontoFullImage (path) {
if (path && path.indexOf('.ico') !== -1) {
return path.replace('.ico', '.jpeg');
}
}
function onContextMenu (contextEvent) {
var srcElement = contextEvent.srcElement;
blackberry.invoke.interrupter = function (request) {
// Check if this is an image we wish to translate
if (srcElement && srcElement.src {
request.uri = translateIcontoFullImage(srcElement.src);
}
// Return the updated request object
return request;
};
}
window.addEventListener('oncontextmenu', onContextMenu);
</script>
Custom Context Menu
Webworks applications can give Dom elements custom context by using the data-webworks-context xml attribute. When a Dom element contains this attribute, custom context menus will be activated when the element is long pressed. Once you have created a custom context using the data-webworks-context attribute, you can then use addItem to add items to the custom context. You can also optionally use defineCustomContext to further define the items shown. |
Supported Platform(s)
– BlackBerry 10 |
– Ripple Emulator |
View Supported Platform Table
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 ID |
BB5.0 |
BB6.0 |
BB7.0 |
PB1.0 |
PB2.0 |
BB10 |
Ripple |
<feature id=”blackberry.ui.contextmenu” /> |
|
|
|
|
|
Y |
Y |
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
void |
blackberry.ui.contextmenu.addItem |
void |
blackberry.ui.contextmenu.defineCustomContext |
void |
blackberry.ui.contextmenu.removeItem |
Constants
String |
CONTEXT_ALL |
String |
CONTEXT_LINK |
String |
CONTEXT_IMAGE |
String |
CONTEXT_IMAGE_LINK |
String |
CONTEXT_INPUT |
String |
CONTEXT_TEXT |
String |
ACTION_CANCEL |
String |
ACTION_CLEAR_FIELD |
String |
ACTION_COPY |
String |
ACTION_COPY_IMAGE_LINK |
String |
ACTION_COPY_LINK |
String |
ACTION_CUT |
String |
INSPECT_ELEMENT |
String |
ACTION_PASTE |
String |
ACTIONE_SAVE_IMAGE |
String |
ACTION_SAVE_LINK_AS |
String |
ACTION_SELECT |
String |
ACTION_VIEW_IMAGE |