Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Using custom messages and folders in the message list

You can use the net.rim.blackberry.api.messagelist package to create custom messages and folders for a BlackBerry device application.

To use custom folders and messages in an application, you must create an application with the following modules:

  • A UI module to interact with a BlackBerry device user
  • A service module to interact with an application server and perform other actions in the background

Both modules are part of the same application but have different application entry points.

You must determine the functionality that is part of each module. For example, a menu item that lets the user delete a message or mark a message as read should be part of the service module. A menu item that lets the user open or reply to a message should be part of the UI module.

See the Message List Demo sample application that is included in the for a demonstration on how to use this API.

Creating a module for background processes

A service module interacts with an application server and performs other actions in the background. It starts automatically when the BlackBerry device starts and runs without input from a BlackBerry device user. The service module can send messages to and receive messages from an application server and can add messages to the message list. The messages that it sends can use any protocol you want (for example, a native protocol, an email message protocol, or an SMS text message protocol). The user cannot stop the service module.

When the device starts, the service module should register an application folder and listen for updates to the folder, such as when the user deletes a message or marks a message as read or unread.

Creating a module for the UI

The UI module contains UI components and is used to interact with a BlackBerry device user. Typically, the UI module starts automatically when the user interacts with a custom message. For example, if the user highlights a custom message in the Messages application and clicks the trackpad or touches the touch screen, the UI module should start and display the message content. If the UI module is not running and the user attempts to open a custom message, the UI module starts automatically. The UI module can also let users reply to a message and compose a new message.

Create a module for background processes

Create a project with settings that start the application automatically. In the BlackBerry Java Plug-in for Eclipse, select the Auto-run on startup check box in the BlackBerry Application Descriptor. For more information, see the BlackBerry Java Plug-in for Eclipse Development Guide.

Create a class with the fields and methods for the module.

Compile the project into a .jad file.

Include the .jad file with the .jad files for the UI module and the main part of the application.

Starting the module for background processes or the module for the UI

import net.rim.blackberry.api.messagelist.*;

//Create a main method for the BlackBerry device application.
public static void main( String[] args )
{
   try 
   {

//In main(), check if the value of the args parameter indicates 
//that the application should start the service module or the UI module.
       if( args.length == 1 && args[ 0 ].equals( "service" ) ) 
       {

//If the application should start the service module, in the first 
//if statement, create an instance of a class that contains the service 
//functionality and items. Obtain a reference to an 
//ApplicationMessageFolderRegistry object.
           MLSampleService service = new MLSampleService();
           ApplicationMessageFolderRegistry reg = 
              ApplicationMessageFolderRegistry.getInstance();
       } 
       else if( args.length == 1 && args[ 0 ].equals( "gui" ) ) 
       {   

//If the application should start the UI module, in the else if statement, 
//create an instance of a class that contains the UI functionality and items. 
//For example, the UI module should start if the BlackBerry
//device user clicks the application icon on the Home screen or opens a custom
//message in the Messages application. Display the UI for the application and add
//the application to the event dispatcher.
           MLSampleGui gui = new MLSampleGui();
           gui.showGui();
           gui.enterEventDispatcher();
       }
   }
}

Create an icon for a custom message

You can associate icons with a custom message. You associate an icon with a custom message's type and status. For example, you can associate one icon with an unopened message and a different icon with an opened message. The icon appears on the left side of a message in the Messages application.

Import the required classes and interfaces.

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

Invoke EncodedImage.getEncodedImageResource() to create an icon based on an encoded image. Pass in the file name as an argument.

ApplicationIcon newIcon = 
   new ApplicationIcon( EncodedImage.getEncodedImageResource( "ml_sample_new.png" ) );
ApplicationIcon openedIcon = 
   new ApplicationIcon( EncodedImage.getEncodedImageResource( "ml_sample_opened.png" ) );

Invoke ApplicationMessageFolderRegistry.registerMessageIcon() to assign a status and an icon to a custom message. Specify the following as arguments: a value for the message type for a BlackBerry device application, a message status by using a field from the ApplicationMessage.Status interface, and an instance of the ApplicationIcon class.

int MESSAGE_TYPE = 0;
int STATUS_NEW = ApplicationMessage.Status.UNOPENED;
int STATUS_OPENED = ApplicationMessage.Status.OPENED;

reg.registerMessageIcon( MESSAGE_TYPE, STATUS_NEW, newIcon );
reg.registerMessageIcon( MESSAGE_TYPE, STATUS_OPENED, openedIcon );

Create a custom folder in the message list

Custom messages are maintained in custom folders. To perform operations on custom messages, your BlackBerry device application must register at least one custom folder.

Import the required classes and interfaces.

import net.rim.blackberry.api.messagelist.*;
import net.rim.device.api.collection.ReadableList;

Create a class that implements the ApplicationMessage interface.

public class MLSampleMessage implements ApplicationMessage

Obtain a reference to an ApplicationMessageFolderRegistry object.

ApplicationMessageFolderRegistry reg = 
   ApplicationMessageFolderRegistry.getInstance();

Invoke ApplicationMessageFolderRegistry.registerFolder() to register a custom folder for each collection of messages.

// collections of MLSampleMessage instances 
ReadableList inboxMessages = messages.getInboxMessages(); 
ReadableList deletedMessages = messages.getDeletedMessages(); 

ApplicationMessageFolder inboxFolder = reg.registerFolder( 
   INBOX_FOLDER_ID, 
   "Inbox", 
   inboxMessages );
ApplicationMessageFolder deletedFolder = reg.registerFolder( 
   DELETED_FOLDER_ID, 
   "Deleted Messages",   
   deletedMessages, 
   false );

Invoke ApplicationMessageFolder.addListener() to add a listener so that your application can be notified when specific folder events occur. In the following code sample, the application listens for deleted messages. For a list of all actions that you can listen for, see the documentation for the ApplicationMessageFolderListener class in the API reference for the .

deletedFolder.addListener( this, 
   ApplicationMessageFolderListener.MESSAGE_DELETED );

Create a class that implements the ApplicationMessageFolderListener interface.

public class AppFolderListener implements ApplicationMessageFolderListener

Implement ApplicationMessageFolderListener.actionPerformed() to perform actions when a folder event occurs.

public void actionPerformed( int action, ApplicationMessage[] messages, 
   ApplicationMessageFolder folder ) 
{
   // check if action was performed on multiple messages
   if( messages.length == 1 )  
   {
     switch( action ) 
     {
        case ApplicationMessageFolderListener.MESSAGE_DELETED:
           messageStore.deleteInboxMessage( message );
   ...

Invoke ApplicationMessageFolderRegistry.setRootFolderName() to specify the name of the root folder for your application's custom folders. The name of the root folder appears in the View Folder dialog box of the Messages application when an application registers more than one application message folder.

reg.setRootFolderName( "ML Sample" );

Send a notification when a custom folder changes

After your BlackBerry device application adds custom messages to the message list, you must manage the messages. For example, a BlackBerry device user might open the application and delete a message there, or the application might synchronize with a server and get more messages to display in the message list.

To keep the message list synchronized with the custom messages in a custom folder, an application needs to be notified when a custom folder changes.

Import the required classes and interfaces.

import net.rim.blackberry.api.messagelist.*;

Invoke ApplicationMessageFolder.fireElementAdded() to notify an application when a message is added to a custom folder.

inboxFolder.fireElementAdded( newMessage );

Invoke ApplicationMessageFolder.fireElementRemoved() to notify an application when a message is removed from a custom folder.

inboxFolder.fireElementRemoved( deletedMessage );

Invoke ApplicationMessageFolder.fireElementUpdated() to notify an application when a message in a custom folder is updated.

inboxFolder.fireElementUpdated( updatedMessage );

Invoke ApplicationMessageFolder.fireReset() to notify an application when more than one message in a custom folder changes.

inboxFolder.fireReset();

Create a custom indicator

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.

Import the required classes and interfaces.

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

Obtain a reference to an ApplicationIndicatorRegistry object.

ApplicationIndicatorRegistry reg = ApplicationIndicatorRegistry.getInstance();

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 );

Register the icon as an application indicator by invoking ApplicationIndicatorRegistry.register(). 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);

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

ApplicationIndicator appIndicator = reg.getApplicationIndicator();

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 );

Hide an indicator

Import the required classes and interfaces.

import net.rim.blackberry.api.messagelist.*;

To temporarily hide an indicator, invoke ApplicationIndicator.setVisible() and provide false as the argument.

appIndicator.setVisible( false );

Remove a custom indicator

You can remove a custom indicator from the Home screen by unregistering it.

Import the required classes and interfaces.

import net.rim.blackberry.api.messagelist.*;

Remove the custom indicator by invoking ApplicationIndicatorRegistry.unregister().

reg.unregister();