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.

Activity indicators and progress indicators

Activity indicators and progress indicators show users that their BlackBerry devices are performing an action, such as searching for items or removing languages.

Use an activity indicator if you want to show that the BlackBerry device is working and you cannot determine the duration of the action. You can add an activity indicator to any component, such as a screen, text field, or list item. You can also add text to an activity indicator to describe the action.

Figure 1. An activity indicator in a field
This screen shows an example of an activity indicator in a field.

Figure 2. An activity indicator with text
This screen shows an example of an activity indicator with text.

Use a progress indicator if you can determine the duration of an action. Progress indicators include a label to indicate what the action is and a horizontal bar that fills from left to right as the action progresses. A percentage appears in the bar to indicate how much of the action is complete.


This screen shows an example of a progress indicator.

Best practice: Implementing activity indicators and progress indicators

  • Always indicate progress when an action takes more than 2 seconds to complete.
  • Use a progress indicator when you can determine the duration of an action.
  • Use an activity indicator when you cannot determine the duration of an action.
  • Use the ActivityIndicatorView class to create activity indicators. Use the ProgressIndicatorView class to create progress indicators.
  • Provide useful progress information. For example, if users are downloading an application to their device, indicate the percentage of data that their BlackBerry device has downloaded. Be as accurate as possible with the progress information.
  • Always allow users to use the End key to hide a progress indicator.

Guidelines for text

  • Use a concise, descriptive text (for example, "Loading data..." or "Building an application list...").
  • If an action is long and you want to communicate what is happening at each stage, provide text that describes each stage (for example, "Downloading..." or "Installing...").
  • Use sentence case capitalization.
  • Punctuate the text with an ellipsis (...).

Indicating activity or task progress

You can use the Activity and Progress Indicator API that is provided in the net.rim.device.api.ui.component.progressindicator package to display visual cues on a screen to indicate that work is being done or that a task is proceeding. You can represent an activity whose duration is unknown, as well as progress that can be represented numerically (for example, as a percentage of a completed task).

The Activity and Progress Indicator API uses the Model-View-Controller design pattern and includes two fields that are responsible for rendering the activity or progress:

  • The ActivityImageField class represents activity by using a bitmap that contains frames of an animation. The displayed frame changes over time. Typically, this field is a spinner, an hourglass, or other similar animated visual cue. This field is built and set by using the ActivityIndicatorView class.

  • The ProgressBarField class represents the progress of a task as a bar that fills as the task completes. This field is built and set by using the ProgressIndicatorView class.

The Progress Indicator Demo sample application is included in the BlackBerry Java SDK. This sample application demonstrates how to create and manipulate a variety of activity indicators and a progress indicator bar.

Indicate activity

You can display a field in your BlackBerry device application that indicates that work is proceeding. Typically, the field is a spinner, an hour glass, or other similar animated visual cue. The field is implemented by using the ActivityImageField class.
  1. Import the required classes and interfaces.

    import net.rim.device.api.system.Bitmap;
    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.component.progressindicator.*;
    import net.rim.device.api.ui.container.*;
  2. Create an image that contains frames of an animation and include it in your project. The image must consist of a series of frames of the animation arranged horizontally. The width of the image must be the width of a frame multiplied by the number of frames.

    For example, the following image has five frames of equal size.

    A sprite containing five frames of equal size.

  3. Create a bitmap from the image.

    Bitmap bitmap = Bitmap.getBitmapResource("spinner.png");
  4. Create an ActivityIndicatorView object. You can specify a style for the view in the constructor.

    ActivityIndicatorView view = new ActivityIndicatorView(Field.USE_ALL_WIDTH);

    To specify a manager to use for layout and focus, provide a second argument when you create the ActivityIndicatorView. If you do not specify a manager, a VerticalFieldManager object is used.

  5. Create a model and a controller.

    ActivityIndicatorModel model = new ActivityIndicatorModel();
    ActivityIndicatorController controller = new ActivityIndicatorController();
  6. Connect the view, model, and controller.

    view.setController(controller);
    view.setModel(model);
    
    controller.setModel(model);
    controller.setView(view);
    
    model.setController(controller);
  7. Create the field that renders the activity from the bitmap.

    view.createActivityImageField(bitmap, 5, Field.FIELD_HCENTER);

    In this example, the bitmap consists of five frames and is displayed centered in the view's manager.

  8. Add the view to your screen.

    add(view);
  9. Control the activity indication by controlling the view's model, as needed.

    MenuItem _stopIndicator = new MenuItem("Stop spinner", 66000, 0)
    {
        public void run()
        {
            view.getModel().cancel();
        }
    };
        
    MenuItem _resumeIndicator = new MenuItem("Resume spinner", 66010, 0)
    {
        public void run()
        {
            view.getModel().resume();
        }
    }; 

    This example invokes the model's cancel() method to stop the animation. The example invokes the model's resume() method to resume the animation.

Indicate progress

You can display a field in your BlackBerry device application that indicates that a task is proceeding. Progress is represented by a bar that fills as the task completes.

  1. Import the required classes and interfaces.

    import net.rim.device.api.ui.*;
    import net.rim.device.api.ui.container.*;
    import net.rim.device.api.ui.component.progressindicator.*;
  2. Create a ProgressIndicatorView object. You can specify a style for the view in the constructor. In the following example, no style is specified.

    ProgressIndicatorView view = new ProgressIndicatorView(0);

    To specify a manager to use for layout and focus, provide a second argument when you create the ProgressIndicatorView. If you do not specify a manager, a VerticalFieldManager object is used.

  3. Create a ProgressIndicatorController object.

    ProgressIndicatorController controller = 
                  new ProgressIndicatorController();
  4. Create a ProgressIndicatorModel object. This object represents the progress of the task. When you create the object, you can specify the model's initial value, its maximum value, and its minimum value. ProgressIndicatorModel uses an Adjustment object to allow for threaded access to the data model and to allow the task to be represented by integer values.

    ProgressIndicatorModel model = 
                  new ProgressIndicatorModel(0, 100, 0);

    In this example, the task starts with the value 0 and can reach 100. These values model the completion of a task as a percentage.

  5. Connect the controller, model, and view.

    model.setController(controller);
    view.setModel(model);
    view.setController(controller);        
    controller.setModel(model);
    controller.setView(view);   
  6. Create a thread to process the task. Typically, tasks that require progress indicators are performed by using a thread. As the task proceeds, update the value of the model to reflect the task's progress.

    class ProgressThread extends Thread
    {
        private boolean _paused;
        private boolean _stop;        
    
        public void run()
        {
            //Perform the task here and update the model's value as appropriate.
        }
    
        public synchronized void setPaused(boolean paused)
        {              
            //Pause the indicator here.
        }             
                    
        public synchronized void stopThread()
        {
            //Stop the indicator here.
        }    
    }
  7. Create a class that Implements the ProgressIndicatorListener interface to be notified of changes to the data model. You can be notified when the model is reset, resumed, or cancelled, or when the the value of the model is changed by non-programmatic means.

    private final class DemoProgressIndicatorListener implements ProgressIndicatorListener
    {
        public void cancelled()
        {
            _progressThread.setPaused(true);
        }
        
        public void resumed()
        {        
            _progressThread.setPaused(false);
        }
    ... 
    } 
  8. Associate the listener with the model.
    model.addListener(new DemoProgressIndicatorListener());
  9. Set the label for the view. The label displays above the rendered ProgressIndicatorField (assuming that the manager is a VerticalFieldManager, which is the default manager).
    view.setLabel("Percent completion");
  10. Create the field that renders the progress. You can provide styles that are defined in ProgressBarField to specify whether text is displayed on the bar and how it is displayed. By default, the model's value is displayed in the center of the space occupied by the bar.
    view.createProgressBar(Field.FIELD_HCENTER);
  11. Add the view to your screen.

    add(view);
  12. Control the progress indication by controlling the view's model, as needed.

    MenuItem _pauseIndicator = new MenuItem("Pause indicator", 66010, 0)
    {
        public void run()
        {
            view.getModel().cancel();
        }
    };
    
    MenuItem _resumeIndicator = new MenuItem("Resume indicator", 66020, 0)
    {
        public void run()
        {
            view.getModel().resume();
        }
    }; 

This example invokes the model's cancel() method to stop the progress indication. The example invokes the model's resume() method to resume progress indication.