Using the BlackBerry gauge field to display progress – Tutorial

Posted by

Introduction

This tutorial will show you how the use the gauge field to show progress in your apps. This is useful when your app is performing long running tasks that need to report feedback to the user. The gauge field is a horizontal component that can be used to display status or progress. It displays a percentage from 0 to 100 and you can set a label before it to display any progress/status messages. You can even overlay the label inside of the gauge field, so that it won’t be displayed before it, but inside of it (on top of the progress bar that’s drawn).

Additionally, you can use this field for input, rather than just display. Press Alt+trackwheel roll to actually set the percentage progress on the component. This is not going to be covered in this tutorial.

Source code example

In the following example, I’m going to create 4 different gauge fields, with different styles, and I’m going to start a timer task that simply updates the value on all 4 of them and takes them from 0 to 100. The timer is cancelled when the value is set to 100. If you close the screen by pressing ESC/BACK, this will cancel the timer as well. This example serves to show you the different styles that can be applied to this gauge field to report status.

/**
 * TimerDemo
 *
 * @author Nazmul Idris
 * @version 1.0
 * @since Nov 14, 2009, 1:41:26 PM
 */
public class TimerDemo extends UiApplication {

// main method
public static void main(String[] args) {

  TimerDemo theApp = new TimerDemo();
  theApp.enterEventDispatcher();

}

// data
private int statusValue = 0;
private Timer timer = new Timer();
private Vector fields = new Vector();

// constructor
public TimerDemo() {

  final ButtonField btnQuit = new ButtonField("Quit and pop screen");

  final MyScreen screen = new MyScreen(btnQuit);

  btnQuit.setChangeListener(new FieldChangeListener() {
    public void fieldChanged(Field field, int i) {
      screen.close();
    }
  });

  UiApplication.getUiApplication().pushScreen(screen);

}

// MyScreen
class MyScreen extends MainScreen {
  public void close() {
    try {
      timer.cancel();
    }
    catch (Exception e) {}
    super.close();
  }

  public boolean isDirty() {
    return false;
  }

  public MyScreen(ButtonField btnQuit) {
    // get the MainScreen's VerticalFieldManager...
    Manager vfm = this.getMainManager();

    //default gauge
    final GaugeField gf1;
    {
      gf1 = new GaugeField();
      gf1.setLabel("default gauge:");
      gf1.setValue(12);
      fields.addElement(gf1);
    }

    // custom gauge
    final GaugeField gf2;
    {
      gf2 = new GaugeField("custom gauge:",
                           0, 100, 0,
                           GaugeField.NO_TEXT | GaugeField.PERCENT | GaugeField.LABEL_AS_PROGRESS);
      fields.addElement(gf2);
    }

    // custom gauge #2
    final GaugeField gf3;
    {
      gf3 = new GaugeField("custom gauge:",
                           0, 100, 0,
                           GaugeField.PERCENT | GaugeField.LABEL_AS_PROGRESS);
      fields.addElement(gf3);
    }

    // custom gauge #3
    final GaugeField gf4;
    {
      gf4 = new GaugeField("custom gauge:",
                           0, 100, 0,
                           GaugeField.LABEL_AS_PROGRESS);
      fields.addElement(gf4);
    }

    // add all the fields to the vfm...
    {
      // add all the guagefields
      for (int i = 0; i < fields.size(); i++) {
        Object field = fields.elementAt(i);
        vfm.add((Field) field);
      }

      // add a separator
      vfm.add(new SeparatorField(SeparatorField.LINE_HORIZONTAL));
    }

    // add the quit button to the vfm...
    vfm.add(btnQuit);

    System.out.println(":: TimerDemo adding components to the MainScreen...");

    timer.schedule(
        new TimerTask() {
          public void run() {
            if (statusValue == 100) {
              try {
                cancel();
                timer.cancel();
              }
              catch (Exception e) {}

              System.out.println(
                  ":: TimerDemo shutting down timer (and subsequent timer tasks)... statusValue > 100");
            }
            else {
              statusValue++;
              for (int i = 0; i < fields.size(); i++) {
                Object field = fields.elementAt(i);
                ((GaugeField) field).setValue(statusValue);
              }
              System.out.println(
                  ":: TimerDemo firing a status value update... statusValue=" + statusValue);
            }
          }
        },
        10,
        10);
    System.out.println(":: TimerDemo starting timer task...");

  }
}// end MainScreen

}//end class TimerDemo

This is what’s happening in the code:

  1. The GaugeApp has a main method that simply creates the MyScreen class and enters the EDT.
  2. Four different gauge fields are created and added to the MyScreen object, in addition to a button field, which simply causes the app to quit by calling close() on MyScreen, which cancels the timer and pops the screen. The VerticalFieldManager is extracted from the MainScreen using getMainManager(), which just allows the buttons and gauge fields to be added.
  3. The TimerTask is then started which simply updates the value of all the gauge fields.

Feedback and comments

If you have any comments on this tutorial, you would like to share, click here.