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

Image recommendations

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



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.