javax.microedition.lcdui
Class Gauge

java.lang.Object
  |
  +--javax.microedition.lcdui.Item
        |
        +--javax.microedition.lcdui.Gauge

public class Gauge
extends Item

The Gauge class implements a bar graph display of a value intended for use in a form. Gauge is optionally interactive. The values accepted by the object are small integers in the range zero through a maximum value established by the application. The application is expected to normalize its values into this range. The device is expected to normalize this range into a smaller set of values for display purposes. Doing so will not change the actual value contained within the object. The range of values specified by the application may be larger than the number of distinct visual states possible on the device, so more than one value may have the same visual representation.

For example, consider a Gauge object that has a range of values from zero to 99, running on a device that displays the Gauge's approximate value using a set of one to ten bars. The device might show one bar for values zero through nine, two bars for values ten through 19, three bars for values 20 through 29, and so forth.

A Gauge may be interactive or non-interactive. Applications may set or retrieve the Gauge's value at any time regardless of the interaction mode. The implementation may change the visual appearance of the bar graph depending on whether the object is created in interactive mode.

In interactive mode, the user is allowed to modify the value. The user will always have the means to change the value up or down by one and may also have the means to change the value in greater increments. The user is prohibited from moving the value outside the established range. The expected behavior is that the application sets the initial value and then allows the user to modify the value thereafter. However, the application is not prohibited from modifying the value even while the user is interacting with it.

In many cases the only means for the user to modify the value will be to press a button to increase or decrease the value by one unit at a time. Therefore, applications should specify a range of no more than a few dozen values.

In non-interactive mode, the user is prohibited from modifying the value. An expected use of the non-interactive mode is as a "progress indicator" to give the user some feedback as progress occurs during a long-running operation. The application is expected to update the value periodically using the setValue() method. An application using the Gauge as a progress indicator should typically also attach a STOP command to the Form containing the Gauge to allow the user to halt the operation in progress.


Field Summary
static int CONTINUOUS_IDLE
          The value representing the continuous-idle state of a non-interactive Gauge with indefinite range.
static int CONTINUOUS_RUNNING
          The value representing the continuous-running state of a non-interactive Gauge with indefinite range.
static int INCREMENTAL_IDLE
          The value representing the incremental-idle state of a non-interactive Gauge with indefinite range.
static int INCREMENTAL_UPDATING
          The value representing the incremental-updating state of a non-interactive Gauge with indefinite range.
static int INDEFINITE
          A special value used for the maximum value in order to indicate that the Gauge has indefinite range.
 
Fields inherited from class javax.microedition.lcdui.Item
BUTTON, HYPERLINK, LAYOUT_2, LAYOUT_BOTTOM, LAYOUT_CENTER, LAYOUT_DEFAULT, LAYOUT_EXPAND, LAYOUT_LEFT, LAYOUT_NEWLINE_AFTER, LAYOUT_NEWLINE_BEFORE, LAYOUT_RIGHT, LAYOUT_SHRINK, LAYOUT_TOP, LAYOUT_VCENTER, LAYOUT_VEXPAND, LAYOUT_VSHRINK, PLAIN
 
Constructor Summary
Gauge(String label, boolean interactive, int maxValue, int initialValue)
          Creates a new Gauge object with the given label, in interactive or non-interactive mode, with the given maximum and initial values.
 
Method Summary
 String getLabel()
          Gets the label of this Item object.
 int getMaxValue()
          Gets the maximum value of this Gauge object.
 int getValue()
          Gets the current value of this Gauge object.
 boolean isInteractive()
          Tells whether the user is allowed to change the value of the Gauge.
 void setLabel(String label)
          Sets the label of the Item.
 void setMaxValue(int maxValue)
          Sets the maximum value of this Gauge object.
 void setValue(int value)
          Sets the current value of this Gauge object.
 
Methods inherited from class javax.microedition.lcdui.Item
addCommand, getLayout, getMinimumHeight, getMinimumWidth, getPreferredHeight, getPreferredWidth, notifyStateChanged, removeCommand, setDefaultCommand, setItemCommandListener, setLayout, setPreferredSize
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INDEFINITE

public static final int INDEFINITE
A special value used for the maximum value in order to indicate that the Gauge has indefinite range. This value may be used as the maxValue parameter to the constructor, the parameter passed to setMaxValue(), and as the return value of getMaxValue().

The value of INDEFINITE is -1.

Since:
MIDP 2.0

CONTINUOUS_IDLE

public static final int CONTINUOUS_IDLE
The value representing the continuous-idle state of a non-interactive Gauge with indefinite range. In the continuous-idle state, the gauge shows a graphic indicating that no work is in progress.

This value has special meaning only for non-interactive gauges with indefinite range. It is treated as an ordinary value for interactive gauges and for non-interactive gauges with definite range.

The value of CONTINUOUS_IDLE is 0.

Since:
MIDP 2.0

INCREMENTAL_IDLE

public static final int INCREMENTAL_IDLE
The value representing the incremental-idle state of a non-interactive Gauge with indefinite range. In the incremental-idle state, the gauge shows a graphic indicating that no work is in progress.

This value has special meaning only for non-interactive gauges with indefinite range. It is treated as an ordinary value for interactive gauges and for non-interactive gauges with definite range.

The value of INCREMENTAL_IDLE is 1.

Since:
MIDP 2.0

CONTINUOUS_RUNNING

public static final int CONTINUOUS_RUNNING
The value representing the continuous-running state of a non-interactive Gauge with indefinite range. In the continuous-running state, the gauge shows a continually-updating animation sequence that indicates that work is in progress. Once the application sets a gauge into the continuous-running state, the animation should proceed without further requests from the application.

This value has special meaning only for non-interactive gauges with indefinite range. It is treated as an ordinary value for interactive gauges and for non-interactive gauges with definite range.

The value of CONTINUOUS_RUNNING is 2.

Since:
MIDP 2.0

INCREMENTAL_UPDATING

public static final int INCREMENTAL_UPDATING
The value representing the incremental-updating state of a non-interactive Gauge with indefinite range. In the incremental-updating state, the gauge shows a graphic indicating that work is in progress, typically one frame of an animation sequence. The graphic should be updated to the next frame in the sequence only when the application calls setValue(INCREMENTAL_UPDATING).

This value has special meaning only for non-interactive gauges with indefinite range. It is treated as an ordinary value for interactive gauges and for non-interactive gauges with definite range.

The value of INCREMENTAL_UPDATING is 3.

Since:
MIDP 2.0
Constructor Detail

Gauge

public Gauge(String label,
             boolean interactive,
             int maxValue,
             int initialValue)

Creates a new Gauge object with the given label, in interactive or non-interactive mode, with the given maximum and initial values. The maximum value must be greater than zero, otherwise an exception is thrown. The initial value must be within the range zero to maxValue, inclusive. If the initial value is less than zero, the value is set to zero. If the initial value is greater than maxValue, it is set to maxValue.

Parameters:
label - the Gauge's label
interactive - tells whether the user can change the value
maxValue - the maximum value
initialValue - the initial value in the range [0..maxValue]
Throws:
IllegalArgumentException - if maxValue is invalid
Method Detail

setValue

public void setValue(int value)

Sets the current value of this Gauge object. If the value is less than zero, zero is used. If the current value is greater than the maximum value, the current value is set to be equal to the maximum value.

Parameters:
value - the new value
Since:
JDE 4.0.2

getValue

public int getValue()

Gets the current value of this Gauge object.

Returns:
current value of the Gauge

setMaxValue

public void setMaxValue(int maxValue)

Sets the maximum value of this Gauge object. The new maximum value must be greater than zero, otherwise an exception is thrown. If the current value is greater than new maximum value, the current value is set to be equal to the new maximum value.

Parameters:
maxValue - the new maximum value
Throws:
IllegalArgumentException - if maxValue is invalid
Since:
JDE 4.0.2

getMaxValue

public int getMaxValue()

Gets the maximum value of this Gauge object.

Returns:
the maximum value of the Gauge

isInteractive

public boolean isInteractive()

Tells whether the user is allowed to change the value of the Gauge.

Returns:
a boolean indicating whether the Gauge is interactive

setLabel

public void setLabel(String label)
Description copied from class: Item
Sets the label of the Item. If label is null, specifies that this item has no label.
Overrides:
setLabel in class Item
Since:
JDE 4.0.2

getLabel

public String getLabel()
Description copied from class: Item
Gets the label of this Item object.
Overrides:
getLabel in class Item
Following copied from class: javax.microedition.lcdui.Item
Returns:
the label string


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.