Would you like to tell us how we are doing?

You bet No thanks

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

Code sample: Creating a menu

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;

//Create the application framework by extending
//the UiApplication class. In main(), create an instance 
//of the new class and invoke enterEventDispatcher() to 
//enable the application to receive events. In the application 
//constructor, invoke pushScreen() to display the custom screen 
//for the application. 
public class CreateMenu extends UiApplication
{
     public static void main(String[] args)
     {
         CreateMenu theApp = new CreateMenu();
         theApp.enterEventDispatcher();
     }
     public CreateMenu()
     {
         pushScreen(new CreateMenuScreen());
     }
} 

//Create the custom screen for the application by extending 
//the MainScreen class. In the screen constructor, invoke 
//setTitle() to specify the title  for the screen. Invoke 
//add() to add a text field to the screen. Invoke addMenuItem() 
//to add a menu item to the menu that MainScreen creates.
class CreateMenuScreen extends MainScreen
{
    public CreateMenuScreen()
    {
      setTitle("Create Menu Sample");
      add(new RichTextField("Create a menu"));
      addMenuItem(_viewItem);
    }

//Create the menu item by using the MenuItem class. Override 
//run() to specify the action that occurs when the user clicks the 
//menu item. When  the user clicks the menu item, the 
//application invokes Menu.run().
    private MenuItem _viewItem = new MenuItem("More Info", 110, 10)
    {
        public void run()
        {
            Dialog.inform("Display more information");
        }
    };

//Override close() to display a dialog box  when the user clicks the 
//Close menu item. By default, the Close menu item is included in the 
//menu that MainScreen creates. Invoke super.close() to close the 
//application. When the user closes the dialog box, the application 
//invokes MainScreen.close() to close the application.
    public void close()
    {
        Dialog.alert("Goodbye!");     
        super.close();
    }   
}

Best practice: Implementing menus

  • Always provide a full menu.
  • Make sure that users can press the Menu key to open the full menu and to initiate an action when a menu item is highlighted. Make sure that users can also hold the Menu key to open the dialog box for switching applications.
  • For the default menu item, use the menu item that users are most likely to select.
  • Place the default menu item and other common menu items in the middle of the menu.
  • Verify that the order of menu items is consistent with the order of menu items in other BlackBerry device applications.
  • Group menu items according to common usage or common functionality, and where possible, test your groupings with users.
  • Insert separators between menu item groupings.
  • Do not place menu items for conflicting actions close together. For example, do not place a "Delete" menu item beside an "Open" menu item.
  • Always include the "Switch application" and "Close" menu items. Place these menu items at the end of the menu. If you use standard components, these menu items are included automatically.

Guidelines for labels

  • Use concise, descriptive labels that are no longer than 12 characters. If a label is too long, an ellipsis (...) appears to indicate that the text is truncated.
  • Use verbs for labels.
  • Use title case capitalization for labels.
  • Use an ellipsis in a menu item label to indicate that users must perform another action after they click the menu item. For example, if users click the Go To Date... menu item in the calendar, they must specify a date on the screen that appears.
  • Avoid using symbols such as an asterisk (*) in labels.

Submenus

A submenu is a group of related menu items that appears as a subset of a menu item in the full menu. By including items in a submenu, users can find frequently used items or important items more easily in the full menu. Submenus typically include the following types of actions:

  • sending items in multiple ways (for example, sending a picture in an email message, an MMS message, or as an audio postcard)
  • sorting, searching for, finding, and filtering items in different ways (for example, filtering messages by sender or subject)
  • changing views (for example, day, week, or agenda view in a calendar)

Action

BlackBerry devices with a trackpad only

BlackBerry devices with a touch screen and a trackpad

When a menu item is highlighted in a full menu, display a submenu.

  • Click the trackpad.
  • Move a finger to the right on the trackpad.
  • Press the Menu key.
  • Press the Enter key.
  • Tap the menu item.
  • Click the trackpad.
  • Move a finger to the right on the trackpad.
  • Press the Menu key.
  • Press the Enter key.

Choose a menu item from a submenu.

  • Click the trackpad.
  • Press the Menu key.
  • Press the Enter key.
  • Tap the menu item.
  • Click the trackpad.
  • Press the Menu key.
  • Press the Enter key.

Close a submenu.

  • Move a finger to the left on the trackpad.
  • Press the Escape key.
  • Tap outside the submenu.
  • Move a finger to the left on the trackpad.
  • Press the Escape key.

Close a submenu and a full menu.

Press the Escape key twice.

  • Tap outside the full menu and the submenu twice.
  • Press the Escape key twice.
  • Open or close the slider.

An arrow appears when submenu items are available for an item in the full menu.

Figure 1. A full menu item with an arrow
This screen shows an example of a full menu item with a scroll arrow indicating that the item has a submenu associated with it.

Figure 2. A full menu and a submenu
This screen shows an example of a full menu item and the submenu associated with it.

Best practice: Implementing submenus

  • Use the Submenu subclass to create submenus.
  • Use submenus to reduce the number of menu items in the full menu. For example, if users have to scroll to see all the items in a full menu, group some of the menu items in a submenu.
  • Group related items in a submenu. For example, if "Sort By" appears in the full menu, group "Date," "Name," and "Subject" in a submenu.
  • Consider grouping advanced features in a submenu. For example, use "Additional Options" in the full menu and group the options in the submenu.
  • Avoid using submenus for only one or two menu items.
  • If a submenu includes more than six items, consider grouping the items into two sections in the submenu. Place the menu items that are frequently used at the top of the submenu, insert a separator, and then order the rest of the items alphabetically.
  • If a menu item requires users to do more than click the item (for example, if a user has to specify a date), open a dialog box.
  • Avoid including frequently used menu items or important menu items in submenus.
  • Avoid implementing a submenu from a submenu.

Guidelines for labels

  • In the full menu, use concise, descriptive labels that clearly define the action. Users should not have to open the submenu to understand the meaning of the item in the full menu.
  • In the full menu, use verbs for labels. Use nouns only if the meaning is clear. For example, if "Email Accounts" appears in the full menu, group each email account in a submenu.
  • Avoid repeating verbs in submenus. For example, avoid using "Sort By" in the full menu and "Sort By Date" and "Sort By Name" in the submenu.
  • Use title case capitalization for labels. Capitalize the first word in the submenu even if it is a preposition. For example, use "Send" > "As Email" instead of "as Email").
  • Avoid using the term "More" in the full menu unless the location of the menu item clearly indicates what "more" refers to. For example, if "Inbox," "Outbox," and "More" appear between separators in the full menu, group additional options associated with a mailbox in a submenu.
Code sample: Creating a submenu
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;

//Create the application framework by extending the 
//UiApplication class. In main(), create an instance of the new
//class and invoke enterEventDispatcher() to enable the application
//to receive events. In the application constructor, invoke 
//pushScreen() to display the custom screen for the application. 
public class CreateSubmenu extends UiApplication
{
     public static void main(String[] args)
     {
         CreateSubmenu theApp = new CreateSubmenu();
         theApp.enterEventDispatcher();
     }
     public CreateSubmenu()
     {
         pushScreen(new CreateSubmenuScreen());
     }
} 

//Create the custom screen for the application by extending the 
//MainScreen class. In the screen constructor,invoke setTitle() to 
//specify the title  for the screen. Invoke add() to add a text
//field to the screen.
class CreateSubmenuScreen extends MainScreen
{
    public CreateSubmenuScreen()
    {
      setTitle("Create Submenu Sample");
      add(new RichTextField("Create a submenu"));
    }

//Create the submenu items by using the MenuItem class. For each 
//submenu item, override run() to specify the action that occurs when 
//the user clicks the menu item. When  the user clicks the menu item, the 
//application invokes Menu.run().
    private MenuItem _status1 = new MenuItem("Available", 100, 1)
    {
        public void run()
        {
            Dialog.inform("I'm available");
        }
    };
    private MenuItem _status2 = new MenuItem("Unavailable", 200, 2)
    {
        public void run()
        {
            Dialog.inform("I'm unavailable");
        }
    };

//Override makeMenu() to create the menu for the application. 
//Create the submenu by using the SubMenu class. 
//Invoke add() to add the submenu items to the 
//submenu. Invoke super.makeMenu() to create the menu.
    protected void makeMenu( Menu menu, int instance )
    {
        SubMenu statusSubMenu = new SubMenu(null,"My Status",300,3);
        statusSubMenu.add(_status1);
        statusSubMenu.add(_status2);
        menu.add(statusSubMenu);
        super.makeMenu(menu, instance);
    };
}

Pop-up menus

A pop-up menu provides users with a quick way to access the most common actions for a highlighted item. You can also use a pop-up menu if a highlighted item has multiple actions associated with it or if a highlighted item does not have any primary actions associated with it. You can create a pop-up menu that contains nine actions, six actions, or three actions.

Action

BlackBerry devices with a trackpad only

BlackBerry devices with a touch screen and a trackpad

Open a pop-up menu.

  • Click the trackpad.
  • If a primary action has already been assigned to an item (for example, open a message), users can click and hold the trackpad to open a pop-up menu.
  • Tap the item.
  • Click the trackpad.
  • If a primary action has already been assigned to an item (for example, open a message), users can click and hold the trackpad or touch and hold a finger on the touch screen to open a pop-up menu.

Choose an item from a pop-up menu.

  • Click the trackpad.
  • Press the Enter key.
  • Tap the item.
  • Click the trackpad.
  • Press the Enter key.

Close a pop-up menu.

Press the Escape key.

  • Tap outside the pop-up menu.
  • Press the Escape key.
  • Open or close the slider.

This screen shows a pop-up menu.

Pop-up menus replace context menus, or short menus. Any existing context menus are automatically converted into pop-up menus.

Best practice: Implementing pop-up menus

  • Use pop-up menus instead of context menus (short menus). Make sure that the pop-up menu provides value to users.
  • Set the menu item that users are most likely to choose as the default menu item. The default item in the pop-up menu should be the same as the default item in the full menu.
  • Only include the most common actions for a highlighted item in a pop-up menu.
  • Include an icon and a label for each item in the pop-up menu. Create icons with an average size of 33-by-33 pixels. These icons appear on a 60-by-40 pixel canvas and should have some negative space.

Guidelines for placing items in pop-up menus

Place the default menu item in the center of the pop-up menu.

Order the rest of the items from most common to least common according to the numbered positions below. Try to leverage users' muscle memory by making the order of actions consistent with the order of actions in other device applications.


This screen shows the different sizes of pop-up menus and the order of items in each menu.

If the positions are filled dynamically, do not display menu items that are unavailable. Allow the available menu items to shift position.

If there are not enough actions to fill the menu, use a smaller menu. If one or two positions need to be filled, include useful actions such as Copy or Search. If you do not fill a position, "Switch Application" or "Home" appears.

About placing items in the pop-up menus

Pop-up menus display menu items in a 3-by-3, 3-by-2, or 3-by-1 grid depending on the number of items. By default, the pop-up menu always includes an item to open the full menu. You can provide up to eight additional items. If you provide more than eight items, the additional items are not displayed. You can add additional items to the full menu instead.

The first item that you add to the vector of CommandItem elements is the default item in the pop-up menu. The default item appears highlighted in the center of the grid when the BlackBerry device user opens the pop-up menu. The other items are positioned in the pop-up menu based on the order that you add them.

If the number of items that you add to the pop-up menu leaves empty cells in the grid, filler items are added to the menu. The first filler item is an option to switch applications. The second filler item is an option to return to the Home screen.

How BlackBerry 7 fills in empty cells in the pop-up menu.

Support for legacy context menus

Since BlackBerry Java SDK 6.0, an application's context menu or short menu is converted to a pop-up menu. Whether you added menu items to a context menu or used the items that were added to the context menu by default, you do not have to change your code to have these items appear in the pop-up menu instead. However, BlackBerry Java SDK 6.0 includes classes and interfaces that you can use to build a pop-up menu, and allows you to use the Command Framework API and make your code more modular. For example, if your application has a UI component and a menu item that performs the same function, by using the Command Framework API, you can write the code for that function once and use it throughout your application, as well as make it available for other applications to use.

A context menu item included an ordinal number which determined the placement of the item in the menu. The lower the ordinal number, the higher the position of the item in the menu. When a context menu is converted to a pop-up menu, the menu item that has the lowest ordinal number becomes the default pop-up menu item. The remaining items are added to the pop-up menu from the lowest ordinal number to the highest. If an icon was associated with a menu item in your legacy context menu, it is used for the item in the pop-up menu. Otherwise, a default icon is used. Similar to other pop-up menus, only the first eight context menu items are displayed in the pop-up menu. If the context menu has more than eight menu items, make sure that you use the ordinal numbers for the menu items appropriately so that the most important and useful items appear in the pop-up menu.

For more information about creating context menus, see Distinguish between a full menu and a primary actions menu.

Creating a pop-up menu

You can create a pop-up menu by using classes that are available in the net.rim.device.api.ui.menu package, and you can define the functionality of the pop-up menu items by using the Command Framework API.

A pop-up menu consists of a context menu provider, a command item provider, and command items.

Component

Description

Context menu provider

You use the DefaultContextMenuProvider class to create and display a screen's pop-up menu. When a BlackBerry device user opens a pop-up menu, the context menu provider looks for fields on the screen that are command item providers. DefaultContextMenuProvider is the default implementation of ContextMenuProvider. If you do not provide a screen with a context menu provider, the legacy context menu is converted and displayed as a pop-up menu.

Command item provider

You use the CommandItemProvider class to configure a field on your UI screen so that the field can provide context and command items to the pop-up menu based on the current context. For example, you could configure an email address as a command item provider and provide the user with different actions based on whether the email address is in the user's contact list.

Command items

You use the CommandItem class to specify the text, icon, and behavior of a pop-up menu item. You define the behavior of the pop-up menu by using a command. The command acts as a proxy to an instance of a command handler, which defines the functionality of the pop-up menu item. For example, for an email address, you could provide command items to add or view a contact based on whether the selected email address appears in the user's contact list. The command handler would contain the code to add or view the contact.

For more information on commands and command handlers, see Command Framework API. The Command Framework sample application that is provided in the BlackBerry Java SDK demonstrates commands and command handlers.

If you use a legacy context menu, BlackBerry Device Software converts the context menu items to command items and provides them to the command item provider. For more information, see Support for legacy context menus.

Code sample: Creating a pop-up menu
import net.rim.device.api.command.*;
import net.rim.device.api.system.*;
import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.menu.*;
import net.rim.device.api.ui.image.*;
import net.rim.device.api.util.*;
import java.util.*;

//Create the application framework by extending the UiApplication 
//class. In main(), create an instance of the new class and invoke 
//enterEventDispatcher() to enable the application to receive 
//events. In the application constructor, invoke pushScreen() to 
//display the custom screen for the application. 
public class MyPopUpMenuApp extends UiApplication 
{
    public static void main(String[] args)
    {
        MyPopUpMenuApp theApp = new MyPopUpMenuApp();
        theApp.enterEventDispatcher();
    }
    
    public MyPopUpMenuApp()
    {
        pushScreen(new MyPopUpMenuScreen());
    }
}

//Create the custom screen for the application by extending the 
//MainScreen class. In the screen constructor, invoke setTitle() to 
//specify the title for the screen.
class MyPopUpMenuScreen extends MainScreen
{
	
	EmailAddressEditField emailAddress;
    public MyPopUpMenuScreen()
    {       
        setTitle("Pop-Up Menu Demo");

//In the screen constructor, specify a context menu provider. Pass a
//DefaultContextMenuProvider object to Screen.setContextMenuProvider() 
//to enable your screen to display a pop-up menu.
        setContextMenuProvider(new DefaultContextMenuProvider()); 
        
//In the screen constructor, create UI components that can invoke
//the pop-up menu. In the following code sample, the label uses the 
//Field.FOCUSABLE property to allow users to highlight the field.
        LabelField labelField = 
          new LabelField("Click to invoke pop-up menu", Field.FOCUSABLE);
        emailAddress =
          new EmailAddressEditField("Email address: ", "name@blackberry.com", 40);

//In the screen constructor, configure the UI components as command
//item providers. The DefaultContextMenuProvider object looks for fields
//that are configured as command item providers, and uses them to create and
//display a pop-up menu. For each component, invoke Field.setCommandItemProvider() 
//to configure the field as a command item provider. 
        ItemProvider itemProvider = new ItemProvider();
                       
        labelField.setCommandItemProvider(itemProvider);
        emailAddress.setCommandItemProvider(itemProvider);
                
        add(labelField);
        add(emailAddress);
    }
    /* To override the default functionality that prompts the user to save changes 
     * before the application closes, override the MainScreen.onSavePrompt() method. 
     * In the following code sample, the return value is true, which 
     * indicates that the application does not prompt the user before closing.
     */ 
    protected boolean onSavePrompt()
    {
        return true;
    }

//In the custom screen, implement the CommandItemProvider interface. 
//In getContext(), return the field that is configured as a command item 
//provider. In getItems(), create a Vector object to add the 
//pop-up menu items to.
    class ItemProvider implements CommandItemProvider 
    {
        public Object getContext(Field field)
        {            
            return field;
        }
        public Vector getItems(Field field)
        {            
            Vector items = new Vector();
            
//In getItems(), provide the pop-up menu items by creating instances 
//of the CommandItem class. For each command item, specify the pop-up 
//menu text, icon, and command. In the following code sample, an 
//if-then-else statement is used to check which component invoked the 
//pop-up menu before creating the CommandItem. The command is a 
//proxy to an instance of a class that extends the abstract 
//CommandHandler class. Invoke Vector.addElement() to add the 
//pop-up menu items to the Vector. Return the Vector.
            CommandItem defaultCmd;
            
            Image myIcon = 
               ImageFactory.createImage(Bitmap.getBitmapResource("my_logo.png"));
            
            if(field.equals(emailAddress)){          
                 defaultCmd = 
                    new CommandItem(new StringProvider("Email Address"),
                       myIcon, new Command(new DialogCommandHandler()));
            }
            else{
                defaultCmd = 
                  new CommandItem(new StringProvider("Label Field"),
                      myIcon, new Command(new DialogCommandHandler()));
            }

            items.addElement(defaultCmd);
          
            return items;
        }
    }

//In the custom screen, create a command handler by creating a class
//that extends the abstract CommandHandler class. In execute(), define 
//the functionality that you want to associate with the pop-up menu 
//items. This command handler could be used by any UI component on your 
//screen (for example, full menu items, buttons, and so on). Because 
//canExecute() is not implemented, this command is always executable. 
//In the following code sample, a dialog box appears when the user 
//clicks a pop-up menu item.
    class DialogCommandHandler extends CommandHandler
    {
        public void execute(ReadOnlyCommandMetadata metadata, Object context)
        {
            Dialog.alert("Executing command for " + context.toString());
        }           
    }
}

Adding a menu item to a BlackBerry Device Software application

You can add a menu item to a BlackBerry Device Software application by using the Menu Item API in the net.rim.blackberry.api.menuitem package. For example, you can add a menu item called View Sales Order to the contacts application on a BlackBerry device so that when a user clicks the menu item, a CRM application opens and displays a list of sales orders for that contact.

The ApplicationMenuItemRepository class provides the constants that specify the BlackBerry Device Software application that your menu item should appear in. For example, the MENUITEM_MESSAGE_LIST constant specifies that the menu item should appear in the messages application.

Add a menu item to a BlackBerry Device Software application

  1. Import the required classes and interfaces.
    import net.rim.blackberry.api.menuitem.*;
    import net.rim.blackberry.api.pdap.*;
    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.component.*;
  2. Extend the abstract ApplicationMenuItem class to create a menu item. Override the ApplicationMenuItem() constructor with an integer to specify the position of the menu item in the menu. A higher number positions the menu item lower in the menu.
    public class SampleMenuItem extends ApplicationMenuItem
    {
       SampleMenuItem()
       {
          super(20);
       }
    }
  3. Implement toString() to specify the menu item text.
    public String toString()
    {
       return "Open the Contacts Demo application";
    }
  4. Invoke getInstance() to retrieve the application repository.
    ApplicationMenuItemRepository repository = ApplicationMenuItemRepository.getInstance();
  5. Create an instance of a class to extend the MenuItem class.
    ContactsDemoMenuItem contactsDemoMenuItem = new ContactsDemoMenuItem();
  6. Invoke ApplicationMenuItemRepository.addMenuItem() to add the menu item to the relevant BlackBerry device application repository.
    repository.addMenuItem(ApplicationMenuItemRepository.MENUITEM_ADDRESSCARD_VIEW, contactsDemoMenuItem);
  7. Implement run() to specify the behavior of the menu item. In the following code sample, when a user clicks the new menu item and a Contact object exists, the ContactsDemo application receives the event and invokes ContactsDemo.enterEventDispatcher().
    public Object run(Object context)
    {
       BlackBerryContact c = (BlackBerryContact)context;
       if ( c != null )
       {
          new ContactsDemo().enterEventDispatcher();
       }
       else
       {
          throw new IllegalStateException( "Context is null, expected a Contact instance");
       }
       Dialog.alert("Viewing an email message in the email view");
       return null;
    }

Changing the appearance of a menu

You can change the background, border, and font of a menu by using the Menu class in the net.rim.device.api.ui.component package. For example, you can change the appearance of the menu so that it has a look and feel that is similar to the rest of your BlackBerry device application. When you change the appearance of a menu, your BlackBerry device application overrides the theme that is set on the BlackBerry device.

Code sample: Changing the appearance of a menu

import net.rim.device.api.ui.*;
import net.rim.device.api.ui.component.*;
import net.rim.device.api.ui.container.*;
import net.rim.device.api.ui.decor.*;
import net.rim.device.api.system.*;

//Create the application framework by extending the 
//UiApplication class. In main(), create an instance of 
//the new class and invoke enterEventDispatcher() to enable 
//the application to receive events. In the application 
//constructor, invoke pushScreen() to display the custom screen 
//for the application. 
public class CreateCustomMenu extends UiApplication
{
   public static void main(String[] args)
   {
      CreateCustomMenu theApp = new CreateCustomMenu();
      theApp.enterEventDispatcher();
   }
   public CreateCustomMenu()
   {
      pushScreen(new CreateCustomMenuScreen());
   }
} 

//Create the custom screen for the application by extending the 
//MainScreen class.  In the screen constructor, invoke setTitle() 
//to specify the title  for the screen. Invoke add() to add a text
//field on the screen.
class CreateCustomMenuScreen extends MainScreen
{
    Border _menuBorder;
    Background _menuBackground;
    Font _menuFont;
    
    CreateCustomMenuScreen()
    {
        setTitle("Custom Menu Sample");
        add(new RichTextField("Creating a custom menu"));
         
//In the screen constructor, specify the appearance of the menu. 
//Create the spacing for the border around the menu by creating 
//an XYEdges object. Invoke createRoundedBorder() to create a border 
//with rounded corners. Invoke createSolidTransparentBackground() to 
//create a transparent background color for the menu.
        XYEdges thickPadding = new XYEdges(10, 10, 10, 10);
        _menuBorder = BorderFactory.createRoundedBorder(thickPadding, 
                 Border.STYLE_DOTTED);        
        _menuBackground = BackgroundFactory.createSolidTransparentBackground(
                 Color.LIGHTSTEELBLUE, 50);

//In the screen constructor, specify the font for the menu by using 
//a FontFamily object. Invoke forName() to retrieve a font from on the BlackBerry
//device. Invoke getFont() to specify the style and size of the font.
        try
        {
            FontFamily family = FontFamily.forName("BBCasual");
            _menuFont = family.getFont(Font.PLAIN, 30, Ui.UNITS_px);
        }
        catch(final ClassNotFoundException cnfe)
        {
            UiApplication.getUiApplication().invokeLater(new Runnable()
            {
                public void run()
                {
                    Dialog.alert("FontFamily.forName() threw " + cnfe.toString());
                }
            });              
        }            
    }

//In the screen class, override makeMenu() to apply the appearance of the 
//menu. Invoke setBackground(), setBorder(), and setFont() to apply the 
//appearance the menu that you specified earlier.
    protected void makeMenu(Menu menu, int context)
    {
        menu.setBorder(_menuBorder);
        menu.setBackground(_menuBackground);
        menu.setFont(_menuFont);
        super.makeMenu(menu, context);
    }        
}