Indicate progress

Help Center

Search This Document

Download PDF

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.

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.*;

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.

Create a ProgressIndicatorController object.

ProgressIndicatorController controller = new ProgressIndicatorController();

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.

Connect the controller, model, and view.

model.setController(controller);
view.setModel(model);
view.setController(controller);        
controller.setModel(model);
controller.setView(view);

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

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

Associate the listener with the model.

model.addListener(new DemoProgressIndicatorListener());

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");
```
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);
```
In this example, the progress bar uses the default text style and is displayed centered in the view's manager.
Add the view to your screen.
```
add(view);
```

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.

Code sample

public class ProgressIndicatorScreen extends MainScreen
{    
    ProgressIndicatorView view = new ProgressIndicatorView(0);
    ProgressIndicatorModel model = new ProgressIndicatorModel(0, 100, 0);
    ProgressIndicatorController controller = new ProgressIndicatorController();        

    ProgressThread _progressThread;

    public ProgressIndicatorScreen()
    {        
        setTitle("Progress Indicator Screen");         
        
        model.setController(controller);
        model.addListener(new DemoProgressIndicatorListener());        
        view.setModel(model);
        view.setController(controller);        
        controller.setModel(model);
        controller.setView(view);
        
        view.setLabel("Percent completion");
        view.createProgressBar(Field.FIELD_HCENTER);       
        
        add(view);        
    
        MenuItem _startIndicator = new MenuItem("Start indicator", 66000, 0)
        {
            public void run()
            {
              if(_progressThread != null)
              {
                  _progressThread.stopThread();                             
              }
              _progressThread = new ProgressThread();
              _progressThread.start();
            }
        };
        
        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();
            }
        }; 

        addMenuItem(_startIndicator);
        addMenuItem(_pauseIndicator);
        addMenuItem(_resumeIndicator);   
    } 
    
    class ProgressThread extends Thread
    {
        private boolean _paused;
        private boolean _stop;        
        
        public void run()
        {
            // Run dummy operations to simulate the processing of 
            // a collection of data.
            for(int i = 0; i <= 100; ++i)
            {           
                synchronized(this)
                {
                    if(_stop)
                    {
                        break;
                    }
                    if(_paused)
                    {
                        try
                        {                           
                            wait();                            
                        }
                        catch(InterruptedException ie)
                        {                        
                        }
                    }                    
                }
                ProgressIndicatorScreen.this.model.setValue(i);
                try
                {
                    // Simulate work
                    sleep(250);
                }
                catch(InterruptedException ie)
                {                    
                }                
            }           
        }
        
        public synchronized void setPaused(boolean paused)
        {              
            _paused = paused;
            this.notify();       
        }             
                
        public synchronized void stopThread()
        {
            _stop = true;
            if(_paused)
            {
                // If the thread is in a paused state, wake it up
                this.notify();                                        
            }
        }      
    }   
    
    private final class DemoProgressIndicatorListener implements
    ProgressIndicatorListener
    {
        public void cancelled()
        {
            _progressThread.setPaused(true);
        }
    
        public void resumed()
        {        
            _progressThread.setPaused(false);
        }
    
        public void reset()
        {
            // Not implemented
        }
        
        public void setNonProgrammaticValue(int value)
        {
            // Not implemented        
        }      

        public void configurationChanged(Adjustment source)
        {
            // Not implemented
        }
          
        public void valueChanged(Adjustment source) 
        {
            // Not implemented
        }        
    } 
}

The Progress Indicator Demo sample application that is included in the BlackBerry® Java® SDK creates and manipulates a progress bar.

Next topic: Pickers

Previous topic: Indicate activity

Was this information helpful? Send us your comments.

Global Navigation

Help Center

Local Navigation

Indicate progress

Code sample