net.rim.blackberry.api.bbm.platform.ui
Class MenuItemManager

java.lang.Object
  |
  +--net.rim.blackberry.api.bbm.platform.ui.MenuItemManager

public abstract class MenuItemManager
extends Object

Allows a plugin to add and remove menu items in the BlackBerry Messenger application. Menu items will only be shown while a contact is highlighted and the contact has the same application. Invoking a particular menu item will result in an invitation being sent to the contact. The receiver of the invitation will get a notification through BBMPlatformConnectionListener.contactsJoined(BBMPlatformConnection, BBMPlatformContactList, String, int), where the cookie will be a String equal to menuItemId. Your application can take appropriate action once this notification is received. If the device is restarted, the menu items will be re-added automatically.

Since:
BBM SDK 1.0
See Also:
UIService.getMenuItemManager()

Method Summary
abstract  void addChannelInvitationMenuItem(int menuItemId, String invitationMessage, String label, int order)
          Adds a menu item to the BlackBerry Messenger's contact list screen.
abstract  boolean exists(int menuItemId)
          Returns true if the calling application already added a menu item with the given id.
static int getMaxLengthMenuItemLabel()
          Returns the maximum value for the length of the menu item label.
static int getMaxLengthMenuItemMessage()
          Returns the maximum value for the length of the menu item invitation message.
static int getMaxMenuItems()
          Returns the maximum number of menu items allowed per application.
abstract  InvitationMenuItem getMenuItem(int menuItemId)
          Returns a menu item for the calling application by the given id.
abstract  InvitationMenuItem[] getMenuItems()
          Returns all menu items for the calling application.
abstract  void remove(int menuItemId)
          Removes the menu item that belongs to the calling application with the provided id.
abstract  void removeAll()
          Remove all menu items (if any) belonging to the calling application.
 

Method Detail

addChannelInvitationMenuItem

public abstract void addChannelInvitationMenuItem(int menuItemId,
                                                  String invitationMessage,
                                                  String label,
                                                  int order)
Adds a menu item to the BlackBerry Messenger's contact list screen. If a menu item with the same id exists for the calling application, the existing item will be overwritten with the provided item. Clicking on the menu item, will send an invitation to the selected contact.
Parameters:
menuItemId - menu id which should not change after the device resets; it will uniquely identify the operation that is intended to be performed with this invitation
invitationMessage - message that will be displayed to the recipient, must be not null and not longer than getMaxLengthMenuItemMessage()
label - display name of the menu item, must not be null and not longer than getMaxLengthMenuItemLabel()
order - display order of this menu item; lower order items will be displayed first
Throws:
IllegalArgumentException - if invitation message is null or too long
IllegalArgumentException - if label is null or too long
IllegalArgumentException - if the application already has getMaxMenuItems() menu items
Since:
BBM SDK 1.0

exists

public abstract boolean exists(int menuItemId)
Returns true if the calling application already added a menu item with the given id.
Parameters:
menuItemId - id of the menu item being checked
Returns:
true if the calling application already added a menu item with the given id
Since:
BBM SDK 1.0

getMaxLengthMenuItemLabel

public static int getMaxLengthMenuItemLabel()
Returns the maximum value for the length of the menu item label. Current return value is 50.
Returns:
maximum value for the length of the menu label
Since:
BBM SDK 1.0

getMaxLengthMenuItemMessage

public static int getMaxLengthMenuItemMessage()
Returns the maximum value for the length of the menu item invitation message. Current return value is 128.
Returns:
maximum value for the length of the menu item invitation message
Since:
BBM SDK 1.0

getMaxMenuItems

public static int getMaxMenuItems()
Returns the maximum number of menu items allowed per application. Current return value is 10.
Returns:
maximum number of menu items allowed per application
Since:
BBM SDK 1.0

getMenuItem

public abstract InvitationMenuItem getMenuItem(int menuItemId)
Returns a menu item for the calling application by the given id.
Parameters:
menuItemId - id of the menu item
Returns:
the menu item; null if no menu item exists for menuItemId.
Since:
BBM SDK 1.2

getMenuItems

public abstract InvitationMenuItem[] getMenuItems()
Returns all menu items for the calling application.
Returns:
all menu items. This will be empty if no menu items exist.
Since:
BBM SDK 1.2

remove

public abstract void remove(int menuItemId)
Removes the menu item that belongs to the calling application with the provided id. If the id does not correspond to a menu item, nothing will be removed.
Parameters:
menuItemId - id that uniquely identifies the menu item in the calling application
Since:
BBM SDK 1.0

removeAll

public abstract void removeAll()
Remove all menu items (if any) belonging to the calling application. If no menu items are found, nothing will be done.
Since:
BBM SDK 1.0



Copyright 1999- 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.