net.rim.device.api.ui.menu
Class DefaultContextMenuProvider

java.lang.Object
  extended by net.rim.device.api.ui.menu.DefaultContextMenuProvider
All Implemented Interfaces:
ContextMenuProvider

public final class DefaultContextMenuProvider
extends Object
implements ContextMenuProvider

Implements ContextMenuProvider to display a screen's pop-up menu. Pass a DefaultContextMenuProvider object into Screen.setContextMenuProvider() in order to display a pop-up menu on your screen. 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.

A pop-up menu should provide users with access to the most common actions for the current context. If only a single action is associated with the current context, that action would be performed instead of invoking the pop-up menu. An item in the pop-up menu can contain both an icon and text. If the text is too long to display in the pop-up menu, it is truncated with an ellipsis (...). If you do not provide an icon, then a default icon is used.

When a user invokes a pop-up menu, the DefaultContextMenuProvider looks for fields configured as a CommandItemProvider. A command item provider provides CommandItems to add to the pop-up menu based on the context. A command item specifies the text and icon to display in the pop-up menu, and the Command to perform when the user selects the pop-up menu item. See the Command Framework API for more information on commands.

For example, an EmailAddressEditField might be configured with a command item provider that adds items like Copy and Add To Contacts to the pop-up menu.

Specifying the default item and the order of items in the pop-up menu

Pop-up menus display items in a 3x3, 3x2, or 3x1 grid depending on the number of items. It displays the first 8 items that you provide and always displays an item to open the full menu. If you provide more than 8 items, they are not displayed. Consider adding these items to the full menu instead.

The default item appears in the center of the grid. The others are positioned in the pop-up menu based on the order that command items are provided in.

       2 | 3 | 4         2 | 3 | 4
       5 | 1 | 6         5 | 1 | x         2 | 1 | x
       7 | 8 | x
 

1 is the default highlighted item and x is the full menu item.

If the number of items provided to the pop-up menu leaves any empty cells in the grid, an option to switch applications is added in the first empty cell, and a home option is added to the second empty cell, if applicable.

Support for legacy context menus

If you have an existing implementation of a context menu from an earlier version of the BlackBerry API, the context menu items are converted into a pop-up menu. The default item remains the default (that is, it becomes the first command item returned by the command item provider) and the remaining items are ordered by using the item's ordinal. Icons associated with a context menu item in your legacy context menu are used in the pop-up menu.

However, even with legacy context menus, only the first 8 items are displayed in the pop-up menu. If you previously provided more than 8, consider evaluating the ordinals to ensure that the most important items are added to the pop-up menu (that is, so that these important items are returned by the command item provider).

Sample code

The following code sample demonstrates how to add a pop-up menu to a screen and to configure fields as a CommandItemProvider.
 class MyCmdFrameworkScreen extends MainScreen
 {
     public MyCmdFrameworkScreen()
     {
         setTitle("Command Framework Demo");

         // set a context menu provider for this screen
         setContextMenuProvider(new DefaultContextMenuProvider());

         LabelField labelField = new LabelField("My Label", Field.FOCUSABLE);
         LabelField labelField2 = new LabelField("My Label 2", Field.FOCUSABLE);

         // create an ItemProvider object, where ItemProvider is a class that
         // implements the CommandItemProvider interface and provides a
         // field's command items
         ItemProvider itemProvider = new ItemProvider();

         // configure the fields as command item providers
         labelField.setCommandItemProvider(itemProvider);
         labelField2.setCommandItemProvider(itemProvider);

         add(labelField);
         add(labelField2);
     }

     protected boolean onSavePrompt()
     {
         return true;
     }  
 }
 

The Command Framework sample application that is provided in the BlackBerry Java SDK demonstrates commands, command handlers, and command item providers.

Since:
BlackBerry API 6.0.0

Constructor Summary
DefaultContextMenuProvider()
           
 
Method Summary
 boolean showContextMenu(Screen screen)
          Displays a pop-up menu.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

DefaultContextMenuProvider

public DefaultContextMenuProvider()
Since:
BlackBerry API 6.0.0


Method Detail

showContextMenu

public boolean showContextMenu(Screen screen)
Displays a pop-up menu.

Specified by:
showContextMenu in interface ContextMenuProvider
Parameters:
screen - The screen displaying the pop-up menu.
Returns:
true if the event was handled, false otherwise.
Since:
BlackBerry API 6.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal