A custom indicator appears on the Home screen along with other indicators, such as the new message indicator and calendar reminders. You can use the ApplicationIndicator class to create and manage an indicator for custom messages. For example, you can create an indicator to display the number of unread custom messages in the message list. Indicators are visible even when the BlackBerry® device is locked. Your application can register only one indicator and must register the indicator every time that the BlackBerry device starts. The size of an indicator can vary depending on the device and theme. For more information on the size of an indicator, see the UI Guidelines for BlackBerry Smartphones.

1. Import the required classes and interfaces.

   import net.rim.blackberry.api.messagelist.*;
   import net.rim.device.api.system.EncodedImage;

2. Obtain a reference to an ApplicationIndicatorRegistry object.

   ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();

3. Create an indicator based on an encoded image by invoking EncodedImage.getEncodedImageResource() and passing in the file name as an argument. Save a reference to the encoded image in an EncodedImage variable. Create an instance of the ApplicationIcon class using the EncodedImage as an argument.

   EncodedImage image = EncodedImage.getEncodedImageResource( "clowds.gif" );
   ApplicationIcon icon = new ApplicationIcon( image );

4. Register the icon as an application indicator by invoking ApplicationIndicatorRegistry.register(). In the following code sample, the second parameter specifies that the indicator can have a numeric value associated with it (for example, new message count). The third parameter specifies that the indicator should be visible.

   ApplicationIndicator indicator = reg.register( icon, false, true);

5. Retrieve the registered indicator by invoking ApplicationIndicatorRegistry.getApplicationIndicator(). Save the return value in an ApplicationIndicator variable.

   ApplicationIndicator appIndicator = reg.getApplicationIndicator();

6. Set the icon and value for the indicator by invoking ApplicationIndicator.set(). You should consider only showing a value if it is greater than 0.

   appIndicator.set( newIcon, newValue );