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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.TextField
              |
              +--net.rim.device.api.ui.component.BasicEditField
                    |
                    +--net.rim.device.api.ui.component.EditField
                          |
                          +--net.rim.device.api.ui.component.AutoTextEditField
All Implemented Interfaces:
FieldLabelProvider, Formatter.TextRenderer, IComponent, InputMethodListener, InputMethodRequests
Direct Known Subclasses:
ActiveAutoTextEditField

public class AutoTextEditField
extends EditField

An editable text field designed to provide autotext support.

Behaviour
When a word is entered that is in the autotext database for the current locale, this field replaces it, including any effects of macro expansion. Pressing backspace when the caret is on the most recent autotext expansion reverses all effects of the autotext substitution.


Field Summary
static long AUTOCAP_OFF
          Do no automatic capitalization based on preceding punctuation.
static long AUTOPERIOD_OFF
          Do no automatic period insertion after two spaces.
static long AUTOREPLACE_OFF
          Do no autotext substitution on this field.
 
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, 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, 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
AutoTextEditField()
          Constructs a new default AutoTextEditField instance.
AutoTextEditField(String label, String initialValue)
          Constructs a new AutoTextEditField instance.
AutoTextEditField(String label, String initialValue, int maxNumChars, long style)
          Constructs a new, smaller AutoTextEditField instance, of a given style.
 
Method Summary
protected  boolean backspace()
          Deletes character to the left of the cursor, or deletes selection.
protected  boolean insert(char key, int status)
          Inserts character into this field.
 int insert(String text, int context, boolean stripInvalid, boolean validateText)
          Inserts string into this field, potentially stripping new lines and/or validating entered value.
protected  boolean keyChar(char key, int status, int time)
          Traps key generation events.
protected  boolean keyDown(int keycode, int time)
          Handles symbol screen key sequences.
protected  boolean keyRepeat(int keycode, int time)
          Handles key repeat events.
protected  int moveFocus(int amount, int status, int time)
          This field's manager invokes this method to prompt this field to handle a focus move event.
 void selectionDelete()
          Deletes character to the right of the cursor, or deletes selection.
protected  void setText(String text, int context)
          Sets the text value for this field, with indication of the source of this action.
protected  void update(int delta)
          Updates this field.
 
Methods inherited from class net.rim.device.api.ui.component.EditField
isEnteringRollerCharacter
 
Methods inherited from class net.rim.device.api.ui.component.BasicEditField
backspace, backspace, charAt, clear, displayFieldFullMessage, drawFocus, getCursorPosition, getFilter, getLabel, getLabelLength, getMaxSize, getPreferredHeight, getPreferredWidth, getText, getText, getText, getTextAbstractString, getTextLength, insert, insert, isSymbolScreenAllowed, keyControl, layout, makeContextMenu, moveFocus, onUnfocus, paint, paste, setCursorPosition, setCursorPosition, setFilter, setFont, setLabel, setMaxSize, setText, wipe
 
Methods inherited from class net.rim.device.api.ui.component.TextField
drawText, fieldChangeNotify, getFocusRect, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionDeleteable, navigationClick, navigationUnclick, onFocus, select, selectionCopy, toString
 
Methods inherited from class net.rim.device.api.ui.Field
drawHighlightRegion, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isSelectionCutable, isSpellCheckable, isStyle, isVisible, keyStatus, keyUp, navigationMovement, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onVisibilityChange, selectionCut, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setMuddy, setNonSpellCheckable, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail


AUTOCAP_OFF

public static final long AUTOCAP_OFF
Do no automatic capitalization based on preceding punctuation.
Since:
JDE 4.3.0

AUTOPERIOD_OFF

public static final long AUTOPERIOD_OFF
Do no automatic period insertion after two spaces.
Since:
JDE 4.3.0

AUTOREPLACE_OFF

public static final long AUTOREPLACE_OFF
Do no autotext substitution on this field.
Since:
JDE 4.3.0
Constructor Detail

AutoTextEditField

public AutoTextEditField()
Constructs a new default AutoTextEditField instance.

It has no label and no initial text.


AutoTextEditField

public AutoTextEditField(String label,
                         String initialValue)
Constructs a new AutoTextEditField instance.

This method builds an editable autotext field that can hold up to EditField#DEFAULT_MAXCHARS.

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

AutoTextEditField

public AutoTextEditField(String label,
                         String initialValue,
                         int maxNumChars,
                         long style)
Constructs a new, smaller AutoTextEditField instance, of a given style.

This method builds an autotext field of a specified style, that can hold a number of characters up to the amount you specify.

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

Parameters:
label - Label for this field.
initialValue - Initial text to show in the buffer.
maxNumChars - Maximum number of characters this field can hold.
style - Styles to apply to this field (for an editable field, specify the style Field.EDITABLE.
Method Detail

backspace

protected boolean backspace()
Deletes character to the left of the cursor, or deletes selection.

If some characters are currently selected, this method deletes the selection as if it were a single character.

If no characters were selected, this method deletes the character immediately to the left of the cursor. If the cursor is currently on the first character in the field, this method does nothing.

If the last key pressed generated an autotext replacement, this method undoes that replacement.

Overrides:
backspace in class BasicEditField
Returns:
True if this method successfully removed a character or selection (or undid an autotext replacement); otherwise, false.

insert

protected boolean insert(char key,
                         int status)
Inserts character into this field.

This method attempts to insert your specified character at the current cursor position. If this method succeeds with the insertion, it then moves the cursor to just after the inserted character.

If inserting the character would trigger an autotext expansion, then this method attempts to perform that insertion instead.

Overrides:
insert in class TextField
Parameters:
key - Character to insert.
Returns:
True if this field accepted your character (or the resulting replacement text); otherwise, false.

insert

public int insert(String text,
                  int context,
                  boolean stripInvalid,
                  boolean validateText)
Inserts string into this field, potentially stripping new lines and/or validating entered value. This method attempts to insert your specified string at the currrent cursor position. If this method (even partially) succeeds with the insertion, it then moves the cursor to just after the last character successfully inserted.

If the maximum size of the field is exceeded while inserting the string, as many characers as possible are inserted.

Overrides:
insert in class TextField
Parameters:
text - String to insert. If null, nothing happens.
context - Information specifying the origin of the change.
stripInvalid - True if method should strip invalid characters from the input text; otherwise, fail if invalid characters exist in the input text.
validateText - True if input text should be validated prior to the insertion attempt; otherwise, do not validate text.
Returns:
Actual number of characters successfully inserted.
Since:
JDE 4.0.0

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)
Traps key generation events.

This field's manager invokes this event to handle all key generation events, except for the special symbol screen event (triggered with ALT+SPACE) which is handled by keyDown(int, int).

This method consumes all key events, except in the following cases:

  • This field does not accept new lines (was built with TextField.NO_NEWLINE, and the ENTER key was pressed.
  • This field is not EDITABLE (exception: if in select mode, and the ENTER key was pressed).
  • The BACKSPACE key was pressed while the cursor was over the first character in the field.
  • The ESCAPE key was pressed.
  • This method attempted to insert a typed character into this field, and the insertion failed.
Overrides:
keyChar in class BasicEditField
Parameters:
key - Character generated by the event.
status - Modifier key status.
time - Number of milliseconds since the device was turned on.
Returns:
True if the event was consumed; otherwise, false.

keyDown

protected boolean keyDown(int keycode,
                          int time)
Handles symbol screen key sequences.

This method traps the ALT+SPACE key sequence, consumes the key generation event, and opens the symbol screen.

Note that, whatever key sequence is pressed, this method stores the keycode as the last key pressed, even if it doesn't handle the key press event (i.e. even if the key wasn't ALT+SPACE).

Overrides:
keyDown in class EditField
Parameters:
keycode - character generated by the event.
time - Number of milliseconds since the device was turned on.
Returns:
True if the event was consumed (ALT+SPACE was pressed); otherwise, false.

keyRepeat

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

This method behaves as follows:

  1. If there has been a roll since the last key down, do nothing.
  2. Don't handle ENTER or BACKSPACE so that they will generate a keyChar which will handle them.
  3. If the key is alphabetic, then switch its case but only once and include the effects of autocap.
  4. If no previous rule applies; don't consume this event.

Overrides:
keyRepeat in class EditField
Parameters:
keycode - Key held down.
time - Number of milliseconds since the device was turned on.
Returns:
True if the event was consumed; otherwise, false.

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)
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).

Checks whether a user moves cursor outside the boundaries of last edited word.

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

selectionDelete

public void selectionDelete()
Deletes character to the right of the cursor, or deletes selection.

Executes BasicEditField.selectionDelete().

Overrides:
selectionDelete in class BasicEditField
Since:
JDE 4.0.0

Following copied from class: TextField
See Also:
Field.isSelectionDeleteable(), Field.selectionCut(net.rim.device.api.system.Clipboard)

setText

protected void setText(String text,
                       int context)
Sets the text value for this field, with indication of the source of this action.
Overrides:
setText in class BasicEditField
Parameters:
text - New text for this field's buffer; if null, this method clears the field.
context - Information specifying the origin of the change.

update

protected void update(int delta)
Updates this field.

This field's manager invokes this method to prompt this field to update itself. When invoked, this field determines the affected region's new line lengths, adjusts the master line length array, adjusts the focus, and resizes this field (if necessary).

Overrides:
update in class BasicEditField
Parameters:
delta - Number of characters by which this field has changed, negative or positive (negative means that many characters have been added).



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.