Menu integration

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.

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, but your application can also add actions that other apps support to the application section of your app's context menu. However, applications can also add the actions supported by other apps, to the application section of their context menu by using the invocation framework. When an invocation request is sent, an action is created as InvokeActionItem, which extends the ActionItem class. Here's how you can add a bound invocation action to the context menu using QML and C++:

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

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

Adding 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 using QML and C++:

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

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

Add your application to the platform section

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.

<invoke-target id="com.example.image.view">
  <invoke-target-type>application</invoke-target-type>
  <filter>
    <action>bb.action.OPEN</action>
    <mime-type>image/png</mime-type>
    <mime-type>image/jpeg</mime-type>
  </filter> 
</invoke-target>

For more information about invocation and how you can make your app an invocation target, see Receiving invocation.