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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.GaugeField
All Implemented Interfaces:
AccessibleContext, FieldLabelProvider, IComponent, InputMethodListener

public class GaugeField
extends Field
implements FieldLabelProvider

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, 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.
 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, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, 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, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail


LABEL_AS_PROGRESS

public static final long LABEL_AS_PROGRESS
Display the label as the progress value.
Since:
JDE 4.2.0

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.


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

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, NO_TEXT, 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

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.

getLabel

public String getLabel()
Retrieves this field's label.
Returns:
Current label; can be null if this field has no label.

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
Since:
JDE 4.0.2
See Also:
Field#getPreferredHeight}

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
Since:
JDE 4.0.2
See Also:
Field#getPreferredWidth}

getValue

public int getValue()
Retrieves the current progress level.
Returns:
Current progress value.

getValueMax

public int getValueMax()
Retrieves the highest value in this field's range.
Returns:
Top of the allowable value range.

getValueMin

public int getValueMin()
Retrieves the lowest value in this field's ragne.
Returns:
Bottom of the allowable value range.

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.

Overrides:
layout in class Field
Parameters:
width - Amount of available horizontal space.
height - Amount of available vertical space.

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

Following copied from class: Field
Parameters:
contextMenu - Context menu to build.
See Also:
ContextMenu

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.

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.

Overrides:
paint in class Field
Parameters:
graphics - Graphics context for repainting this field.

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

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 outside the valid range.



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.