de.enough.polish.ui
Class Gauge

java.lang.Object
  de.enough.polish.ui.Item
      de.enough.polish.ui.Gauge

All Implemented Interfaces:

ImageConsumer

public class Gauge
extends Item
implements ImageConsumer

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

Author:

Robert Virkus, robert@enough.de

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 de.enough.polish.ui.Item

_bbField, _bbFieldAdded, appearanceMode, background, backgroundHeight, backgroundWidth, backgroundYOffset, border, borderWidth, BUTTON, colSpan, commands, completeBackground, completeBackgroundPadding, completeBorder, contentHeight, contentWidth, contentX, contentY, cssSelector, defaultCommand, focusedStyle, HORIZONTAL, HYPERLINK, includeLabel, INTERACTIVE, internalHeight, internalWidth, internalX, internalY, isFocused, isInitialized, isInvisible, isLayoutCenter, isLayoutExpand, isLayoutRight, isPressed, isShown, isStyleInitialised, itemCommandListener, itemHeight, itemWidth, label, labelStyle, layout, 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, marginBottom, marginLeft, marginRight, marginTop, maximumHeight, maximumWidth, minimumHeight, minimumWidth, NO_POSITION_SET, opacity, opacityPaintNormally, opacityRgbData, paddingBottom, paddingHorizontal, paddingLeft, paddingRight, paddingTop, paddingVertical, parent, PLAIN, preferredHeight, preferredWidth, preserveViewType, relativeX, relativeY, rowSpan, screen, style, TRANSPARENT, useSingleRow, VERTICAL, view

Constructor Summary

Gauge(java.lang.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.

Gauge(java.lang.String label, boolean interactive, int maxValue, int initialValue, Style style)
Creates a new Gauge object with the given label, in interactive or non-interactive mode, with the given maximum and initial values.

Method Summary

boolean	animate() Animates this item.
protected java.lang.String	createCssSelector() Retrieves the CSS selector for this item.
int	getMaxValue() Gets the maximum value of this Gauge object.
int	getValue() Gets the current value of this Gauge object.
protected boolean	handleKeyPressed(int keyCode, int gameAction) Handles the key-pressed event.
protected boolean	handlePointerPressed(int x, int y) Handles the event when a pointer has been pressed at the specified position.
protected void	hideNotify() Called by the system to notify the item that it is now completely invisible, when it previously had been at least partially visible.
protected void	initContent(int firstLineWidth, int lineWidth) Initialises this item.
boolean	isInteractive() Tells whether the user is allowed to change the value of the Gauge.
void	paintContent(int x, int y, int leftBorder, int rightBorder, javax.microedition.lcdui.Graphics g) Paints the content of this item.
void	setImage(java.lang.String name, javax.microedition.lcdui.Image image) sets the image which has been loaded in the background.
void	setMaxValue(int maxValue) Sets the maximum value of this Gauge object.
void	setStyle(Style style) Sets the style of this item.
void	setValue(int value) Sets the current value of this Gauge object.
protected void	showNotify() Called by the system to notify the item that it is now at least partially visible, when it previously had been completely invisible.

Methods inherited from class de.enough.polish.ui.Item

addCommand, addCommand, addCommands, addRelativeToBackgroundRegion, addRelativeToBackgroundRegion, addRelativeToContentRegion, animate, containsCommand, defocus, focus, getAbsoluteX, getAbsoluteY, getAppearanceMode, getAttribute, getAttributes, getBackgroundHeight, getBackgroundWidth, getBackgroundX, getBackgroundY, getContentHeight, getContentWidth, getContentX, getContentY, getDefaultCommand, getFocusedStyle, getItemAt, getItemCommandListener, getItemCommands, getItemHeight, getItemStateListener, getItemWidth, getLabel, getLabelItem, getLayout, getMinimumHeight, getMinimumWidth, getParent, getPreferredHeight, getPreferredWidth, getScreen, getStyle, handleCommand, handleKeyReleased, handleKeyRepeated, handlePointerReleased, init, initStyle, isInContentArea, isInItemArea, isInItemArea, isInitialized, isVisible, notifyItemPressedEnd, notifyItemPressedStart, notifyStateChanged, paint, paintBackground, paintBackgroundAndBorder, paintBorder, releaseResources, removeCommand, repaint, repaint, repaintFully, requestInit, setAppearanceMode, setAttribute, setDefaultCommand, setItemCommandListener, setItemCommandListener, setItemStateListener, setLabel, setLayout, setParent, setParent, setPreferredSize, setVisible, show, showCommands, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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(java.lang.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:

java.lang.IllegalArgumentException - if maxValue is not positive for interactive gauges or if maxValue is neither positive nor INDEFINITE for non-interactive gauges or 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

Gauge

public Gauge(java.lang.String label,
             boolean interactive,
             int maxValue,
             int initialValue,
             Style style)

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.

style - the CSS style for this item

Throws:

java.lang.IllegalArgumentException - if maxValue is not positive for interactive gauges or if maxValue is neither positive nor INDEFINITE for non-interactive gauges or 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

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:

java.lang.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:

INDEFINITE, CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, INCREMENTAL_UPDATING

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:

INDEFINITE, CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, INCREMENTAL_UPDATING

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:

java.lang.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

paintContent

public void paintContent(int x,
                         int y,
                         int leftBorder,
                         int rightBorder,
                         javax.microedition.lcdui.Graphics g)

Description copied from class: Item

Paints the content of this item. The background has already been painted and the border will be added after this method returns.

Specified by:

paintContent in class Item

Parameters:

x - the left start position

y - the upper start position

leftBorder - the left border, nothing must be painted left of this position

rightBorder - the right border, nothing must be painted right of this position

g - the Graphics on which this item should be painted.

initContent

protected void initContent(int firstLineWidth,
                           int lineWidth)

Description copied from class: Item

Initialises this item. The implementation needs to calculate and set the contentWidth and contentHeight fields. The implementation should take the fields preferredWidth and preferredHeight into account.

Specified by:

initContent in class Item

Parameters:

firstLineWidth - the maximum width of the first line

lineWidth - the maximum width of any following lines

See Also:

Item.contentWidth, Item.contentHeight, Item.preferredWidth, Item.preferredHeight

createCssSelector

protected java.lang.String createCssSelector()

Description copied from class: Item

Retrieves the CSS selector for this item. The CSS selector is used for the dynamic assignment of styles - that is the styles are assigned by the usage of the item and not by a predefined style-name. With the #style preprocessing command styles are set fix, this method yields in a faster GUI and is recommended. When in a style-sheet dynamic styles are used, e.g. "Form>p", than the selector of the item is needed.
This abstract method needs only be implemented, when dynamic styles are used: #ifdef polish.useDynamicStyles
The returned selector needs to be in lower case.

Specified by:

createCssSelector in class Item

Returns:

the appropriate CSS selector for this item. The selector needs to be in lower case.

setStyle

public void setStyle(Style style)

Description copied from class: Item

Sets the style of this item.

Overrides:

setStyle in class Item

Parameters:

style - the new style for this item.

setImage

public void setImage(java.lang.String name,
                     javax.microedition.lcdui.Image image)

Description copied from interface: ImageConsumer

sets the image which has been loaded in the background.

Specified by:

setImage in interface ImageConsumer

Parameters:

name - the name of the image. This allows the image-consumer to differentiate between several images.

image - the image which was loaded in the background thread.

handleKeyPressed

protected boolean handleKeyPressed(int keyCode,
                                   int gameAction)

Description copied from class: Item

Handles the key-pressed event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation just handles the FIRE game-action when a default-command and an item-command-listener have been registered.

Overrides:

handleKeyPressed in class Item

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

handlePointerPressed

protected boolean handlePointerPressed(int x,
                                       int y)

Description copied from class: Item

Handles the event when a pointer has been pressed at the specified position. The default method discards this event when relX/relY is outside of the item's area. When the event took place inside of the content area, the pointer-event is translated into an artificial FIRE game-action keyPressed event, which is subsequently handled bu the handleKeyPressed(-1, Canvas.FIRE) method. This method needs should be overwritten only when the "polish.hasPointerEvents" preprocessing symbol is defined: "//#ifdef polish.hasPointerEvents".

Overrides:

handlePointerPressed in class Item

Parameters:

x - the x position of the pointer pressing relative to this item's left position

y - the y position of the pointer pressing relative to this item's top position

Returns:

true when the pressing of the pointer was actually handled by this item.

See Also:

this method is used for determining whether the event belongs to this item, for a helper method for determining whether the event took place into the actual content area, Item.handleKeyPressed(int, int), for calculating the horizontal position relative to the content (relX - contentX), for calculating the vertical position relative to the content (relY - contentY)

animate

public boolean animate()

Description copied from class: Item

Animates this item. Subclasses can override this method to create animations. The default implementation returns false

Overrides:

animate in class Item

Returns:

true when this item has been animated.

See Also:

Item.animate(long, ClippingRegion)

hideNotify

protected void hideNotify()

Description copied from class: Item

Called by the system to notify the item that it is now completely invisible, when it previously had been at least partially visible. No further paint() calls will be made on this item until after a showNotify() has been called again.

The default implementation of this method sets the isShown field to false and calls hideNotify on style elements.

Overrides:

hideNotify in class Item

showNotify

protected void showNotify()

Description copied from class: Item

Called by the system to notify the item that it is now at least partially visible, when it previously had been completely invisible. The item may receive paint() calls after showNotify() has been called.

The default implementation of this method sets the isShown field to true and calls showNotify on style elements.

Overrides:

showNotify in class Item