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.

Training Services

Want to learn from the best in the business? We have training programs available for BlackBerry development, Android development, rich desktop apps, and UX design. We can give your development team a competitive edge, and make them experts in these technologies. Contact us if you are interesting in learning more about our training services & schedule.

Consulting Services

If you need help building web, mobile, and desktop apps that are all connected to the cloud, we can help. We can empower your business by bringing your ideas to life.

Our expertise: architecture, UX design, graphic design, and implementation services for BlackBerry, Android, GWT, desktop Java, and cloud computing.

Our specialties: crafting stunning UXes, LBS, real-time collaboration and syncing between services and web/mobile/desktop apps, location based mobile e-commerce, and location based mobile advertising.

Contact us if you have a project you need our help with and we will consider taking you on as a client.

ONE Platform Licensing

If you are not interested in our consulting or training services, but would like to build web, mobile, and desktop apps that are all connected to the cloud quickly, you can kick-start your development by leveraging the ONE Platform. You won’t have to build and test from scratch!

The ONE Platform SDK will accelerate the development and deployment of your connected/service-enabled web/mobile/desktop projects. Contact us for more information on licensing the ONE Platform.

This entry was posted on Friday, October 9th, 2009 at 1:42 pm and is filed under BlackBerry. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.