Profile Box
Provides access to the current user's profile box.
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.
Permission Model
The user must manually show the profile box via the "activities" option in the BBM options screen for the application. The application can add items whether or not this option is enabled.The application can read profileboxEnabled to determine if the user is showing the profile box, and prompt them to enable it with blackberry.bbm.platform.showBBMAppOptions.
Icon 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 by assigning a callback to blackberry.bbm.platform.onappinvoked.
Supported Platform(s)
- BlackBerry OS 5.0+ |
API | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
blackberry.bbm.platform.self.profilebox.addItem | Y | Y | Y | ||||
blackberry.bbm.platform.self.profilebox.clearItems | Y | Y | Y | ||||
blackberry.bbm.platform.self.profilebox.removeItem | Y | Y | Y | ||||
accessible | Y | Y | Y | ||||
items | Y | Y | Y |
Configuration Document Settings
To use all of the API described for this object, you must ensure the following settings are in your configuration document: |
You must declare the feature element(s) below in your configuration document: |
Feature ID | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
<feature id="blackberry.bbm.platform" /> | Y | Y | Y |
Permission Elements (PlayBook and BlackBerry 10+) |
---|
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
Functions
Properties
Functions
static
blackberry.bbm.platform.self.profilebox.ProfileBoxItem
blackberry.bbm.platform.self.profilebox.addItem
(options : Object)
Adds an item to the top of the user's profile box.
Icons are optional and are provided via a fully-qualified URI. Non-local URIs must be whitelisted in the application's configuration file. Examples:
- Locally from within the widget package (e.g. "local:///smiley.jpg")
- From the file system of the device (e.g. "file:///SDCard/BlackBerry/pictures/smiley.jpg")
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
options |
The options.
text: The text of the item. icon: Optional The URI of the icon to use. If not provided, no icon is used. cookie: Optional The customizable cookie. |
Throws | |
---|---|
UserProfileBoxAccessException | If the profile box is inaccessible. |
Return:
The new item.
Code Example:
|
|
static
void
blackberry.bbm.platform.self.profilebox.clearItems
()
Removes all items.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Throws | |
---|---|
UserProfileBoxAccessException | If the profile box is inaccessible. |
static
void
blackberry.bbm.platform.self.profilebox.removeItem
(item : blackberry.bbm.platform.self.profilebox.ProfileBoxItem)
Removes an item.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
item | The item to remove. |
Throws | |
---|---|
UserProfileBoxAccessException | If the profile box is inaccessible. |
Properties
static
readonly
Boolean
accessible
true
if the profile box is accessible and can be updated; false
otherwise.
The profile box is not accessible when the device is in mass storage mode.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
static
readonly
blackberry.bbm.platform.self.profilebox.ProfileBoxItem[]
items
The profile box items. undefined
if the device is in mass storage mode.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |