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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.component.TextField
          extended by net.rim.device.api.ui.component.BasicEditField
              extended by net.rim.device.api.ui.component.EditField
All Implemented Interfaces:
ITextInputStyle
Direct Known Subclasses:
AutoTextEditField, EmailAddressEditField

public class EditField
extends BasicEditField

An editable simple text field with no formatting.

Behaviour
Displays a label in front of the text contents. If the contents occupy more than one line the text will flow around the label. The caret position is behaves as if it were between characters in the text contents, however it appears as a full inverted box on the character immediately following the caret.

The trackwheel moves the focus caret in the major direction (usually vertical), and using alt+trackwheel will move the focus caret in a less significant direction (usually horizontal).

If this field is Field.EDITABLE, typing inserts text into the contents at the caret position. The BACKSPACE character removes the character prior to the caret, and the DELETE character removes the character after the caret. Some subclasses of this may choose to support special symbols: typing a ALT+SPACE brings up the symbol screen from which the user can select a symbol.

Select Mode
In select mode, the selection is first anchored to a caret position, and moving the caret selects the text between the caret and the anchor. The following table summarizes the keystroke behaviour in select mode.

Keystroke Action taken
backspace nothing
alt+backspace nothing
shift+backspace nothing
delete delete
alt+delete delete
shift+delete cut
escape exit selection mode
alt+click copy
shift+click paste
shift+scroll select word

When not in select mode, these keystrokes should provide cut and paste functionality:

Keystroke Action taken
alt+click enter select mode
shift+click paste
shift+roll enter select mode and select word
An editable text field specifically designed for characters entered by holding a key while rolling the trackwheel.

Behaviour
Adds the ability to hold down a letter and roll to get related characters. The actual characters selected will be based on locale.

Rolling wraps around the list of available characters, once one end of the list is reached.

Where possible, rolling in the increasing direction will be symmetric to rolling in the decreasing direction: rolling two stops in the increase direction should give you the upper case of rolling two stops in the decrease direction (which gives lower case). For example, if holding 'A' and rolling one stop up gives '' then rolling one stop down must give ''. Also, accents must be traversed in the same order, so the accents on 'E' will be in the same order as the accents on 'A'. However, not all accents apply to all letters, for example 'N' might only have the tilde.


Field Summary
 
Fields inherited from class net.rim.device.api.ui.component.BasicEditField
FILTER_DEFAULT, FILTER_EMAIL, FILTER_FILENAME, FILTER_HEXADECIMAL, FILTER_INTEGER, FILTER_LOWERCASE, FILTER_NUMERIC, FILTER_PHONE, FILTER_PIN_ADDRESS, FILTER_REAL_NUMERIC, FILTER_UPPERCASE, FILTER_URL
 
Fields inherited from class net.rim.device.api.ui.component.TextField
CONSUME_INPUT, DEFAULT_MAXCHARS, JUMP_FOCUS_AT_END, NO_COMPLEX_INPUT, NO_EDIT_MODE_INPUT, NO_LEARNING, NO_NEWLINE, NO_SWITCHING_INPUT
 
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
EditField()
          Constructs an empty EditField object.
EditField(String label, String initialValue)
          Constructs an EditField object with label and initial contents.
EditField(String label, String initialValue, int maxNumChars, long style)
          Constructs a smaller EditField object with label, initial contents, and particular style.
EditField(long style)
          Constructs an empty EditField object.
 
Method Summary
protected  boolean isEnteringRollerCharacter()
          Determines if currently doing rolling character selection.
protected  boolean keyDown(int keycode, int time)
          Handles the key down event.
protected  boolean keyRepeat(int keycode, int time)
          Handles key repeat events.
protected  int moveFocus(int amount, int status, int time)
          Handles focus move events.
 
Methods inherited from class net.rim.device.api.ui.component.BasicEditField
backspace, backspace, backspace, charAt, clear, displayFieldFullMessage, drawFocus, getAccessibleContext, getCursorPosition, getFilter, getLabel, getLabelLength, getMaxSize, getPreferredHeight, getPreferredWidth, getText, getText, getText, getTextAbstractString, getTextLength, insert, insert, isSymbolScreenAllowed, keyChar, keyControl, layout, makeContextMenu, moveFocus, onUnfocus, paint, paste, selectionDelete, setCursorPosition, setCursorPosition, setFilter, setFont, setLabel, setMaxSize, setText, setText, update, wipe
 
Methods inherited from class net.rim.device.api.ui.component.TextField
drawText, fieldChangeNotify, getDescription, getFocusRect, getTrackpadScrollAmount, getTrackpadScrollLineSpeed, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionDeleteable, keyStatus, navigationClick, navigationUnclick, onFocus, select, selectionCopy, setDescription, toString, touchEvent
 
Methods inherited from class net.rim.device.api.ui.Field
cursorClick, cursorUnclick, drawHighlightRegion, 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, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isLeftToRight, isMuddy, isScrollCopyable, isSelectionCutable, isSpellCheckable, isStyle, isVisible, keyUp, navigationMovement, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onVisibilityChange, selectionCut, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface net.rim.device.api.im.ITextInputStyle
getPreferredInputLocale, getTextInputStyle, isEditable, isUnicodeInputAllowed, updateInputStyle
 



Constructor Detail

EditField

public EditField()
Constructs an empty EditField object.

This method builds an empty, Field.EDITABLE edit field that has no label and can hold up to TextField.DEFAULT_MAXCHARS characters.


EditField

public EditField(long style)
Constructs an empty EditField object.

This method builds an empty edit field with a style that has no label and can hold up to TextField.DEFAULT_MAXCHARS characters.

Note: EditField does not support the Field.FIELD_RIGHT style.

Parameters:
style - Styles for this field (see Field for usable styles).

EditField

public EditField(String label,
                 String initialValue)
Constructs an EditField object with label and initial contents.

This method builds an Field.EDITABLE edit field with a specified label and initial contents that can hold up to TextField.DEFAULT_MAXCHARS characters.

Parameters:
label - Label for this field.
initialValue - Initial text to show in this field.

EditField

public EditField(String label,
                 String initialValue,
                 int maxNumChars,
                 long style)
Constructs a smaller EditField object with label, initial contents, and particular style.

This class's other constructors build an Field.EDITABLE field by default. Use this method to build an edit field with some other style.

Note: EditField does not support the Field.FIELD_RIGHT style.

Parameters:
label - Label for this field.
initialValue - Initial text to show in the field.
maxNumChars - Maximum number of characters this field can hold.
style - Styles for this field (see Field for usable styles).
Throws:
IllegalArgumentException - If maxNumChars is less than 0, or the initialValue is invalid given the style.


Method Detail

keyDown

protected boolean keyDown(int keycode,
                          int time)
Handles the key down event. Most key events are handled in the BasicEditField.keyChar(char, int, int) event.

Information on which key was pressed is recorded and provided for handling rolling with a key held down.

Overrides:
keyDown in class BasicEditField
Parameters:
keycode - Character generated by the event.
time - Number of milliseconds since the device was turned on.
Returns:
Returns false.

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)
Handles key repeat events.

Overrides:
keyRepeat in class Field
Parameters:
keycode - Key held down.
time - Number of milliseconds since the device was turned on.
Returns:
Returns false.

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)
Handles focus move events.

This field's manager invokes this method to prompt this field to handle a focus move event.

Prior to invoking this method, this field's manager invokes Field.focusRemove(). After invoking this method, the framework invokes Field.focusAdd(boolean). This method also clears this field's muddy state (but only if the focus actually gets moved).

Overrides:
moveFocus in class BasicEditField
Parameters:
amount - The number of trackwheel positions to handle. A negative value indicates the focus came into this field from the bottom; a positive result indicates the focus came into this field from the top.
status - Modifier key status.
time - Number of milliseconds since the device was turned on.
Returns:
Remaining scroll amount, or zero if this method trapped a rolling character selection event.

isEnteringRollerCharacter

protected boolean isEnteringRollerCharacter()
Determines if currently doing rolling character selection.

Returns:
True if field is currently doing rolling character selection; otherwise, false.





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