net.rim.blackberry.api.bbm.platform.profile
Class UserProfileBox

java.lang.Object
  |
  +--net.rim.blackberry.api.bbm.platform.profile.UserProfileBox

public abstract class UserProfileBox

extends Object

A box for this application that appears in the current user's profile. Each box contains a list of items, each composed of text and an optional icon. There is a maximum of 3 items; as more are added, older items will be removed automatically.

This box can be viewed by the current user and their contacts, and is editable by the current user and the owning application (on this device). The current user can only remove items.

The user can control whether an application's profile box appears in his or her profile using the BBM options for the application. Applications can modify the profile box whether or not the user has enabled it. Applications can query this setting using SettingsManager.

Icons

Before icons can be used in profile box items, a static set of icons must be registered using registerIcon(int, EncodedImage). An application should register its entire set of icons initially. This improves speed when the current user views this application in their contacts' profiles. Since icons are registered to the filesystem this should be done on a non-event thread.

Icon IDs

• Each icon must be given a unique non-negative ID.
• Each icon ID must map to the same icon on all devices. Images generated at runtime such as screenshots are not acceptable for use.
• A new version of the same icon should not be registered under the same icon ID.

Image recommendations

• Recommended icon size is 100x100, regardless of device.
• Icons should be square.
• Alpha is supported.
• Animating icons are not supported. Only the first frame will be used.

Launching your application from the profile box

The user can invoke an application through its profile box items in their profile or a contact's profile. The application will be brought to the foreground and/or launched if not yet running. The invoking profile box item can be obtained overriding BBMPlatformContextListener.appInvoked(int, Object) with the reason code BBMPlatformContext.INVOKE_PROFILE_BOX_ITEM.

Method Summary

abstract UserProfileBoxItem	addItem(int iconId, String text) Adds an item with icon and text.
abstract UserProfileBoxItem	addItem(int iconId, String text, String cookie) Adds an item with icon, text, and a customizable parameter.
abstract UserProfileBoxItem	addItem(String text) Adds an item with text.
abstract EncodedImage	getIcon(int iconId) Gets a registered icon by its ID.
abstract UserProfileBoxItem	getItem(int itemId) Returns an item by its ID.
abstract int	getItemCount() Returns the number of items.
abstract int[]	getItemIds() Returns the item IDs.
abstract UserProfileBoxItem[]	getItems() Returns the items.
abstract boolean	isAccessible() Returns whether the profile box is accessible and can be updated.
abstract boolean	isIconRegistered(int iconId) Returns whether an icon is registered for an icon ID.
abstract void	registerIcon(int iconId, EncodedImage icon) Registers a static icon for use in profile box items.
abstract void	removeAllItems() Removes all items.
abstract UserProfileBoxItem	removeItem(int itemId) Removes an item by its ID.

Method Detail

addItem

public abstract UserProfileBoxItem addItem(int iconId,
                                           String text)
                                    throws UserProfileBoxAccessException

Adds an item with icon and text.

Parameters:

iconId - The ID of a registered icon. -1 if there is no icon.

text - The item text.

Returns:

the added item.

Throws:

IllegalArgumentException - if text.length() > 100 or text has more than 2 new line characters.

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

addItem

public abstract UserProfileBoxItem addItem(int iconId,
                                           String text,
                                           String cookie)
                                    throws UserProfileBoxAccessException

Adds an item with icon, text, and a customizable parameter.

Parameters:

iconId - The ID of a registered icon. -1 if there is no icon.

text - The item text.

cookie - The customizable item parameter.

Returns:

the added item.

Throws:

IllegalArgumentException - if text.length() > 100 or text has more than 2 new line characters.

IllegalArgumentException - if cookie.length() > 128.

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

addItem

public abstract UserProfileBoxItem addItem(String text)
                                    throws UserProfileBoxAccessException

Adds an item with text.

Parameters:

text - The text for the item.

Returns:

the added item.

Throws:

IllegalArgumentException - if text.length() > 100 or text has more than 2 new line characters.

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

getIcon

public abstract EncodedImage getIcon(int iconId)
                              throws UserProfileBoxAccessException

Gets a registered icon by its ID.

Parameters:

iconId - The icon's ID.

Returns:

the registered icon, or null if no icon is registered for iconId.

Throws:

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

getItem

public abstract UserProfileBoxItem getItem(int itemId)
                                    throws UserProfileBoxAccessException

Returns an item by its ID.

Parameters:

itemId - The item ID.

Returns:

the item, or null if there is no item for itemId.

Throws:

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

getItemCount

public abstract int getItemCount()
                          throws UserProfileBoxAccessException

Returns the number of items.

Returns:

the number of items.

Throws:

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

getItemIds

public abstract int[] getItemIds()
                          throws UserProfileBoxAccessException

Returns the item IDs.

Returns:

the item IDs.

Throws:

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

getItems

public abstract UserProfileBoxItem[] getItems()
                                       throws UserProfileBoxAccessException

Returns the items.

Returns:

the items.

Throws:

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

isAccessible

public abstract boolean isAccessible()

Returns whether the profile box is accessible and can be updated. The profile box is not accessible when the device is in mass storage mode.

Returns:

true if the profile box is accessible; false otherwise.

Since:

BBM SDK 1.0

isIconRegistered

public abstract boolean isIconRegistered(int iconId)
                                  throws UserProfileBoxAccessException

Returns whether an icon is registered for an icon ID.

Parameters:

iconId - The icon ID to check.

Returns:

true if an icon with ID iconId is registered; false otherwise.

Throws:

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

registerIcon

public abstract void registerIcon(int iconId,
                                  EncodedImage icon)
                           throws UserProfileBoxAccessException

Registers a static icon for use in profile box items. Since icons are registered to the filesystem this should be done on a non-event thread.

Parameters:

iconId - The icon ID. Must be >= 0.

icon - The icon.

Throws:

IllegalArgumentException - if iconId < 0.

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

removeAllItems

public abstract void removeAllItems()
                             throws UserProfileBoxAccessException

Removes all items. This cannot be undone.

Throws:

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0

removeItem

public abstract UserProfileBoxItem removeItem(int itemId)
                                       throws UserProfileBoxAccessException

Removes an item by its ID.

Parameters:

itemId - The item ID.

Returns:

The removed item, or null if the item was not found.

Throws:

UserProfileBoxAccessException - if the device is in mass storage mode.

Since:

BBM SDK 1.0