Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

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
`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` | `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
`getLabel, setLabel`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

### 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

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 0.95 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.