Blackberry - How to use notification icon in statusbar - user-interface

Question

In RIM Blackberry OS 4.6+ there is a new feature - ability to show notification icon in statusbar. Integrated application use it to give quick and informative information for user: Dealler - missed calls, Messages - unread messages etc.
removed dead ImageShack link
Possible use of notification icon:
missed events
RSS updates
object status (ex. weather/app activity/gps signal strength)
other
I would like to post a howto guide for this feature.

Answer 1

ApplicationIndicator class
To add/modify/remove notification icon we can use ApplicationIndicator class:
Represents an application indicator that consists of an icon and optional numeric value.
The icon is placed in indicators area along with others such as new mail counter, calendar reminders, missed calls counter, security status and others.
Application can register only one indicator and has to register it every time the phone starts.
All indicators are cleared upon phone restart.
Indicators may be not visible if there will be no space on statusbar
Indicator dimensions depend on current theme and phone screen size.
The icon size varies from 10x10 up to 24x24.
If indicator is initialized with a big icon then an exception is thrown.
Indicator can have optional numeric value that usually serves as a counter.
The value can be negative, 0 or positive.
If indicator is used as a counter it's better to hide it when its value is equal to 0.
If indicator value is too big, it will display '99+' or '999+'
Add notification icon
For this we should create instance of ApplicationIcon:
Application icon class is used in conjunction with application indicator and application messages.
It incapsulates image and its painting properties.
EncodedImage mImage = EncodedImage.getEncodedImageResource("indicator_icon.png");
ApplicationIcon mIcon = new ApplicationIcon(mImage);
Then we should register ApplicationIndicator with ApplicationIndicatorRegistry:
ApplicationIndicatorRegistry.register(icon, iconOnly, visible)
icon - an icon to be displayed in the indicators area
iconOnly - specifies if indicator should have icon representation only and no value
visible - specifies whether indicator has to be visible initially
ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();
ApplicationIndicator indicator = reg.register(mIcon, false, true);
Modify indicator icon and value
To modify icon, use ApplicationIndicator.setIcon method:
ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();
ApplicationIndicator appIndicator = reg.getApplicationIndicator();
appIndicator.setIcon(icon);
To modify number value, use ApplicationIndicator.setValue method:
ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();
ApplicationIndicator appIndicator = reg.getApplicationIndicator();
appIndicator.setValue(value);
If very big value is provided then indicator will display '99+' or '999+'.
To hide or show indicator, use ApplicationIndicator.setVisible
Unregister ApplicationIndicator
Most likely you don't want your app indicator to stay in statusbar, it's better to ApplicationIndicatorRegistry.unregister() it on app close.
Sample application
Icons:
removed dead ImageShack links
Screenshots:
removed dead ImageShack links
Code:
import net.rim.blackberry.api.messagelist.ApplicationIcon;
import net.rim.blackberry.api.messagelist.ApplicationIndicator;
import net.rim.blackberry.api.messagelist.ApplicationIndicatorRegistry;
import net.rim.device.api.system.EncodedImage;
import net.rim.device.api.ui.MenuItem;
import net.rim.device.api.ui.component.LabelField;
import net.rim.device.api.ui.component.Menu;
import net.rim.device.api.ui.container.MainScreen;
class Scr extends MainScreen {
EncodedImage mImageGreen = EncodedImage
.getEncodedImageResource("bb_icon_green.png");
ApplicationIcon mIconGreen = new ApplicationIcon(mImageGreen);
EncodedImage mImageRed = EncodedImage
.getEncodedImageResource("bb_icon_red.png");
ApplicationIcon mIconRed = new ApplicationIcon(mImageRed);
ApplicationIcon mIcon = mIconGreen;
public Scr() {
add(new LabelField("Use menu to:"));
add(new LabelField("Register indicator"));
add(new LabelField("Increment value"));
add(new LabelField("Decrement value"));
add(new LabelField("Switch icon"));
add(new LabelField("Unregister indicator"));
}
MenuItem menuRegister = new MenuItem("register", 0, 0) {
public void run() {
registerIndicator();
};
};
protected int mValue = 0;
MenuItem menuIncrement = new MenuItem("increment", 0, 0) {
public void run() {
mValue++;
updateValue(mValue);
};
};
MenuItem menuDecrement = new MenuItem("decrement", 0, 0) {
public void run() {
mValue--;
updateValue(mValue);
};
};
MenuItem menuSwitchIcon = new MenuItem("icon", 0, 0) {
public void run() {
mIcon = (mIcon == mIconGreen) ? mIconRed : mIconGreen;
updateIcon(mIcon);
};
};
MenuItem menuUnregister = new MenuItem("unregister", 0, 0) {
public void run() {
unregisterIndicator();
};
};
protected void makeMenu(Menu menu, int instance) {
super.makeMenu(menu, instance);
menu.add(menuRegister);
menu.add(menuIncrement);
menu.add(menuDecrement);
menu.add(menuSwitchIcon);
menu.add(menuUnregister);
}
private void registerIndicator() {
try {
ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry
.getInstance();
ApplicationIndicator indicator =
reg.register(mIcon, false, true);
} catch (Exception e) {
}
}
private void unregisterIndicator() {
try {
ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry
.getInstance();
reg.unregister();
} catch (Exception e) {
}
}
void updateValue(int value) {
try {
ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry
.getInstance();
ApplicationIndicator appIndicator =
reg.getApplicationIndicator();
appIndicator.setValue(value);
} catch (Exception e) {
}
}
void updateIcon(ApplicationIcon icon) {
try {
ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry
.getInstance();
ApplicationIndicator appIndicator =
reg.getApplicationIndicator();
appIndicator.setIcon(icon);
} catch (Exception e) {
}
}
}