net.rim.device.api.content
Class ContentHandlerMenu

java.lang.Object
  extended by net.rim.device.api.ui.component.Menu
      extended by net.rim.device.api.ui.menu.SubMenu
          extended by 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, 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
 
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





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.