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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.ChoiceField
              |
              +--net.rim.device.api.ui.component.NumericChoiceField

All Implemented Interfaces:

IComponent, InputMethodListener

public class NumericChoiceField

extends ChoiceField

A choice field that supports chosing from a range of numeric values. Choice for a closed range of integers. This is intended to be used for small ranges (for example, less than 20 items); otherwise, use EditField with a NumericTextFilter.

When creating a NumericChoiceField you specify a range of values that deviate by a single specified increment -- you cannot create a field with values unevenly spread across the range.

Behaviour

Looks like a ChoiceField.

Typing a digit will append it to the number. However, if nothing was previously typed (ie. the field is not muddy) then it will first be cleared. If the result is out of bounds, most significant digits will be taken off until the result is within the range or zero is reached in which case it will be set to the amount within the range closest to 0.

Space will add one, backspace will take away the last digit.

Fields inherited from class net.rim.device.api.ui.component.ChoiceField

CONTEXT_CHANGE_OPTION

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

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

Constructor Summary

NumericChoiceField()
Constructs a new NumericChoiceField instance.

NumericChoiceField(String label, int begin, int end, int increment)
Constructs a new NumbericChoiceField instance with label, range values and increment.

NumericChoiceField(String label, int begin, int end, int increment, int initialIndex)
Constructs a new numeric choice field and sets initially selected value.

Method Summary

Object	getChoice(int index) Retrieves value for specified index.
int	getPreferredWidth() Retrieves this field's preferred width.
int	getSelectedValue() Retrieves value of the currently selected choice.
protected boolean	keyChar(char key, int status, int time) Traps key events to seek to the appropriate choice.
protected boolean	keyControl(char character, int status, int time) Like keyChar, but for control characters.

Methods inherited from class net.rim.device.api.ui.component.ChoiceField

getFocusRect, getLabel, getSelectedIndex, getSize, keyStatus, layout, makeContextMenu, moveFocus, paint, setLabel, setSelectedIndex, setSelectedIndex, setSelectedIndex, setSize

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

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, getWidth, invalidate, invalidate, isDirty, isEditable, isFocusable, isMuddy, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isVisible, keyDown, keyRepeat, keyUp, moveFocus, onFocus, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setPosition, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

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

Constructor Detail

NumericChoiceField

public NumericChoiceField()

Constructs a new NumericChoiceField instance.

Builds a numeric choice field with no label, no starting or ending value, and an increment value of 1.

NumericChoiceField

public NumericChoiceField(String label,
                          int begin,
                          int end,
                          int increment)

Constructs a new NumbericChoiceField instance with label, range values and increment.

Parameters:

label - Label for this field.

begin - First value in the range.

end - Last value in the range.

increment - The amount to increase between each choice value.

NumericChoiceField

public NumericChoiceField(String label,
                          int begin,
                          int end,
                          int increment,
                          int initialIndex)

Constructs a new numeric choice field and sets initially selected value.

Parameters:

label - Label for this field.

begin - First value in the range.

end - Last value in the range.

increment - The amount to increase between each choice value.

initialIndex - Index of the initially selected value.

Method Detail

getPreferredWidth

public int getPreferredWidth()

Retrieves this field's preferred width.

This field's manager invokes this method to assist in its layout.

Overrides:

getPreferredWidth in class ChoiceField

Returns:

Preferred width (in pixels) of this field.

getChoice

public Object getChoice(int index)

Retrieves value for specified index.

Overrides:

getChoice in class ChoiceField

Parameters:

index - Index of choice for which to retrieve value.

Returns:

Numeric value at specified index.

Since:

JDE 3.7.0

getSelectedValue

public int getSelectedValue()

Retrieves value of the currently selected choice.

Returns:

the value, not the index, of the currently selected choice.

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)

Traps key events to seek to the appropriate choice.

This method handles and consumes a key generation event, only if this field is Field.EDITABLE; otherwise, it does nothing and does not consume the event.

If the key generated was a number key, and the field has not already been changed (muddied), this method uses the number generated by the key press as the selected value. It then finds the nearest choice to this value from this field's list.

If the key generated was a number key, and the field has already been changed, this method concatenates the number generated by the key press to the selected value. It then finds the nearest choice to this value from this field's list.

If the key generated was a BACKSPACE character, this method divides the current selected value by 10 (i.e., deletes the last digit of the currently selected value). It then finds the nearest choice to this value from this field's list.

If the key generated was a DELETE character, this method sets the selected value to 0. It then finds the nearest choice to zero from this field's list.

If the key generated was a SPACE character, this method first increments the selected value by one. It then finds the nearest choice to this value from this field's list. If incrementing puts the specified value beyond the end of the list, then this method wraps and selects the first choice in this field's list.

Overrides:

keyChar in class ChoiceField

Parameters:

key - Character generated by the event.

status - State of the modifier keys.

time - Ticks since device reset (this parameter is ignored).

Returns:

True if this event was consumed; otherwise, false.

Since:

JDE 3.7.0

keyControl

protected boolean keyControl(char character,
                             int status,
                             int time)

Like keyChar, but for control characters.

Overrides:

keyControl in class Field

Since:

JDE 3.7.0