|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.ui.component.SpinBoxField
net.rim.device.api.ui.component.TextSpinBoxField
public class TextSpinBoxField
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.
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
, 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);
}
}
SpinBoxField
,
SpinBoxFieldManager
,
VirtualKeyboard
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 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
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. |
|
protected void |
refresh()
This method must be called when the contents/choices have changed. |
|
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, setEditable, setRowHeight, setSelectedIndex, setSelectedIndex, setVisibleRows, touchEvent, updateSelectedIndex, wrap |
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 |
---|
public static final long MATCH_FIRST_CHAR_ONLY
public static final long NUMERIC_CHOICES
Constructor Detail |
---|
public TextSpinBoxField()
public TextSpinBoxField(Object[] choices)
toString
method will be used to retrieve the text to display). By default,
the choices are matched by first character only for key presses.
choices
- an array of objects to display,
must not be null,
each element in the array must not be null.public TextSpinBoxField(Object[] choices, long style)
toString
method will be used to retrieve the text to display).
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
TextSpinBoxField.MATCH_FIRST_CHAR_ONLY
Method Detail |
---|
public void setChoices(Object[] choices)
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.protected void refresh()
refresh
in class SpinBoxField
protected void drawRow(Graphics graphics, int index, int x, int y, int width, int height)
drawRow
in class SpinBoxField
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.SpinBoxField.drawRow(net.rim.device.api.ui.Graphics, int, int, int, int, int)
public int getPreferredWidth()
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.
getPreferredWidth
in class Field
Field#getPreferredWidth
public Object get(int index)
get
in class SpinBoxField
index
- The index to retrieve; must be an in bounds index.
SpinBoxField.get(int)
public int getCount()
getCount
in class SpinBoxField
SpinBoxField.getCount()
public boolean keyChar(char key, int status, int time)
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.
keyChar
in interface KeyListener
keyChar
in class SpinBoxField
key
- The character generated.status
- The modifier key status. See KeypadListener
.time
- The number of milliseconds since the device was turned on.
true
if this method consumed the event,
false
otherwise.KeyListener.keyChar(char, int, int)
protected boolean findOtherMatch(char matchChar)
* 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.
matchChar
- A character to match
protected boolean findOtherMatch(String matchedString)
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.
matchedString
- a non null string to match
protected boolean findOtherMatch(String matchedString, int startIndex, int endIndex)
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.
matchedString
- a non null string to matchstartIndex
- 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
IllegalArgumentException
- if startIndex > endIndex
.TextSpinBoxField.MATCH_FIRST_CHAR_ONLY
public boolean keyDown(int keycode, int time)
By default, this method returns false
. Custom fields
that specially handle key down events must override this method.
keyDown
in interface KeyListener
keyDown
in class Field
keycode
- The code of the key that was pressed.time
- The number of milliseconds since the device was turned on.
false
. Classes that extend Field
must
override this method to provide specific handling.public boolean keyRepeat(int keycode, int time)
By default, this method returns false
. Custom fields
that specially handle key repeat events must override this method.
keyRepeat
in interface KeyListener
keyRepeat
in class Field
keycode
- The code of the key that was repeated.time
- The number of milliseconds since the device was turned on.
false
. Classes that extend Field
must
override this method to provide specific handling.public boolean keyStatus(int keycode, int time)
By default, this method returns false
. Custom fields
that specially handle key status events must override this method.
keyStatus
in interface KeyListener
keyStatus
in class Field
keycode
- The code of the status key.time
- The number of milliseconds since the device was turned on.
false
. Classes that extend Field
must
override this method to provide specific handling.public boolean keyUp(int keycode, int time)
By default, this method returns false
. Custom fields
that specially handle key up events must override this method.
keyUp
in interface KeyListener
keyUp
in class Field
keycode
- The code of the key that was released.time
- The number of milliseconds since the device was turned on.
false
. Classes that extend Field
must
override this method to provide specific handling.public int getTextInputStyle()
getTextInputStyle
in interface ITextInputStyle
getTextInputStyle
in class Field
public boolean isUnicodeInputAllowed()
isUnicodeInputAllowed
in interface ITextInputStyle
public void updateInputStyle()
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.
updateInputStyle
in interface ITextInputStyle
public TextFilter getFilter()
getFilter
in interface ITextInputStyle
protected void endMatch()
startMatch
protected void startMatch()
TextSpinBoxField.endMatch()
is called.
protected boolean invokeAction(int action)
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.
invokeAction
in class Field
action
- The action to be performed on this field.
true
if the action was consumed, false
if the action was not consumed.Manager#invokeAction
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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