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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.component.SpinBoxField
          extended by net.rim.device.api.ui.component.TextSpinBoxField
All Implemented Interfaces:
KeyListener, KeypadListener

public class TextSpinBoxField
extends SpinBoxField
implements KeyListener

A SpinBoxField that renders text. Users of this class construct an instance with an array of objects to display. Each object's toString method will be used to retrieve the string to render. See SpinBoxFieldManager for additional documentation.

Text Matching

The choices in the spin box field can be automatically selected based on keyboard presses. The choices can be matched either by first character or by the entire word. See the style TextSpinBoxField.MATCH_FIRST_CHAR_ONLY. To match the entire text, do not use style TextSpinBoxField.MATCH_FIRST_CHAR_ONLY. Additionally, if all of the choices are numeric, then use TextSpinBoxField.NUMERIC_CHOICES then the keyboard presses will be automatically alt-ed. The search for a match is optimized for ordered and sequential lists. Subclasses may override the search for efficiency purposes or customized searches. See TextSpinBoxField.findOtherMatch(char).

Virtual Keyboard

If the device supports a Virtual Keyboard, a virtual keyboard will be displayed automatically if this field is focused on a screen that is pushed onto the display stack. Additionally, the numeric keys will be shown if the TextSpinBoxField.NUMERIC_CHOICES style is used. If showing the virtual keyboard is undesirable, you can hide the screen using code like the following.
        // Hide the virtual keyboard by default
        final Screen screen = getScreen();

        if (screen != null) {
            final VirtualKeyboard virtualKeyboard = screen.getVirtualKeyboard();
            if (virtualKeyboard != null) {
                virtualKeyboard.setVisibility(VirtualKeyboard.HIDE);
            }
        }        
 

See Also:
SpinBoxField, SpinBoxFieldManager, VirtualKeyboard
Since:
BlackBerry API 5.0.0

Field Summary
static long MATCH_FIRST_CHAR_ONLY
          A style that indicates that the text is matched by the first character only.
static long NUMERIC_CHOICES
          Indicates that the supplied choices are numeric so that keys are automatically ALT-ed when necessary.
 
Fields inherited from class net.rim.device.api.ui.component.SpinBoxField
NO_WRAP, SPINBOX_STOPPED, SPINBOX_WRAP_FIRST_TO_LAST_INDEX, SPINBOX_WRAP_LAST_TO_FIRST_INDEX
 
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
 
Fields inherited from interface net.rim.device.api.system.KeypadListener
STATUS_ALT, STATUS_ALT_LOCK, STATUS_CAPS_LOCK, STATUS_FOUR_WAY, STATUS_KEY_HELD_WHILE_ROLLING, STATUS_NOT_FROM_KEYPAD, STATUS_SHIFT, STATUS_SHIFT_LEFT, STATUS_SHIFT_RIGHT, STATUS_TRACKWHEEL
 
Constructor Summary
TextSpinBoxField()
          Construct an empty texts spin box.
TextSpinBoxField(Object[] choices)
          Construct a spin box field from an array of objects (the toString method will be used to retrieve the text to display).
TextSpinBoxField(Object[] choices, long style)
          Construct a spin box field from an array of objects (the toString method will be used to retrieve the text to display).
 
Method Summary
protected  void drawRow(Graphics graphics, int index, int x, int y, int width, int height)
          Draw the specified row in the given parameters.
protected  void endMatch()
          Ends a text matching.
protected  boolean findOtherMatch(char matchChar)
          Finds a match in the spin box (except selected index) from a character.
protected  boolean findOtherMatch(String matchedString)
          Finds a match in the spin box (except selected index) from a string.
protected  boolean findOtherMatch(String matchedString, int startIndex, int endIndex)
          Finds a match in the spin box (except selected index) from a string.
 Object get(int index)
          Retrieve the object at the given index.
 int getCount()
          Returns The number of objects that could be displayed in the spin box.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 boolean keyChar(char key, int status, int time)
          Handles character generation events.

This field's manager invokes this method to send this field a character event.

Special keystroke handling code should be implemented in the Field keyDown method. However, this code checks for cut, copy, or paste keystrokes and dispatches to the appropriate field.

While selection mode is on, ESC cancels selection, and SHIFT+DEL cuts selection.

 boolean keyDown(int keycode, int time)
          Handles key down events.
 boolean keyRepeat(int keycode, int time)
          Handles key repeat events.
 boolean keyStatus(int keycode, int time)
          Handles key status events.
 boolean keyUp(int keycode, int time)
          Handles key up events.
 void setChoices(Object[] choices)
          Sets the choices for the spin box.
protected  void startMatch()
          Starts a text matching.
 
Methods inherited from class net.rim.device.api.ui.component.SpinBoxField
applyTheme, drawFocus, getPreferredHeight, getRowHeight, getSelectedIndex, getSpinBoxFieldManager, getVisibleRows, layout, moveFocus, moveSelectedIndex, moveSelectedIndex, navigationMovement, onFocus, onUnfocus, paint, refresh, setEditable, setRowHeight, setSelectedIndex, setSelectedIndex, setVisibleRows, touchEvent, updateSelectedIndex, wrap
 
Methods inherited from class net.rim.device.api.ui.Field
drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, 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, keyControl, makeContextMenu, moveFocus, navigationClick, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, 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

MATCH_FIRST_CHAR_ONLY

public static final long MATCH_FIRST_CHAR_ONLY
A style that indicates that the text is matched by the first character only. If this style is not set, all of the characters of each choice will attempt to be matched.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0

NUMERIC_CHOICES

public static final long NUMERIC_CHOICES
Indicates that the supplied choices are numeric so that keys are automatically ALT-ed when necessary.

See Also:
Constant Field Values
Since:
BlackBerry API 5.0.0


Constructor Detail

TextSpinBoxField

public TextSpinBoxField()
Construct an empty texts spin box.

Since:
BlackBerry API 5.0.0

TextSpinBoxField

public TextSpinBoxField(Object[] choices)
Construct a spin box field from an array of objects (the toString method will be used to retrieve the text to display). By default, the choices are matched by first character only for key presses.

Parameters:
choices - an array of objects to display, must not be null, each element in the array must not be null.
Since:
BlackBerry API 5.0.0

TextSpinBoxField

public TextSpinBoxField(Object[] choices,
                        long style)
Construct a spin box field from an array of objects (the toString method will be used to retrieve the text to display).

Parameters:
choices - an array of objects to display, must not be null, each element in the array must not be null.
style - the styles supported are TextSpinBoxField.MATCH_FIRST_CHAR_ONLY and #NUMERIC
See Also:
#setMatchFirstCharacter, #isMatchFirstCharacter
Since:
BlackBerry API 5.0.0


Method Detail

setChoices

public void setChoices(Object[] choices)
Sets the choices for the spin box.

Parameters:
choices - an array of objects to display, each element in the array must not be null. The object's toString method will be used for display.
Since:
BlackBerry API 5.0.0

drawRow

protected void drawRow(Graphics graphics,
                       int index,
                       int x,
                       int y,
                       int width,
                       int height)
Draw the specified row in the given parameters.

Specified by:
drawRow in class SpinBoxField
Parameters:
graphics - graphics context, never null.
index - which index to draw.
x - The top left x coordinate where drawing could begin.
y - The top left y coordinate where drawing could begin.
width - the width available.
height - the height available.
See Also:
SpinBoxField.drawRow(net.rim.device.api.ui.Graphics, int, int, int, int, int)
Since:
BlackBerry API 5.0.0

getPreferredWidth

public int getPreferredWidth()
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 5.0.0

get

public Object get(int index)
Retrieve the object at the given index.

Specified by:
get in class SpinBoxField
Parameters:
index - The index to retrieve; must be an in bounds index.
Returns:
the object corresponding to the given index.
See Also:
SpinBoxField.get(int)
Since:
BlackBerry API 5.0.0

getCount

public int getCount()
Returns The number of objects that could be displayed in the spin box.

Specified by:
getCount in class SpinBoxField
Returns:
The number of objects that could be displayed in the spin box, must be >= 0;
See Also:
SpinBoxField.getCount()
Since:
BlackBerry API 5.0.0

keyChar

public boolean keyChar(char key,
                       int status,
                       int time)
Handles character generation events.

This field's manager invokes this method to send this field a character event.

Special keystroke handling code should be implemented in the Field keyDown method. However, this code checks for cut, copy, or paste keystrokes and dispatches to the appropriate field.

While selection mode is on, ESC cancels selection, and SHIFT+DEL cuts selection.

Specified by:
keyChar in interface KeyListener
Overrides:
keyChar in class SpinBoxField
Parameters:
key - Character generated.
status - Modifier key status. See KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
See Also:
KeyListener.keyChar(char, int, int)
Since:
BlackBerry API 5.0.0

findOtherMatch

protected boolean findOtherMatch(char matchChar)
Finds a match in the spin box (except selected index) from a character. The selected index is changed accordingly.

* This method performs a linear search throughout the elements starting after the currently selected index, then wraps around to the element just before the selected index. Subclasses can choose to override this method for efficiency or custom find algorithms.

If matching first character only, then the spin box is animated. Otherwise, the spin box snaps to the match.

Parameters:
matchChar - A character to match
Returns:
true if a character was matched.
Since:
BlackBerry API 5.0.0

findOtherMatch

protected boolean findOtherMatch(String matchedString)
Finds a match in the spin box (except selected index) from a string. The selected index is changed accordingly.

This method performs a linear search throughout the elements starting after the currently selected index, then wraps around to the element just before the selected index. Subclasses can choose to override this method for efficiency or custom find algorithms.

If matching first character only, then the spin box is animated. Otherwise, the spin box snaps to the match.

Parameters:
matchedString - a non null string to match
Returns:
true if a match was found.
Since:
BlackBerry API 5.0.0

findOtherMatch

protected boolean findOtherMatch(String matchedString,
                                 int startIndex,
                                 int endIndex)
Finds a match in the spin box (except selected index) from a string. The selected index is changed accordingly.

This method performs a linear search throughout the elements starting after the currently selected index, then wraps around to the element just before the selected index. Subclasses can choose to override this method for efficiency or custom find algorithms.

If matching first character only, then the spin box is animated. Otherwise, the spin box snaps to the match.

Parameters:
matchedString - a non null string to match
startIndex - the start index within the choices to search, must be less than or equal to endIndex
endIndex - the end index within the choices to search, must be greater than or equal to endIndex
Returns:
true if a match was found.
See Also:
TextSpinBoxField.MATCH_FIRST_CHAR_ONLY
Since:
BlackBerry API 5.0.0

keyDown

public boolean keyDown(int keycode,
                       int time)
Handles key down events.

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

Specified by:
keyDown in interface KeyListener
Overrides:
keyDown in class Field
Parameters:
keycode - Code of key pressed.
time - Number of milliseconds since the device was turned on.
Returns:
False (classes that extend Field must override this method to provide specific handling).
See Also:
KeyListener.keyDown(int, int)
Since:
BlackBerry API 5.0.0

keyRepeat

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

Specified by:
keyRepeat in interface KeyListener
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).
See Also:
KeyListener.keyRepeat(int, int)
Since:
BlackBerry API 5.0.0

keyStatus

public boolean keyStatus(int keycode,
                         int time)
Handles key status events.

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

Specified by:
keyStatus in interface KeyListener
Overrides:
keyStatus in class Field
Parameters:
keycode - Code of status key.
time - Number of milliseconds since the device was turned on.
Returns:
False (classes that extend Field must override this method to provide specific handling).
See Also:
KeyListener.keyStatus(int, int)
Since:
BlackBerry API 5.0.0

keyUp

public boolean keyUp(int keycode,
                     int time)
Handles key up events.

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

Specified by:
keyUp in interface KeyListener
Overrides:
keyUp in class Field
Parameters:
keycode - Code of key released.
time - Number of milliseconds since the device was turned on.
Returns:
False (classes that extend Field must override this method to provide specific handling).
See Also:
KeyListener.keyUp(int, int)
Since:
BlackBerry API 5.0.0

endMatch

protected void endMatch()
Ends a text matching.

See Also:
startMatch
Since:
BlackBerry API 5.0.0

startMatch

protected void startMatch()
Starts a text matching. A matching ends in two ways: timer expires or TextSpinBoxField.endMatch() is called.

Since:
BlackBerry API 5.0.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.