Programming Wireless Devices with the Java2 Platform

10.7 Gauge

The Gauge class implements a graphical value display that may be placed in a Form. A Gauge displays a visual representation of a numeric value in the range between zero and the maximum value defined by the programmer. If the Gauge is set to be interactive, user actions can increase and decrease the value. Changes to the Gauge value are reported using an ItemStateListener. If the Gauge is set to be non-interactive, it represents a progress bar that can be used to provide feedback about the progress of long-running operations. The application can set and get the value of Gauge with the setValue(int) and getValue() methods. When Gauge is in non-interactive progress bar mode, the application must periodically update the value using the setValue method during the operation: the Gauge value should reach the maximum value just before the operation is finished.

Also available for a non-interactive Gauge is an indefinite range setting. This is used if there is no known endpoint to the activity. To define an indefinite Gauge, set the maximum value to the special INDEFINITE value. There are two kinds of indefinite Gauges available: CONTINUOUS_RUNNING and INCREMENTAL_UPDATING. These constants are used as Gauge range values. Continuous mode automatically animates the progress animation, whereas incremental mode requires that application call setValue(Gauge.INCREMENTAL_UPDATING) whenever there is an update in progress state.

For both of these modes there are separate idle modes that can be set with range values CONTINUOUS_IDLE and INCREMENTAL_IDLE, which indicate that no work is in progress. An application should use the idle modes with the correct pairs because the device progress graphics are typically designed so that, for example, CONTINUOUS_IDLE works well only in CONTINUOUS_RUNNING mode.

An example using interactive Gauge is:

Gauge gauge =
    new Gauge("Speed:", true, 10, 5);
form.append(gauge);

A non-interactive Gauge can also be placed in an Alert as an activity indicator. See Section 9.3.2, "Activity Indicator," for details.