Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Menu items

The Application Menu Item API, in the net.rim.blackberry.api.menuitem package, lets you define menu items to display in BlackBerry Device Software applications. The ApplicationMenuItemRepository class lets you add or remove menu items from BlackBerry Device Software applications.

Create and register a menu item

Extend the ApplicationMenuItem class to define a menu item to display in BlackBerry Device Software applications.

Import the required classes and interfaces.

import java.lang.IllegalStateException;
import net.rim.blackberry.api.menuitem.ApplicationMenuItem;
import net.rim.blackberry.api.menuitem.ApplicationMenuItemRepository;

To create and register a menu item, perform the following tasks:

Task

Steps

Define a menu item.

Extend the ApplicationMenuItem class.

public class SampleMenuItem
     extends ApplicationMenuItem { ... }

Specify the position of the menu item in the menu.

Construct the ApplicationMenuItem. A higher number in the constructor means that the menu item appears lower in the menu.

SampleMenuItem() 
{
  super(0x350100);
}

Specify the menu item text.

Implement toString().

public String toString() 
{
  return "My menu item";
}

Specify the behavior of the menu item.

Implement run().

public Object run(Object context) 
{
  // The menu's action here.
  return null;
}

Register the menu item.

Invoke ApplicationMenuItemRepository.addMenuItem().

ApplicationMenuItemRepository amir = 
  ApplicationMenuItemRepository.getInstance();
amir.addMenuItem(
  ApplicationMenuItemRepository.MENUITEM_PHONE, 
  mySampleMenuItem);

Code sample: Creating and registering a menu item

// Create menu item 
int placement = 0x350100; 
ApplicationMenuItem ami = new ApplicationMenuItem(placement) 
{ 
   public Object run(Object context) 
   { 
      // do something 
      return null; 
   } 

   public String toString()
   { 
      return "My menu item"; 
   } 
}; 

// Register menu item to display when user views a contact.
ApplicationMenuItemRepository amir = ApplicationMenuItemRepository.getInstance();
amir.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW, ami); 

Send Menu API

You can use the Send Menu API to allow BlackBerry device users to send content from your application to a recipient by using a core application on the BlackBerry device. For example, you can create an application that allows users to send content using an email message, an SMS text message, a PIN message, or a social networking application such as Twitter for BlackBerry smartphones. You can allow users to send text from your application, or files from the file system on the device. The classes that make up the Send Menu API are included in the net.rim.blackberry.api.sendmenu package.

The Send Menu API allows your application to interact with other BlackBerry Device Software applications, such as the Messages application and social networking applications, and makes it easy for users to navigate between applications. By using the Send Menu API, you can create an application with a user experience that is consistent with other core applications on the device.

You can use the Send Menu API to add a Send menu item to the menu of your application. When a user clicks the Send menu item, a submenu appears with a list of applications that the user can use to send content from your application to a recipient. When the user clicks the name of an application in the Send submenu, that application opens with certain fields prepopulated with the content to send. For example, if the user chooses to send text from your application by using an email message, the Messages application opens and the body of a new email message is populated with the text. Only applications that are developed by Research In Motion can appear in the Send menu of your application.

An example of the Send menu.

Retrieving Send commands

To create a Send menu in your application, you must retrieve a set of commands to include in the menu. Each command corresponds to an application that BlackBerry device users can use to send content from your application. For example, you can retrieve commands that correspond to sending an email message, an SMS text message, and so on.

You can use the SendCommandRepository class to retrieve commands to use in a Send menu. The SendCommandRepository class contains all of the commands that are registered on the device, and you can include these commands in the Send menu. The SendCommandRepository class is a singleton class, and you can retrieve the singleton instance of this class by invoking the static SendCommandRepository.getInstance(). You can then retrieve an array of commands by invoking get(). Commands are represented by SendCommand objects, and so invoking get() returns an array of SendCommand objects.

When you invoke get() to retrieve commands, you must provide a set of parameters that defines the types of commands that you want this method to return. The following table describes the parameters that you must provide and how each parameter affects the types of commands that you receive.

Parameter

Description

type

This parameter is an int value that represents the type of content that your application allows users to send using the Send menu. You can specify two values for this parameter, both of which are constants that are included in SendCommand:

  • SendCommand.TYPE_TEXT: This constant indicates that your application allows users to send text, and that the context parameter contains information that is related to the text to send.
  • SendCommand.TYPE_PATH: This constant indicates that your application allows users to send files, and that the context parameter contains information that is related to the file to send.

context

This parameter is a JSONObject object that represents the content to send. This object contains a set of key-value pairs that determine what content is sent and what fields are populated in the application that sends the content. For example, the JSONObject object might contain the path of the file to send, or the subject and body of a message to create. You can use the constants that are included in the SendCommandContextKeys class as keys for the content.

availability

This parameter is a boolean value that indicates whether get() returns all commands regardless of whether their associated applications can be opened.

This parameter is optional.

The get() method returns SendCommand objects that support both the type and the context that you specify. For example, if you specify a type of SendCommand.TYPE_PATH, the array of SendCommand objects that you receive from get() will not include a command that is associated with sending an SMS text message because files cannot be sent using SMS text messages.

You can use the following code snippet to retrieve a set of commands from a SendCommandRepository. These commands are associated with applications that support sending text content to a recipient, such as the Messages application, and do not include commands that are associated with applications that cannot be opened.

SendCommand[] sendCommands = SendCommandRepository.getInstance().get(SendCommand.TYPE_TEXT, context, false);

Creating a Send menu

You can use the SendCommandMenu class to create a Send menu in your application. This class is a subclass of the SubMenu class and is designed to create a menu that represents a set of SendCommand objects. Each SendCommand object is represented in the Send menu by a SendCommandMenuItem object. When a BlackBerry device user clicks one of the Send menu items, the run() method of the associated SendCommand object is invoked.

When you create a SendCommandMenu object, you can provide either an array of SendCommandMenuItem objects or an array of SendCommand objects. You can specify both the ordering of the items in the menu, and what text appears as the label of the menu. For example, the default label is "Send," but you can provide different text that is appropriate for your application.

As an alternative to creating a Send menu, you can use the SendCommandScreen class to create a pop-up screen that displays SendCommand objects. For example, your application might contain a toolbar button called "Send", and when a user clicks this button, a list of available Send commands is displayed.

You can also create your own UI components to display SendCommand objects if neither SendCommandMenu or SendCommandScreen suit your needs. For example, you might create a drop-down list that contains SendCommand objects that a user can choose from.

Code sample: Creating a Send menu

In this task, an edit field is created that accepts text that a BlackBerry device user types. This text is stored in a context object, and this context object is used to retrieve a list of Send menu commands whose associated applications can accept the text. A Send menu is created with these Send menu commands.

import net.rim.blackberry.api.sendmenu.*;

import net.rim.device.api.ui.Field;
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.XYEdges;
import net.rim.device.api.ui.component.EditField;
import net.rim.device.api.ui.component.Menu;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.decor.BorderFactory;

import org.json.me.JSONException;
import org.json.me.JSONObject;

public class SendMenuAPIDemo extends UiApplication
{
    public static void main(String[] args)
    {
        SendMenuAPIDemo theApp = new SendMenuAPIDemo();
        theApp.enterEventDispatcher();
    }

    public SendMenuAPIDemo()
    {
        pushScreen(new SendCommandDemoScreen());
    }
}

class SendCommandDemoScreen extends MainScreen
{

//In the screen class, declare instance variables to represent 
//an edit field and the text that the user types in this field.  
    private EditField _textToSend;
    private String _textString;

    public SendCommandDemoScreen()
    {
        setTitle("Send Menu API Demo");

//In the screen constructor, create a new EditField object to represent 
//the field that the user types in.  
        _textToSend = new EditField("Send: ", "Type the text to send here",
                                    255, Field.USE_ALL_WIDTH);

//To specify the appearance of the EditField object, invoke setBorder(), 
//setPadding(), and setMargin(). In this example, a bevel border is created
//for the EditField object, and a padding area and margin area are added. 
        _textToSend.setBorder(BorderFactory.createBevelBorder(
                                            new XYEdges(3, 3, 3, 3)));
        _textToSend.setPadding(8, 8, 8, 8);
        _textToSend.setMargin(15, 15, 15, 15);

//Add the EditField object to the screen. 
        add(_textToSend);
    }

//Override makeMenu() of the MainScreen class. 
    protected void makeMenu(Menu menu, int instance)
    {

//Invoke super.makeMenu() to add the default menu items for BlackBerry 
//device applications to the menu. 
        super.makeMenu(menu, instance);

//Invoke getText() of the EditField class to retrieve the text that 
//the user typed in the edit field. 
        _textString = _textToSend.getText();

//Create a new JSONObject object to represent the context 
//information for the Send menu. 
        JSONObject context = new JSONObject();

//In a try/catch block, invoke put() of the JSONObject object to populate 
//the context information using key-value pairs. Use the constants that 
//are defined in the SendCommandContextKeys class as keys. Catch a 
//JSONException, which indicates that the specified key is null.  
        try
        {
            context.put(SendCommandContextKeys.TEXT, _textString); 
            context.put(SendCommandContextKeys.SUBJECT, "Your Text");
        }
        catch (JSONException e)
        {
            System.out.println(e.toString());
        }

//Create an array of SendCommand objects to represent the Send menu commands 
//that you want to include in the Send menu. Invoke 
//SendCommandRepository.getInstance() to retrieve the singleton instance of the
//SendCommandRepository. Invoke get() and specify as parameters the type of content 
//to send, the context information for the content, and a boolean value 
//that indicates whether all of the commands should be retrieved 
//regardless of whether their associated applications can be opened. 
        SendCommand[] sendCommands = SendCommandRepository.getInstance().get(
                                         SendCommand.TYPE_TEXT, context, false);

//Determine whether the array of SendCommand objects is not null and 
//contains commands, and if so, create a new SendCommandMenu object to represent 
//these commands and add it to the menu. 
        if (sendCommands != null && sendCommands.length > 0)
        {
            menu.add(new SendCommandMenu(sendCommands, 0, 0));
        }
    }
}

Creating a context object

When you use the SendCommandRepository class to retrieve a set of commands to include in a Send menu, you must provide a context object. A context object contains information that is required to send content from your application to a recipient. For example, if your application allows a BlackBerry device user to send text and the user chooses to send the text in an email message, the context object might contain the subject and body of the email message to send.

The Send Menu API uses a JSONObject object to represent context information. A JSONObject is an unordered collection of key-value pairs. The keys are String objects, and the values can include several types, such as boolean, int, Hashtable, or Vector.

You can invoke put() of the JSONObject class to add context information to a JSONObject. The Send Menu API provides a set of predefined keys, which are constants in the SendCommandContextKeys class, that you can use to add context information to a JSONObject.

The following code sample demonstrates how to create a JSONObject and add text to it using the SendCommandContextKeys.TEXT key. The put() method can throw a JSONException to indicate that the key that you specify is null, so it's important to catch this exception.

JSONObject context = new JSONObject();
try
{
    context.put(SendCommandContextKeys.TEXT, "This is some text to send.");
}
catch (JSONException e)
{
    System.out.println(e.toString());
}

Using context keys

When you add context information for a Send command to a JSONObject object, you must specify a context key. The key in a JSONObject must be a String value. You can use the constants in the SendCommandContextKeys class as keys for the information in a JSONObject. You aren't required to use the keys that are defined in SendCommandContextKeys, but they are defined to standardize the keys that the Send Menu API uses.

The following table describes the constants that are defined in SendCommandContextKeys.

Constant

Description

PATH

You can use this constant as a key to store a String object that represents a path. This path is the location of a file in the file system of the BlackBerry device, such as /SDCard/photo.jpg. The file that this path refers to does not need to exist on the device.

If a SendCommand object has a type of SendCommand.TYPE_PATH, then this constant is required as a key in the associated JSONObject.

SUBJECT

You can use this constant as a key to store a String object that represents the subject of a message. For example, if your application allows a BlackBerry device user to send text and the user chooses to send the text in an email message, then the value that is associated with this key in the JSONObject is used as the subject of the email message.

If a SendCommand object has a type of SendCommand.TYPE_TEXT, then this constant is optional as a key in the associated JSONObject.

TEXT

You can use this constant as a key to store a String object that represents the text of a message. For example, if your application allows a user to send text and the user chooses to send the text in an email message, then the value that is associated with this key in the JSONObject is used as the text of the email message.

If a SendCommand object has a type of SendCommand.TYPE_TEXT, then this constant is optional as a key in the assocated JSONObject.

Using context filters

You can use the SendCommandContextFilter interface to define a context filter for the context object that is associated with a SendCommand object. Filters are useful if the application that you're using to send content has restrictions on the size or type of content that it receives. For example, if an application can accept text of a certain length only, you can define a filter that shortens strings in the context object if they exceed a specific character limit so that the application can accept and send the content.

You can create a class that acts as a filter by implementing the SendCommandContextFilter interface and implementing filterContext(). This method changes the context object of a specified SendCommand object according to filtering criteria that you specify, and returns the altered context object. The run() method of the SendCommand object uses the altered context object to send the content from your application. You can register a context filter for a SendCommand object by invoking setSendCommandContextFilter().

Code sample: Creating a context filter

In this task, a context filter is created that replaces the subject in the JSONObject context object with different text.

import net.rim.blackberry.api.sendmenu.*;

import net.rim.device.api.ui.Field;
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.XYEdges;
import net.rim.device.api.ui.component.EditField;
import net.rim.device.api.ui.component.Menu;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.ui.decor.BorderFactory;

import org.json.me.JSONException;
import org.json.me.JSONObject;

public class ContextFilterDemo extends UiApplication
{
    public static void main(String[] args)
    {
        ContextFilterDemo theApp = new ContextFilterDemo();
        theApp.enterEventDispatcher();
    }

    public ContextFilterDemo()
    {
        pushScreen(new ContextFilterDemoScreen());
    }
}

class ContextFilterDemoScreen extends MainScreen
{
    private EditField _textToSend;
    private String _textString;
	
    public ContextFilterDemoScreen()
    {
        setTitle("Context Filter Demo");

        _textToSend = new EditField("Send: ", "Type the text to send here",
                                    255, Field.USE_ALL_WIDTH);
        _textToSend.setBorder(BorderFactory.createBevelBorder(
                              new XYEdges(3, 3, 3, 3)));
        _textToSend.setPadding(8, 8, 8, 8);
        _textToSend.setMargin(15, 15, 15, 15);

        add(_textToSend);
    }

//Override makeMenu() of the MainScreen class to create the menu for your 
//application. Add the required code to set up a Send menu, such as invoking 
//super.makeMenu(), creating and populating a context object, and retrieving a 
//list of SendCommand objects.  
    protected void makeMenu(Menu menu, int instance)
    {
        super.makeMenu(menu, instance);

        _textString = _textToSend.getText();

        JSONObject context = new JSONObject();
        try
        {
            context.put(SendCommandContextKeys.TEXT, _textString); 
            context.put(SendCommandContextKeys.SUBJECT, "Your Text");
        }
        catch (JSONException e)
        {
            System.out.println(e.toString());
        }

        SendCommand[] sendCommands = SendCommandRepository.getInstance().get(
                                       SendCommand.TYPE_TEXT, context, false);
        if (sendCommands != null && sendCommands.length > 0)
        {

//Before you invoke add() to add the Send menu to the menu of your app, 
//create a new object to represent a context filter. In this example,
//the MyContextFilter class is defined as a context filter for SendCommand objects. 
            MyContextFilter filter = new MyContextFilter();
            for (int i = 0; i < sendCommands.length; i++)
            {

//Invoke setSendCommandContextFilter() of the SendCommand class to set the 
//MyContextFilter object as the context filter for a SendCommand.
                sendCommands[i].setSendCommandContextFilter(filter);
            }
            menu.add(new SendCommandMenu(sendCommands, 0, 0));
        }
    }
}

//Define MyContextFilter and implement SendCommandContextFilter. 
class MyContextFilter implements SendCommandContextFilter
{

//Implement filterContext(). This method is invoked when a BlackBerry device user 
//clicks a Send menu item that has this context filter set. 
    public JSONObject filterContext(SendCommand sendCommand)
    {

//Create a new JSONObject object.
//Invoke getContext() to retrieve the context object of 
//the SendCommand object that the user clicked, and store it in the JSONObject. 
        JSONObject newContext = sendCommand.getContext();

//In a try/catch block, alter the context object as appropriate. In this example, 
//we invoke put() of the JSONObject object to replace the subject text. 
//Catch a JSONException, which indicates that the specified key is null. 
        try
        {
            newContext.put(SendCommandContextKeys.SUBJECT,
                           "Subject replaced by filter");
        }
        catch (JSONException e)
        {
            System.out.println(e.toString());
        }

        return newContext;
    }
}