net.rim.device.api.ui.component
Class GaugeField

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.component.GaugeField

public class GaugeField
extends Field

Displays a horizontal bar that you can use for numeric selection or as a progress indicator.

Behaviour
Displays a label followed by a gauge bar. The gauge optionally has text overlayed over it indicating the percentage the gauge represents.

If this field is built as Field.EDITABLE, the user can employ the trackwheel to change the value by ALT-rolling. If Ui.getIncreaseDirection() returns -1, then rolling the trackwheel down decreases the value. If Ui.getIncreaseDirection() returns +1, then rolling the trackwheel up increases the * value.

If the UI is not operating in MODE_ADVANCED mode, this field adds a context menu item usable for changing its value. When invoked, a dialog appears in which one can use the trackwheel to select the item without ALT-rolling. Pressing ENTER or clicking dismisses the dialog, changing this field's value. Pressing ESCAPE dismisses the dialog, cancelling the change.

Field Summary
static long	LABEL_AS_PROGRESS Display the label as the progress value.
static int	NO_TEXT Do not display progress value in text form.
static int	PERCENT Displays progress as a percentage.

Fields inherited from class net.rim.device.api.ui.Field

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Constructor Summary

GaugeField()
Constructs a new GaugeField instance.

GaugeField(String label, int min, int max, int start, long style)
Constructs a new GaugeField instance with label, values, and style.

Method Summary
protected void	drawFocus(Graphics graphics, boolean on) Draws the focus indicator for this field.
AccessibleContext	getAccessibleContext() Returns accessible representation of the field for a screen reader.
String	getLabel() Retrieves this field's label.
int	getPreferredHeight() Retrieves this field's preferred height.
int	getPreferredWidth() Retrieves this field's preferred width.
int	getValue() Retrieves the current progress level.
int	getValueMax() Retrieves the highest value in this field's range.
int	getValueMin() Retrieves the lowest value in this field's ragne.
protected void	layout(int width, int height) Lays out this field's contents.
protected void	makeContextMenu(ContextMenu contextMenu) Builds this field's context menu.
protected int	moveFocus(int amount, int status, int time) Handles moving the focus within this field.
protected void	paint(Graphics graphics) Redraws this field.
void	reset(String label, int min, int max, int start) Resets this field's values.
void	setLabel(String label) Sets this field's label.
void	setValue(int value) Sets the progress level for the gauge.

Methods inherited from class net.rim.device.api.ui.Field

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_TEXT

public static final int NO_TEXT

Do not display progress value in text form.

By default, this field displays the progress in a textual form.

See Also:

Constant Field Values

PERCENT

public static final int PERCENT

Displays progress as a percentage.

By default, this field displays progress in absolute values (that is, the actual values ranging from the min to the max of this field's range).

See Also:

Constant Field Values

LABEL_AS_PROGRESS

public static final long LABEL_AS_PROGRESS

Display the label as the progress value.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.0

Constructor Detail

GaugeField

public GaugeField()

Constructs a new GaugeField instance.

This builds a new gauge field with no label, 0 for min, 100 for max, and PERCENT as style.

GaugeField

public GaugeField(String label,
                  int min,
                  int max,
                  int start,
                  long style)

Constructs a new GaugeField instance with label, values, and style.

Provided a range of values and a start position, this method builds a gauge field of your specified style, and sets the extent of its progress to your start position.

Note that the range of values handled by this field includes both your min and max values, and that (min <= start <= max).

When using this constructor, you specify this field's style as a combination of this class's various style constants (Field.FOCUSABLE, Field.EDITABLE, GaugeField.NO_TEXT, GaugeField.PERCENT).

Parameters:

label - Optional label for the gauge (may be null).

min - Bottom of the value range.

max - Top of the value range.

start - Initial progress level of this field.

style - Style value(s) for this field.

Throws:

IllegalArgumentException - if max is less than or equal to min, or start is not in the range between min and max.

Method Detail

reset

public void reset(String label,
                  int min,
                  int max,
                  int start)

Resets this field's values.

The parameters for this method serve exactly the same purpose as in the constructor, GaugeField.GaugeField(java.lang.String, int, int, int, long).

Parameters:

label - Optional label for the gauge (may be null).

min - Bottom of the value range.

max - Top of the value range.

start - Initial progress level of this field.

Throws:

IllegalArgumentException - if max is less than or equal to min, or start is not in the range between min and max.

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)

Draws the focus indicator for this field.

This field's manager invokes this method after painting this field to invert the border of the focus indicator.

Overrides:

drawFocus in class Field

Parameters:

graphics - Graphics context for drawing the focus.

on - True if the focus should be set; otherwise, false.

getValueMin

public int getValueMin()

Retrieves the lowest value in this field's ragne.

Returns:

Bottom of the allowable value range.

getValueMax

public int getValueMax()

Retrieves the highest value in this field's range.

Returns:

Top of the allowable value range.

getValue

public int getValue()

Retrieves the current progress level.

Returns:

Current progress value.

getLabel

public String getLabel()

Retrieves this field's label.

Returns:

Current label; can be null if this field has no label.

layout

protected void layout(int width,
                      int height)

Lays out this field's contents.

this field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of available space.

Note that this field always uses all the available horizontal width.

Specified by:

layout in class Field

Parameters:

width - Amount of available horizontal space.

height - Amount of available vertical space.

getPreferredHeight

public int getPreferredHeight()

Description copied from class: Field

Retrieves this field's preferred height. Your implementation of getPreferredHeight() should return the height of your custom field if it has any amount of space available.

Managers may make use of this value during layout. Override this method to request a certain height for your field.

Overrides:

getPreferredHeight in class Field

Returns:

Preferred height for this field in pixels.

See Also:

Field.getPreferredHeight()

Since:

BlackBerry API 4.0.2

getPreferredWidth

public int getPreferredWidth()

Description copied from class: Field

Retrieves this field's preferred width. Your implementation of getPreferredWidth() should return the width of your custom field if it has any amount of space available.

Managers make use of this value during layout. Override this method to request a certain width for your field.

Overrides:

getPreferredWidth in class Field

Returns:

Preferred width for this field in pixels.

See Also:

Field.getPreferredWidth()

Since:

BlackBerry API 4.0.2

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)

Builds this field's context menu.

Field.getContextMenu() invokes this method to construct this field's context menu.

If the UI is not operating in MODE_ADVANCED mode, this method builds this field's context menu adding a menu item for changing this field's value.

Overrides:

makeContextMenu in class Field

Parameters:

contextMenu - Context menu to build.

See Also:

ContextMenu

paint

protected void paint(Graphics graphics)

Redraws this field.

This field's manager invokes this method during the repainting process to instruct this field to repaint itself.

Specified by:

paint in class Field

Parameters:

graphics - Graphics context for repainting this field.

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)

Handles moving the focus within this field.

This field's manager invokes this method only when this field already has the focus.

If this field is not Field.EDITABLE, this method does nothing and returns the entire roll amount.

If the trackwheel is ALT-rolling the roll amount is used to change the progress value of the gauge field. If an end of this field's allowable range is reached, this method clamps the progress value to the maximum or minimum end of the range (as appropriate) and returns zero.

Overrides:

moveFocus in class Field

Parameters:

amount - Number of positions to move, positive means downward (or towards the max end of the field's progress value), negative means upward (or towards the min end of the field's progress value).

status - Modifier key state: if KeypadListener.STATUS_ALT, then this method uses the roll amount to change this field's progress value.

time - Number of milliseconds since the device was turned on.

Returns:

Remaining scroll amount not used up. If the roll amount is used to alter this field's progress value, then this method uses up the entire roll amount. Otherwise, this method returns the entire roll amount.

setLabel

public void setLabel(String label)

Sets this field's label.

You can leave this field without a label: provide null for this method's parameter.

Parameters:

label - New label for this field.

setValue

public void setValue(int value)

Sets the progress level for the gauge.

Parameters:

value - New progress level for this field.

Throws:

IllegalArgumentException - if value is less than the bottom of the value range or greater than the top of the value range. The value range is set when the field is constructed or when the field's values are reset.

See Also:

GaugeField.reset(java.lang.String, int, int, int)

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns accessible representation of the field for a screen reader.

Overrides:

getAccessibleContext in class Field

Returns:

AccessibleContext instance

Since:

BlackBerry API 4.6.1