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.

We do not just build mobile “apps”, we build mobile experiences

Let us build you mobile experiences for Android, BlackBerry, and iPhone. We can also build you cloud-connected experiences that span Mobile (Android, BlackBerry, iPhone), Web (Safari, Firefox, Internet Explorer) and Desktop (PC, Mac, Linux) for a truly connected real-time experience. See our work in action: download RainOrShine for BlackBerry and CityRyde for Android.

• We provide full service, full lifecycle consulting services (planning, graphic design, architecture, marketing, support, and implementation).
• We provide Architecture guidance before implementation; marketing strategy after implementation. Click here to learn more.

Zen Application Framework

All our applications are built using our Zen Application Framework, which helps you avoid the common pitfalls around mobile development. Zen drastically reduces development time & cost for mobile, web, and desktop experiences. Click here to learn more.

Our training services make You self-sufficient & sustainable

Want to learn from the best? We offer Android and BlackBerry developer training programs. Whether you are just starting out, or want advanced training, we have courses for different skill levels & technology requirements. Contact us to learn more, and sign up.

Our values: Open-source. Democratization of knowledge. To lead, never follow

We are leaders in mobile technology. We have done and seen it all. We do not follow trends set by others & we do not make the mistakes made by others. We set the trends for mobile because we are mobile visionaries.

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.