Menu integration

The 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 device: action menu and context menu.

This section shows you how to add menus to your app and how to use the invocation framework to display your app in the context menu of other apps. This section also shows you how to configure your app to allow the BlackBerry 10 OS to automatically populate any related actions into the context menu of your app.

If you're using C++, 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.

To learn more about the action and app menus, see Menus.

Context menu

The context menu is a vital part of building an intuitive experience and is a key feature in BlackBerry 10. When the user presses and holds a particular area of the app UI, the context menu is presented. The context menu is divided into two sections that offer actions related to the content selected by the user.

The upper section of the context menu is the app section, which contains all of the actions that the app adds. For example, in the following image on the right, Add as friend, Call, Email, and Text actions are all app actions.

The lower section of the context menu is the platform section, which contains all of the actions that the BlackBerry 10 OS adds automatically. In the following image on the right, Delete is a platform action.

 

Screen showing a context menu with the icons and labels associated with each action.

Screen showing the order of items in a context menu. The upper half of the items are application specific actions and the lower half are platform specific actions.

 

Customizing the context menu

You can use the following techniques to customize the context menu and integrate it with the invocation framework.

Add bound invocations

The ActionItem class represents the actions that your app supports. You can also add actions to the context menu in your app from actions that are supported in other apps using the invocation framework. When an invocation request is sent, an action is created as an InvokeActionItem object, which extends the ActionItem class.

Here's how you can add a bound invocation action to the context menu:

InvokeActionItem {
	query {
		invokeTargetId: "com.example.image.view"
	     	mimeType: "image/png"
		invokeActionId: "bb.action.OPEN"
		uri: "file:///.../image.png"
	}
}

Here's how you can add a bound invocation action to the context menu:

InvokeActionItem invokeItem;
invokeItem.setTarget("com.example.image.view"); 
invokeItem.setAction("bb.action.OPEN");
invokeItem.setMimeType("image/png");
invokeItem.setUri("file:///.../image.png"); 

Add the platform section

Before the platform can add any actions to the context menu, it determines the current context of the app. For example, if your app is currently displaying an image, the platform determines the properties of the image (for example, .jpg or .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:

InvokeActionItem {
	query {
	     	mimeType: "image/png"
		invokeActionId: "bb.action.OPEN"
		uri: "file:///.../image.png"
	}
}

Here's how you can add the platform section to your app's context menu:

InvokeActionItem invokeItem;
invokeItem.setAction("bb.action.OPEN");
invokeItem.setMimeType("image/png");
invokeItem.setUri("file:///.../image.png");

The platform section is displayed only if there are targets that match the criteria of the invocation-related actions.

Add your application to the platform section

You can add a specific feature of your app to the platform section of the context menu of other apps. Enabling your app to appear in the platform section gives it greater visibility among other apps and is good for the publicity of your app. You can add a specific feature of your app 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:

  • bb.action.OPEN
  • bb.action.SHARE
  • bb.action.SET

It is important to choose the action that suits your app's needs. For example, if your app 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, then 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 app:

<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>
        <mime-type>*</mime-type>
        <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

The target selection menu is displayed when the user selects the Share action on the context menu. The target selection menu contains two sections: Suggestions and a Share With list displaying all of the available targets for sharing.

Screen showing the share card.

Adding icons to the target selection menu

If your app is declaring itself as a target for core menu actions (OPEN, SHARE, and SET), you must package your app with two images of size 81 x 81 pixels and 358 x 358 pixels. These images should typically show your app's icon. The image of size 81 x 81 pixels is used in the list that displays all of 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 the BBM and Text Messages apps look in the list section:

 

The BBM icon in the list section of the target selection menu.

The Text Messages icon in the list section of the target selection menu.

 

Here's how the images for the Email and Text Messages apps look in the suggestions section:

 

Screen showing the email icon for suggestions grid of the context menu.

Screen showing the Text Messages app icon for suggestions grid of the context menu.

 

As a best practice, remember to fill any transparent pixels in your image with color. This approach 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 app, as follows:

...
<icon>
    <image public="true"> icon_small.png</image>
    <image public="true"> icon_big.png</image>
</icon>
...

Last modified: 2014-11-17



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus