Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | 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

Implements a graphical display, such as a bar graph, of an integer value. The `Gauge` contains a current value that lies between zero and the maximum value, inclusive. The application can control the current value and maximum value. 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. Non-interactive mode is used to provide feedback to the user on the state of a long-running operation. One expected use of the non-interactive mode is as a "progress indicator" or "activity indicator" to give the user some feedback during a long-running operation. The application may update the value periodically using the `setValue()` method.

A non-interactive `Gauge` can have a definite or indefinite range. If a `Gauge` has definite range, it will have an integer value between zero and the maximum value set by the application, inclusive. The implementation will provide a graphical representation of this value such as described above.

A non-interactive `Gauge` that has indefinite range will exist in one of four states: continuous-idle, incremental-idle, continuous-running, or incremental-updating. These states are intended to indicate to the user that some level of activity is occurring. With incremental-updating, progress can be indicated to the user even though there is no known endpoint to the activity. With continuous-running, there is no progress that gets reported to the user and there is no known endpoint; continuous-running is merely a busy state indicator. The implementation should use a graphical display that shows this appropriately. The implementation may use different graphics for indefinite continuous gauges and indefinite incremental gauges. Because of this, separate idle states exist for each mode. For example, the implementation might show an hourglass or spinning watch in the continuous-running state, but show an animation with different states, like a beach ball or candy-striped bar, in the incremental-updating state.

In the continuous-idle or incremental-idle state, the `Gauge` indicates that no activity is occurring. In the incremental-updating state, the `Gauge` indicates activity, but its graphical representation should be updated only when the application requests an update with a call to `setValue()`. In the continuous-running state, the `Gauge` indicates activity by showing an animation that runs continuously, without update requests from the application.

The values `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, and `INCREMENTAL_UPDATING` have their special meaning only when the `Gauge` is non-interactive and has been set to have indefinite range. They are treated as ordinary values if the `Gauge` is interactive or if it has been set to have a definite range.

An application using the `Gauge` as a progress indicator should typically also attach a `STOP` command to the container containing the `Gauge` to allow the user to halt the operation in progress.

### Notes for Application Developers

As mentioned above, a non-interactive `Gauge` may be used to give user feedback during a long-running operation. If the application can observe the progress of the operation as it proceeds to an endpoint known in advance, then the application should use a non-interactive `Gauge` with a definite range. For example, consider an application that is downloading a file known to be `20` kilobytes in size. The application could set the `Gauge's` maximum value to be `20` and set its value to the number of kilobytes downloaded so far. The user will be presented with a `Gauge` that shows the portion of the task completed at any given time.

If, on the other hand, the application is downloading a file of unknown size, it should use a non-interactive `Gauge` with indefinite range. Ideally, the application should call `setValue(INCREMENTAL_UPDATING)` periodically, perhaps each time its input buffer has filled. This will give the user an indication of the rate at which progress is occurring.

Finally, if the application is performing an operation but has no means of detecting progress, it should set a non-interactive `Gauge` to have indefinite range and set its value to `CONTINUOUS_RUNNING` or `CONTINUOUS_IDLE` as appropriate. For example, if the application has issued a request to a network server and is about to block waiting for the server to respond, it should set the `Gauge's` state to `CONTINUOUS_RUNNING` before awaiting the response, and it should set the state to `CONTINUOUS_IDLE` after it has received the response.

Since:
  MIDP 1.0

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
`void` | `addCommand(Command cmd)` Adds a context sensitive `Command` to the item.
`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` | `setDefaultCommand(Command cmd)` Sets default `Command` for this `Item`.
`void` | `setItemCommandListener(ItemCommandListener l)` Sets a listener for `Commands` to this Item, replacing any previous `ItemCommandListener`.
`void` | `setLabel(String label)` Sets the label of the `Item`.
`void` | `setLayout(int layout)` Sets the layout directives for this item.
`void` | `setMaxValue(int maxValue)` Sets the maximum value of this `Gauge` object.
`void` | `setPreferredSize(int width, int height)` Sets the preferred width and height for this `Item`.
`void` | `setValue(int value)` Sets the current value of this `Gauge` object.

Methods inherited from class javax.microedition.lcdui.Item
`getLabel, getLayout, getMinimumHeight, getMinimumWidth, getPreferredHeight, getPreferredWidth, notifyStateChanged, removeCommand`

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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

### 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
  See Also:
    Constant Field Values

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. In interactive mode (where `interactive` is `true`) the maximum value must be greater than zero, otherwise an exception is thrown. In non-interactive mode (where `interactive` is `false`) the maximum value must be greater than zero or equal to the special value `INDEFINITE`, otherwise an exception is thrown.

  If the maximum value is greater than zero, the gauge has definite range. In this case 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`.

  If `interactive` is `false` and the maximum value is `INDEFINITE`, this creates a non-interactive gauge with indefinite range. The initial value must be one of `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, or `INCREMENTAL_UPDATING`.

Parameters:
  `label` - the `Gauge's` label
  `interactive` - tells whether the user can change the value
  `maxValue` - the maximum value, or `INDEFINITE`
  `initialValue` - the initial value in the range `[0..maxValue]`, or one of `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, or `INCREMENTAL_UPDATING` if `maxValue` is `INDEFINITE`.
Throws:
  `IllegalArgumentException` - if `maxValue` is not positive for interactive gauges
  `IllegalArgumentException` - if `maxValue` is neither positive nor `INDEFINITE` for non-interactive gauges
  `IllegalArgumentException` - if initialValue is not one of `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, or `INCREMENTAL_UPDATING` for a non-interactive gauge with indefinite range
See Also:
  `INDEFINITE`, `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, `INCREMENTAL_UPDATING`

Method Detail

### setLabel

    public void setLabel(String label)

  Sets the label of the `Item`. If `label` is `null`, specifies that this item has no label.

  It is illegal to call this method if this `Item` is contained within an `Alert`.

  Overrides:
    `setLabel` in class `Item`
  Parameters:
    `label` - the label string
  Throws:
    `IllegalStateException` - if this `Item` is contained within an `Alert`
  See Also:
    `Item.getLabel()`

### setLayout

    public void setLayout(int layout)

  Sets the layout directives for this item.

  It is illegal to call this method if this `Item` is contained within an `Alert`.

  Overrides:
    `setLayout` in class `Item`
  Parameters:
    `layout` - a combination of layout directive values for this item
  Throws:
    `IllegalArgumentException` - if the value of layout is not a valid combination of layout directives
    `IllegalStateException` - if this `Item` is contained within an `Alert`
  Since:
    MIDP 2.0
  See Also:
    `Item.getLayout()`

### addCommand

    public void addCommand(Command cmd)

  Adds a context sensitive `Command` to the item. The semantic type of `Command` should be `ITEM`. The implementation will present the command only when the the item is active, for example, highlighted.

  If the added command is already in the item (tested by comparing the object references), the method has no effect. If the item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so.

  It is illegal to call this method if this `Item` is contained within an `Alert`.

  Overrides:
    `addCommand` in class `Item`
  Parameters:
    `cmd` - the command to be added
  Throws:
    `IllegalStateException` - if this `Item` is contained within an `Alert`
    `NullPointerException` - if cmd is `null`
  Since:
    MIDP 2.0

### setItemCommandListener

    public void setItemCommandListener(ItemCommandListener l)

  Sets a listener for `Commands` to this Item, replacing any previous `ItemCommandListener`. A `null` reference is allowed and has the effect of removing any existing listener.

  It is illegal to call this method if this `Item` is contained within an `Alert`.

  Overrides:
    `setItemCommandListener` in class `Item`
  Parameters:
    `l` - the new listener, or `null`.
  Throws:
    `IllegalStateException` - if this `Item` is contained within an `Alert`
  Since:
    MIDP 2.0

### setPreferredSize

    public void setPreferredSize(int width,
                                 int height)

  Sets the preferred width and height for this `Item`. Values for width and height less than `-1` are illegal. If the width is between zero and the minimum width, inclusive, the minimum width is used instead. If the height is between zero and the minimum height, inclusive, the minimum height is used instead.

  Supplying a width or height value greater than the minimum width or height locks that dimension to the supplied value. The implementation may silently enforce a maximum dimension for an `Item` based on factors such as the screen size. Supplying a value of `-1` for the width or height unlocks that dimension. See Item Sizes for a complete discussion.

  It is illegal to call this method if this `Item` is contained within an `Alert`.

  Overrides:
    `setPreferredSize` in class `Item`
  Parameters:
    `width` - the value to which the width should be locked, or `-1` to unlock
    `height` - the value to which the height should be locked, or `-1` to unlock
  Throws:
    `IllegalArgumentException` - if width or height is less than `-1`
    `IllegalStateException` - if this `Item` is contained within an `Alert`
  Since:
    MIDP 2.0
  See Also:
    `Item.getPreferredHeight()`, `Item.getPreferredWidth()`

### setDefaultCommand

    public void setDefaultCommand(Command cmd)

  Sets default `Command` for this `Item`. If the `Item` previously had a default `Command`, that `Command` is no longer the default, but it remains present on the `Item`.

  If not `null`, the `Command` object passed becomes the default `Command` for this `Item`. If the `Command` object passed is not currently present on this `Item`, it is added as if `addCommand(javax.microedition.lcdui.Command)` had been called before it is made the default `Command`.

  If `null` is passed, the `Item` is set to have no default `Command`. The previous default `Command`, if any, remains present on the `Item`.

  It is illegal to call this method if this `Item` is contained within an `Alert`.

  Overrides:
    `setDefaultCommand` in class `Item`
  Parameters:
    `cmd` - the command to be used as this `Item's` default `Command`, or `null` if there is to be no default command
  Throws:
    `IllegalStateException` - if this `Item` is contained within an `Alert`
  Since:
    MIDP 2.0

### setValue

    public void setValue(int value)

  Sets the current value of this `Gauge` object.

  If the gauge is interactive, or if it is non-interactive with definite range, the following rules apply. 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.

  If this `Gauge` object is a non-interactive gauge with indefinite range, then value must be one of `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, or `INCREMENTAL_UPDATING`. Other values will cause an exception to be thrown.

  Parameters:
    `value` - the new value
  Throws:
    `IllegalArgumentException` - if value is not one of `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, or `INCREMENTAL_UPDATING` for non-interactive gauges with indefinite range
  See Also:
    `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, `INCREMENTAL_UPDATING`, `getValue()`

### getValue

    public int getValue()

  Gets the current value of this `Gauge` object.

  If this `Gauge` object is a non-interactive gauge with indefinite range, the value returned will be one of `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, or `INCREMENTAL_UPDATING`. Otherwise, it will be an integer between zero and the gauge's maximum value, inclusive.

  Returns:
    current value of the `Gauge`
  See Also:
    `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, `INCREMENTAL_UPDATING`, `setValue(int)`

### setMaxValue

    public void setMaxValue(int maxValue)

  Sets the maximum value of this `Gauge` object.

  For interactive gauges, the new maximum value must be greater than zero, otherwise an exception is thrown. For non-interactive gauges, the new maximum value must be greater than zero or equal to the special value `INDEFINITE`, otherwise an exception is thrown.

  If the new maximum value is greater than zero, this provides the gauge with a definite range. If the gauge previously had a definite range, and if the current value is greater than new maximum value, the current value is set to be equal to the new maximum value. If the gauge previously had a definite range, and if the current value is less than or equal to the new maximum value, the current value is left unchanged.

  If the new maximum value is greater than zero, and if the gauge had previously had indefinite range, this new maximum value provides it with a definite range. Its graphical representation must change accordingly, the previous state of `CONTINUOUS_IDLE`, `INCREMENTAL_IDLE`, `CONTINUOUS_RUNNING`, or `INCREMENTAL_UPDATING` is ignored, and the current value is set to zero.

  If this gauge is non-interactive and the new maximum value is `INDEFINITE`, this gives the gauge indefinite range. If the gauge previously had a definite range, its graphical representation must change accordingly, the previous value is ignored, and the current state is set to `CONTINUOUS_IDLE`. If the gauge previously had an indefinite range, setting the maximum value to `INDEFINITE` will have no effect.

  Parameters:
    `maxValue` - the new maximum value
  Throws:
    `IllegalArgumentException` - if `maxValue` is invalid
  See Also:
    `INDEFINITE`, `getMaxValue()`

### getMaxValue

    public int getMaxValue()

  Gets the maximum value of this `Gauge` object.

  If this gauge is interactive, the maximum value will be a positive integer. If this gauge is non-interactive, the maximum value will be a positive integer (indicating that the gauge has definite range) or the special value `INDEFINITE` (indicating that the gauge has indefinite range).

  Returns:
    the maximum value of the `Gauge`, or `INDEFINITE`
  See Also:
    `INDEFINITE`, `setMaxValue(int)`

### 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: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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