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:

ITextInputStyle

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, 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

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, getAccessibleContext, 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, touchEvent

Methods inherited from class net.rim.device.api.ui.Field

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, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isScrollCopyable, isSelectionCutable, isSpellCheckable, isStyle, isVisible, keyStatus, 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, 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

Field Detail

AUTOREPLACE_OFF

public static final long AUTOREPLACE_OFF

Do no autotext substitution on this field.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

AUTOCAP_OFF

public static final long AUTOCAP_OFF

Do no automatic capitalization based on preceding punctuation.

See Also:

Constant Field Values

Since:

BlackBerry API 4.3.0

AUTOPERIOD_OFF

public static final long AUTOPERIOD_OFF

Do no automatic period insertion after two spaces.

See Also:

Constant Field Values

Since:

BlackBerry API 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 TextField.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.

status - Modifier key status.

Returns:

True if this field accepted your character (or the resulting replacement text); otherwise, false.

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

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

selectionDelete

public void selectionDelete()

Deletes character to the right of the cursor, or deletes selection.

Executes BasicEditField.selectionDelete().

Overrides:

selectionDelete in class BasicEditField

See Also:

TextField.isSelectionDeleteable(), Field.selectionCut(net.rim.device.api.system.Clipboard)

Since:

BlackBerry API 4.0.0

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:

BlackBerry API 4.0.0