Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

Integrating the BlackBerry 6 pop-up menu in your application and best practices

by Retired on ‎08-03-2010 11:25 AM - edited on ‎09-20-2010 05:06 PM by Retired (8,336 Views)

Integrating the BlackBerry 6 pop-up menu in your application and best practices


  • BlackBerry® Java® SDK 6.0 and later
  • BlackBerry® JDE
  • BlackBerry Java Plug-in for Eclipse®
  • BlackBerry Java Plug-in for Microsoft® Visual Studio®



BlackBerry 6 brings exciting enhancements to the BlackBerry platform by providing a rich set of new APIs for developers.  One of the new features is the new pop-up menu.  A pop-up menu provides users with a quick way to access the most common actions for a highlighted item.  From an application development perspective, it allows you to group a list of most commonly available actions that users can perform into a 3x3, 2x3 or a 1x3 visually appealing pop-up grid.  Every action can include descriptive text, an application icon, and a command.  Additionally the menu is context sensitive so you can assign specific actions depending on the current user context. 


For the user, bringing up the pop-up menu is simple and intuitive.  On touch screen devices, it can be displayed by tapping the touch screen.  On devices supporting a trackpad or trackball, it can be displayed by clicking the trackpad or trackball.  If a primary action is assigned to a tap or click (for example, opening an email message in the message list) then the user can bring it up by touching and holding a finger on the screen or clicking and holding the trackpad or trackball. 



Creating a pop-up  menu


You can create a pop-up menu by using the net.rim.device.api.ui.menu package and define the functionality of the pop-up menu items by using the following classes from the Command Framework API.


You use the DefaultContextMenuProvider class to create and display a screen's pop-up menu. When a user invokes a pop-up menu, the context menu provider looks for fields that are command item providers. This class 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. 



You use the CommandItemProvider class to configure a field on your UI screen so that it can provide context and command items to the pop-up menu based on the current context. 



 You use 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 actually defines the functionality of the pop-up menu item. 


The sample code below put is all together. 



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.*;


public class MyPopUpMenu extends UiApplication {

         public static void main(String[] args) {

                 MyPopUpMenu theApp = new MyPopUpMenu();




         public MyPopUpMenu() {

                 pushScreen(new MyPopUpMenuScreen());




class MyPopUpMenuScreen extends MainScreen {

         EmailAddressEditField emailAddress;


         public MyPopUpMenuScreen() {

                 setTitle("Pop-Up Menu Demo");

                 setContextMenuProvider(new DefaultContextMenuProvider());


                 LabelField labelField = new LabelField("Click to invoke pop-up menu",


                 emailAddress = new EmailAddressEditField("Email address: ",

                                   "name@blackberry.com", 40);

                 ItemProvider itemProvider = new ItemProvider();








          * 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;



         class ItemProvider implements CommandItemProvider {

                 public Object getContext(Field field) {

                          return field;



                 public Vector getItems(Field field) {

                          Vector items = new Vector();

                          CommandItem defaultCmd;

                          Image myIcon = ImageFactory.createImage(Bitmap


                          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()));



                          return items;




         class DialogCommandHandler extends CommandHandler {

                 public void execute(ReadOnlyCommandMetadata metadata, Object context) {

                          Dialog.alert("Executing command for " + context.toString());






Best Practices


When using the pop-up menu in your application, positioning of the items is critical in order to create a consistent user experience.  As shown below, the best practice is to place the default action of the menu in the centre position and the contextual actions in the numbered positions.  The full menu option is automatically added at the last position giving the user the option to invoke the full menu at any point.




When choosing the positions for the action items you should place them as consistently as possible to leverage muscle memory.  This ensures that users get accustomed to the placement and don’t have to look for actions every time the pop-up menu is invoked.  Order of items should be chosen as the most common to least common according to the numbered positions.  If an action involves choice, display the choices in a dialog box.  For example, if a contact has more than one phone number, provide a "Call" item in the pop-up menu and then display a dialog box to allow users to choose a phone number.  If your use case requires dynamic action items then don’t display them when they are unavailable.  Instead, shift the position of the available items and resize the pop-up menu as necessary.   



Support for legacy context menu


If your application is compiled with a version of BlackBerry Java SDK earlier than 6.0, the application's context menu or short menu is automatically converted to a pop-up menu. Whether you added items to a context menu or relied on the items that were added to the context menu by default, you do not have to do anything to your code to have these items appear in the pop-up menu instead. However, the BlackBerry Java SDK 6.0 includes classes and interfaces to build a pop-up menu, and allows you to leverage the Command Framework API and make your code more modular. For example, if your application has a UI component and a menu item performing the same functionality, by using the Command Framework API, you can write that functionality once and use it across your application and made it available for other applications to use as well.


When a context menu is converted to a pop-up menu, the menu item that has the lowest ordinal becomes the default pop-upmenu item. The remaining items are added to the vector from the lowest ordinal value to the highest. If an icon was associated with a menu item in your legacy context menu, it is used in the pop-up menu. Otherwise, a default icon is used. As with other pop-up menus, only the first 8 context menu items are displayed in the pop-up menu. If the context menu has more than 8 menu items, ensure that the ordinals for the menu items are used appropriately so that the most important and useful items appear in the pop-up menu.


For more information on legacy context menus see:


Users Online
Currently online: 11 members 557 guests
Please welcome our newest community members: