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

public class NumericChoiceField
extends ChoiceField

A choice field that supports choosing 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.

Field Summary

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

CONTEXT_CHANGE_OPTION

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

NumericChoiceField()
Constructs a new NumericChoiceField instance.

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

NumericChoiceField(String label, int begin, int end, int increment, int initialIndex)
Constructs a new NumericChoiceField instance 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) Traps control key events to seek to the appropriate choice.
protected boolean	keyRepeat(int keycode, int time) Handles key repeat events.
protected boolean	keyStatus(int keycode, int time) Handles key status events.
protected void	makeContextMenu(ContextMenu contextMenu) Builds this field's context menu.
protected boolean	navigationClick(int status, int time) Invoked when the navigational action is selected.
protected void	onUnfocus() Invoked when this field loses focus.
void	setSelectedValue(int value) Sets value of the desired choice.
void	setSelectedValue(int value, int context) Sets value of the desired choice.

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

drawFocus, getAccessibleContext, getFocusRect, getHeightOfChoices, getLabel, getPreferredHeight, getSelectedIndex, getSize, getWidthOfChoice, invokeAction, layout, moveFocus, paint, setEditable, setLabel, setNumberOfChoices, setSelectedIndex, setSelectedIndex, setSelectedIndex, setSize, toString, touchEvent, trackwheelClick, trackwheelUnclick

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, 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, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyDown, keyUp, moveFocus, navigationMovement, navigationUnclick, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, 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 NumericChoiceField 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 NumericChoiceField instance 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.

Specified by:

getChoice in class ChoiceField

Parameters:

index - Index of choice for which to retrieve value.

Returns:

Numeric value at specified index.

getSelectedValue

public int getSelectedValue()

Retrieves value of the currently selected choice.

Returns:

Value value of the currently selected choice.

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)

Builds this field's context menu.

Be sure to save and terminate manual edit mode first.

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

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

Overrides:

makeContextMenu in class ChoiceField

Parameters:

contextMenu - Context menu to build.

See Also:

ContextMenu

Since:

BlackBerry API 4.0.0

setSelectedValue

public void setSelectedValue(int value,
                             int context)

Sets value of the desired choice.

Parameters:

value - Value, not the index, of the desired choice (checked against the maximum/minimum allowable values).

context - Context in which the change was made.

Since:

BlackBerry API 4.0.0

setSelectedValue

public void setSelectedValue(int value)

Sets value of the desired choice.

Parameters:

value - Value, not the index, of the desired choice (checked against the maximum/minimum allowable values).

Since:

BlackBerry API 4.0.0

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, the behaviour is different depending on the style of the keyboard. On devices with a full QWERTY keyboard, 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. However, on devices with a reduced QWERTY keyboard using a SureType® input method (like the BlackBerry Pearl 8100 Series smartphones), if the key generated was a SPACE character, this method multiplies the selected value by 10. It then finds the nearest choice to this value from the field's list.

Overrides:

keyChar in class ChoiceField

Parameters:

key - Character generated by the event.

status - State of the modifier keys.

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

Returns:

True if this event was consumed; otherwise, false.

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)

Handles key repeat events.

By default, this method returns false; custom fields that specially handle key repeat events must override this method.

Overrides:

keyRepeat in class Field

Parameters:

keycode - Code of key repeated.

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

Returns:

False (classes that extend Field must override this method to provide specific handling).

Since:

BlackBerry API 4.1.0

navigationClick

protected boolean navigationClick(int status,
                                  int time)

Invoked when the navigational action is selected.

The system invokes this method when passing on a navigational click event.

The ALT-click combination will enter selection mode, or if in selection mode will copy.

The source of the navigation event can be determined by checking the KeypadListener.STATUS_TRACKWHEEL and KeypadListener.STATUS_FOUR_WAY bits in the status parameter; exactly one of them will be set.

Overrides:

navigationClick in class Field

Parameters:

status - Bitfield of values defined by KeypadListener.

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

Returns:

True if this method consumed the event; otherwise, false.

Since:

BlackBerry API 4.2.0

onUnfocus

protected void onUnfocus()

Invoked when this field loses focus.

This method will not be invoked if this field does not already have the focus.

This method clears the muddy bit and removes selection, but it also ensures an edit-in-progress is saved and terminated.

Overrides:

onUnfocus in class ChoiceField

Since:

BlackBerry API 4.0.0

keyControl

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

Traps control key events to seek to the appropriate choice. This method handles a control key generation event: if the ALTed version of the character passed in is a digit, then this method acts as a wrapper for NumericChoiceField.keyChar(char, int, int). Otherwise, it simply returns false.

Overrides:

keyControl in class ChoiceField

Parameters:

character - Character generated by the event.

status - Modifier key status.

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

Returns:

True if this event was consumed; otherwise, false.

Since:

BlackBerry API 3.6.0

keyStatus

protected boolean keyStatus(int keycode,
                            int time)

Handles key status events.

Overrides:

keyStatus in class ChoiceField

Parameters:

keycode - Code of status key.

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

Returns:

True if event was consumed; otherwise false.

Since:

BlackBerry API 4.0.0