net.rim.device.api.content
Class ContentHandlerMenu

java.lang.Object
  net.rim.device.api.ui.component.Menu
      net.rim.device.api.ui.menu.SubMenu
          net.rim.device.api.content.ContentHandlerMenu

public class ContentHandlerMenu
extends SubMenu

A submenu that provides the user with options to open/play/edit content with different applications that are registered with the Content Handler Registry.

Applications can add this submenu to their menus when content has focus. Consider adding this submenu when there is more than one application that can handle the content. The sample code below shows how to determine when you should display the submenu.

Applications in the submenu are sorted in alphabetical order. If there is a default content handler, then that handler's menu item is highlighted by default.

Pop-up Menu Support

A content handler menu item can be added to a pop-up menu using the Command Framework. The content handler command can be accessed using command ID "ContentHandlerCommand". The context provided to the command must not be null Invocation. A code sample is provided below.

Sample Code for Content Handler Submenu

The following code sample demonstrates how to add the content handler submenu to a Manager in an application.

 // overrides Manager.makeMenu
 protected void makeMenu(Menu menu, int instance) {
     String selectedFileURL = getSelectedFileURL(); // obtain the URL of the selected file which will be acted upon
     String type = null;// could also use MIMETypeAssociations.getMIMEType(filename);
     Invocation invocation = new Invocation(selectedFileURL, type, null);
     Registry registry = Registry.getRegistry(getClass().getName());
     invocation.setAction(ContentHandler.ACTION_OPEN);
   
      // only add the menu if there is more than one handler application
      if (ContentHandlerMenu.hasMultipleHandlers(invocation, registry) {
          // There is also a constructor to use a resource bundle     
          ContentHandlerMenu contentHandlerMenu = new ContentHandlerMenu(invocation, registry, "Open With", 0, 0);
          menu.add(contentHandlerMenu);
      }
 }
 

Sample Code for Content Handler Pop-up Menu Support

The following code sample demonstrates how to add the content handler to the pop-up menu. Pop-up menus are populated using the Command Framework. The pop-up menu items are provided by an implementation of a CommandItemProvider. The code sample demonstrates the methods that are required to be implemented by the CommandItemProvider. The Content Handler command takes an Invocation object as the context when executing the command. The sample code shows a custom LabelField that returns an Invocation for the field.

      public class MyCommandItemProvider implements CommandItemProvider {

            // See CommandItemProvider.getContext
            // Returns the context for a given field.
            // Recall the Invocation is used as context when the command executes 
            public Object getContext(Field field) {
                Object context = null;

                if (field instanceof ContentHandlerLabelField) {
                    ContentHandlerLabelField handlerLabel = (ContentHandlerLabelField)field;
                    context = handlerLabel.getInvocation();
                }

                return context;

            }

            // See CommandItemProvider.getItems
            public Vector getItems(Field field) {
                Vector items = null;

                if (field instanceof ContentHandlerLabelField) {
                    CommandRegistrarConnection connection = new RemoteCommandRegistrarConnection();
                    CommandRequest request = new CommandRequest("ContentHandlerCommand");
                    Command command = connection.getCommand( request );
                    items = new Vector();
                    items.addElement(new CommandItem(new StringProvider("Open with"), null, command));
                }

                return items;
            }

            static class ContentHandlerLabelField extends LabelField {        
                private final Invocation _invocation;

                ContentHandlerLabelField(Object text, Invocation invocation, long style) {
                    super(text, style|LabelField.FOCUSABLE);
                    _invocation = invocation;
                }

                Invocation getInvocation() {
                    return _invocation;
                }        
            }
        }
 

See Also:

Invocation, Registry, Command, CommandItemProvider

Since:

BlackBerry API 6.0.0

Field Summary

Fields inherited from class net.rim.device.api.ui.component.Menu

CANCELLED, INSTANCE_CONTEXT, INSTANCE_CONTEXT_SELECTION, INSTANCE_DEFAULT, INSTANCE_FROM_MENU_KEY, MENU_POPUP, SORTED, UNDEFINED

Constructor Summary

ContentHandlerMenu(Invocation invocation, Registry registry, String text, int ordering, int priority)
Creates a content handler submenu for the given invocation and registry.

ContentHandlerMenu(Invocation invocation, Registry registry, ResourceBundle rb, int rbid, int ordering, int priority)
Creates a content handler submenu for the given invocation and registry.

Method Summary
static boolean	hasMultipleHandlers(Invocation invocation, Registry registry) Determines whether an invocation has multiple handlers.

Methods inherited from class net.rim.device.api.ui.menu.SubMenu

getMenuItem, getMenuItemRunnable, setMenuItemRunnable

Methods inherited from class net.rim.device.api.ui.component.Menu

add, add, add, add, add, addSeparator, close, deleteAll, deleteItem, getBackground, getBorder, getCaretBackground, getDefault, getFont, getItem, getItemCookie, getItemId, getSelectedCookie, getSelectedId, getSelectedItem, getSize, isDisplayed, setBackground, setBorder, setCaretBackground, setDefault, setDefault, setFont, setItemHighlight, setTarget, show

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ContentHandlerMenu

public ContentHandlerMenu(Invocation invocation,
                          Registry registry,
                          ResourceBundle rb,
                          int rbid,
                          int ordering,
                          int priority)

Creates a content handler submenu for the given invocation and registry. The submenu contains applications that can handle the given invocation.

Parameters:

invocation - Contains the details about the content and the action that will be performed.

registry - The content handler registry that will be used to look up the handlers.

rb - Resource bundle which contains the text string to identify the submenu in the parent menu.

rbId - Identifier of the submenu text string within the resource bundle rb.

ordering - Ordering of the submenu item relative to other items in the parent menu.

priority - Priority of the submenu item within the parent menu.

Since:

BlackBerry API 6.0.0

ContentHandlerMenu

public ContentHandlerMenu(Invocation invocation,
                          Registry registry,
                          String text,
                          int ordering,
                          int priority)

Creates a content handler submenu for the given invocation and registry. The submenu contains applications that can handle the given invocation.

Parameters:

invocation - Contains the details about the content and the action that will be performed.

registry - The content handler registry that will be used to look up the handlers.

text - Text to identify the submenu item in the parent menu.

ordering - Ordering of the submenu item relative to other items in the parent menu.

priority - Priority of the submenu item within the parent menu.

Since:

BlackBerry API 6.0.0

Method Detail

hasMultipleHandlers

public static boolean hasMultipleHandlers(Invocation invocation,
                                          Registry registry)

Determines whether an invocation has multiple handlers. See the sample code above for an example usage.

Parameters:

invocation - Contains the details about the content and the action that will be performed.

registry - The content handler registry that will be used to look up the handlers.

Returns:

true if the given invocation has more than one handler; false otherwise.

Since:

BlackBerry API 6.0.0