BlackBerry 10 OS offers a well-integrated menu system that enables you to make highly contextual apps. There are two types of menus available on the UI of a BlackBerry 10 OS device: action menu and context menu.
In this section, you will learn how to add menus to your app and how to use the invocation framework to display your application in the context menu of other apps. You will also learn about configuring your app to allow the BlackBerry 10 OS to automatically populate any related actions into the context menu of your app.
It's a good practice to add invocation-related actions to the context menu. However, if an action applies to the whole page, you can add the action to the action bar.
Meanwhile, to learn more about the action and application menus, see Menus.
The context menu is a vital part of building an intuitive experience and is a key feature in BlackBerry 10 OS. It is presented when the user presses and momentarily holds a particular area of the application UI. The context menu is divided into two sections that offer actions related to the content selected by the user.
The upper half of the context menu is the application section, which contains all the actions that the application adds. For example, in the following image on the right, Add as friend, Call, Email, and Text actions are all application actions.
The lower half of the context menu is the platform section, which contains all the actions that the BlackBerry 10 OS adds automatically. In the following image on the right, Call, Email, Text, Share, Set as and Open in are platform actions.
Customizing the context menu
You can use the following technique to customize the context menu and integrate it with the invocation framework.
Add the platform section
Before the platform can add any actions to the context menu, it determines the current context of the application. For example, if your application is currently displaying an image, the platform determines the properties of the image (for example, .jpg, .png) and how it can be accessed (for example, as file:// or http://). Here's how you can add the platform section to your app's context menu:
var button:Button = new Button(); //When using the InvokeActionItem class, ensure your application is including the QNXDevice.ane. var invokeItem:InvokeActionItem = new InvokeActionItem( InvokeAction.OPEN, "image/png", "file:///.../image.png" ); var actionSet:ActionSet = new ActionSet( new <ActionBase>[invokeItem] ); var actions:Vector.<ActionSet> = new <ActionSet>[actionSet]; button.contextActions = actions;
Add your application to the platform section
You can add a specific functionality of your application to the platform section of the context menu of other apps. Enabling your application to appear in the platform section allows it greater visibility among other applications and is good for the publicity of your app. You can add a specific functionality of your application to the platform section by declaring support for the invocation of a core action for a given context. The following core actions are available in the BlackBerry 10 OS:
It is important to choose the action that suits your application's needs. For example, if your application manages images, then supporting bb.action.OPEN action in your app is a good idea. If your app uploads images to an online catalog, then you probably want to support bb.action.SHARE. If your app assigns images as avatars, you probably want to use bb.action.SET as the core action.
Here's how you can declare these actions in the target filter section of the bar-descriptor.xml file of your application:
<invoke-target id="com.example.image.view"> <invoke-target-type>application</invoke-target-type> <invoke-target-name>My Sample Application</invoke-target-name> <icon> <image public="true"> icon_small.png</image> <image public="true"> icon_big.png</image> </icon> <filter> <action>bb.action.SHARE</action> <property var="uris" value="file://,list://"/> <property var="exts" value="jpg,png,jpeg,bmp"/> </filter> </invoke-target>
For more information about invocation and how you can make your app an invocation target, see Receiving invocation.
Target selection menu
Target selection menu displays when the user selects the share action on the context menu. The target selection menu contains two sections: suggestions and a list displaying all the available targets for sharing.
Adding icons to the target selection menu
If your application is declaring itself as a target for core menu actions (OPEN, SHARE, SET), you must package your application with two images of size 81 x 81 pixels and 358 x 358 pixels respectively. These images should typically show your application's icon. The image of size 81 x 81 pixels is used in the list that displays all the available targets while the image of size 358 x 358 pixels is used in the suggestions section of the target selection menu.
Here's how the images for BBM and Text Messages applications look in the list section:
Here's how the images for Email and Text Messages applications look in the suggestions section:
As a best practice, remember to fill any transparent pixels in your image with color. This prevents the background color of the suggestions grid from appearing through the transparent pixels.
You should specify the images in the bar-descriptor.xml file of your application as shown in the code below.
... <icon> <image public="true"> icon_small.png</image> <image public="true"> icon_big.png</image> </icon> ...