File	Doc	Category	Size	Date	Package
Gauge.java	API Doc	phoneME MR2 API (J2ME)	30831	Wed May 02 18:00:22 BST 2007	javax.microedition.lcdui

Gauge

• java.lang.Object
  • Item

Fields Summary
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.
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.
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.
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.
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.
GaugeLF	gaugeLF The look&feel associated with this item. Set in the constructor.
int	value The current value of this gauge
int	maxValue The maximum possible value of this gauge
boolean	interactive Whether this gauge is interactive or not

Constructors Summary

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. see #INDEFINITE see #CONTINUOUS_IDLE see #INCREMENTAL_IDLE see #CONTINUOUS_RUNNING see #INCREMENTAL_UPDATING param label the Gauge's label param interactive tells whether the user can change the value param maxValue the maximum value, or INDEFINITE param 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 throws IllegalArgumentException if maxValue is neither positive nor INDEFINITE for non-interactive gauges throws IllegalArgumentException if initialValue is not one of CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, or INCREMENTAL_UPDATING for a non-interactive gauge with indefinite range super(label); if (maxValue == INDEFINITE && (initialValue < CONTINUOUS_IDLE || initialValue > INCREMENTAL_UPDATING)) { throw new IllegalArgumentException(); } synchronized (Display.LCDUILock) { this.interactive = interactive; itemLF = gaugeLF = LFFactory.getFactory().getGaugeLF(this); /** * IllegalArgumentException may be thrown by * setMaxValueImpl and setValue */ setMaxValueImpl(maxValue); setValueImpl(initialValue); }

Methods Summary
boolean	acceptFocus() Return whether the Item takes user input focus. return return true if contents is interactive or have abstract commands. return super.acceptFocus() || interactive;
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. param cmd the command to be added throws IllegalStateException if this Item is contained within an Alert throws NullPointerException if cmd is null if (this.owner instanceof Alert) { throw new IllegalStateException("Gauge contained within an Alert"); } super.addCommand(cmd);
private void	checkValue() Utility method to ensure the value of the Gauge is always in a range of 0 to maxValue, or if maxValue is INDEFINITE that value is CONTINUOUS_IDLE, INCREMENTAL_IDLE, INCREMENTAL_UPDATING, or CONTINUOUS_RUNNING. In the case where maxValue is INDEFINITE and value is not one of the three defined here it will be set to CONTINUOUS_IDLE. (0) private instance variable value will be within parameter after this call if (maxValue == INDEFINITE) { if (value < CONTINUOUS_IDLE || value > INCREMENTAL_UPDATING) { value = CONTINUOUS_IDLE; } } else { if (value < 0) { value = 0; } else if (value > maxValue) { value = maxValue; } }
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). see #INDEFINITE return the maximum value of the Gauge, or INDEFINITE see #setMaxValue // SYNC NOTE: return of atomic value, no locking necessary return maxValue;
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. see #CONTINUOUS_IDLE see #INCREMENTAL_IDLE see #CONTINUOUS_RUNNING see #INCREMENTAL_UPDATING return current value of the Gauge see #setValue synchronized (Display.LCDUILock) { return gaugeLF.lGetValue(); }
public boolean	isInteractive() Tells whether the user is allowed to change the value of the Gauge. return a boolean indicating whether the Gauge is interactive // SYNC NOTE: return of atomic value, no locking necessary return interactive;
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 {@link #addCommand} 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. param 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 if (this.owner instanceof Alert) { throw new IllegalStateException("Gauge contained within an Alert"); } super.setDefaultCommand(cmd);
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. param l the new listener, or null. throws IllegalStateException if this Item is contained within an Alert if (this.owner instanceof Alert) { throw new IllegalStateException("Gauge contained within an Alert"); } super.setItemCommandListener(l);
public void	setLabel(java.lang.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. param label the label string throws IllegalStateException if this Item is contained within an Alert see #getLabel if (this.owner instanceof Alert) { throw new IllegalStateException("Gauge contained within an Alert"); } super.setLabel(label);
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. param 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 throws IllegalStateException if this Item is contained within an Alert see #getLayout if (this.owner instanceof Alert) { throw new IllegalStateException("Gauge contained within an Alert"); } super.setLayout(layout);
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. see #INDEFINITE param maxValue the new maximum value throws IllegalArgumentException if maxValue is invalid see #getMaxValue synchronized (Display.LCDUILock) { setMaxValueImpl(maxValue); }
private void	setMaxValueImpl(int maxValue) Set the max value of this Gauge. param maxValue The maximum value to set for this Gauge throws IllegalArgumentException if maxValue is not positive for interactive gauges throws IllegalArgumentException if maxValue is neither positive nor INDEFINITE for non-interactive gauges if (maxValue <= 0) { if (!(interactive == false && maxValue == INDEFINITE)) { throw new IllegalArgumentException(); } } int oldMaxValue = this.maxValue; this.maxValue = maxValue; if (oldMaxValue == INDEFINITE) { // oldMaxValue if (maxValue > INDEFINITE) { value = 0; } } else if (maxValue == INDEFINITE) { value = CONTINUOUS_IDLE; } checkValue(); if (oldMaxValue != maxValue) { gaugeLF.lSetMaxValue(oldMaxValue, maxValue); }
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. param width the value to which the width should be locked, or -1 to unlock param height the value to which the height should be locked, or -1 to unlock throws IllegalArgumentException if width or height is less than -1 throws IllegalStateException if this Item is contained within an Alert see #getPreferredHeight see #getPreferredWidth if (this.owner instanceof Alert) { throw new IllegalStateException("Gauge contained within an Alert"); } super.setPreferredSize(width, height);
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. see #CONTINUOUS_IDLE see #INCREMENTAL_IDLE see #CONTINUOUS_RUNNING see #INCREMENTAL_UPDATING param 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 #getValue synchronized (Display.LCDUILock) { setValueImpl(value); }
void	setValueImpl(int value) Sets the current value of this Gauge object. param 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 if (!interactive && maxValue == INDEFINITE) { switch (value) { case CONTINUOUS_IDLE: case INCREMENTAL_IDLE: case INCREMENTAL_UPDATING: case CONTINUOUS_RUNNING: break; default: throw new IllegalArgumentException(); } } if ((this.value != value) || (this.maxValue == INDEFINITE && value == INCREMENTAL_UPDATING)) { int oldValue = this.value; this.value = value; checkValue(); gaugeLF.lSetValue(oldValue, this.value); }