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:
ITextInputStyle, KeyListener, KeypadListener

public class TextSpinBoxField
extends SpinBoxField
implements KeyListener, ITextInputStyle

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
DEFAULT_ROW_HEIGHT, 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.
 TextFilter getFilter()
          Gets the text filter set for this field.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 int getTextInputStyle()
          Returns text related style bits (including filter styles); Implements IComponent interface
protected  boolean invokeAction(int action)
          Invokes an action on this field.
 boolean isUnicodeInputAllowed()
          Determines if this field allows the Unicode input.
 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.
 void updateInputStyle()
          Updates text input style via input method control object.
 
Methods inherited from class net.rim.device.api.ui.component.SpinBoxField
applyTheme, drawFocus, fieldChangeNotify, 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
cursorClick, cursorUnclick, drawHighlightRegion, focusAdd, focusRemove, getAccessibleContext, 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, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isLeftToRight, isMuddy, isPasteable, isScrollCopyable, 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, setCommandItemProvider, setCookie, setDirty, setEnabled, setExtent, setFocus, setFocusListener, setFont, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface net.rim.device.api.im.ITextInputStyle
getPreferredInputLocale, isEditable
 



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:
TextSpinBoxField.MATCH_FIRST_CHAR_ONLY
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:
The 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 - The character generated.
status - The modifier key status. See KeypadListener.
time - The number of milliseconds since the device was turned on.
Returns:
true if this method consumed the event, false otherwise.
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 startIndex
Returns:
true if a match was found.
Throws:
IllegalArgumentException - if startIndex > endIndex.
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 - The code of the key that was pressed.
time - The 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 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 - The code of the key that was repeated.
time - The 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 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 - The code of the status key.
time - The 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 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 - The code of the key that was released.
time - The 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 5.0.0

getTextInputStyle

public int getTextInputStyle()
Returns text related style bits (including filter styles); Implements IComponent interface

Specified by:
getTextInputStyle in interface ITextInputStyle
Overrides:
getTextInputStyle in class Field
Returns:
int the text input style
Since:
BlackBerry API 6.0.0

isUnicodeInputAllowed

public boolean isUnicodeInputAllowed()
Determines if this field allows the Unicode input.

Specified by:
isUnicodeInputAllowed in interface ITextInputStyle
Returns:
True if this field allows the Unicode input.
Since:
BlackBerry API 6.0.0

updateInputStyle

public void updateInputStyle()
Updates text input style via input method control object.

Can be used to update the input method with text component input preferences such as preferred repositories.

Present TextField's implementation resets value of input style.

Specified by:
updateInputStyle in interface ITextInputStyle
Since:
BlackBerry API 6.0.0

getFilter

public TextFilter getFilter()
Gets the text filter set for this field.

Specified by:
getFilter in interface ITextInputStyle
Returns:
the text filter set for this field if exist otherwise return null;
Since:
BlackBerry API 6.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

invokeAction

protected boolean invokeAction(int action)
Invokes an action on this field.

This method is designed to be overridden by subclasses to perform custom behavior for different actions. The implementation in this class does nothing and returns false.

If action is not a recognized action then this method does nothing and returns false, indicating that the action was not consumed.

Overrides:
invokeAction in class Field
Parameters:
action - The action to be performed on this field.
Returns:
true if the action was consumed, false if the action was not consumed.
See Also:
Manager#invokeAction
Since:
BlackBerry API 6.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal