Blackberry - How to use notification icon in statusbar

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.

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) {
        }
    }
}