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