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:

IComponent, InputMethodListener, InputMethodRequests

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 the most recent autotext expansion reverses all effects of the autotext substitution.

Field Summary

Fields inherited from class net.rim.device.api.ui.component.BasicEditField

DEFAULT_MAXCHARS, FILTER_DEFAULT, FILTER_EMAIL, FILTER_HEXADECIMAL, FILTER_INTEGER, FILTER_LOWERCASE, FILTER_NUMERIC, FILTER_PHONE, FILTER_UPPERCASE, FILTER_URL, JUMP_FOCUS_AT_END, NO_NEWLINE

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

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

Constructor Summary

AutoTextEditField()
Constructs a default AutoTextEditField.

AutoTextEditField(String label, String initialValue)
Constructs an AutoTextEditField object.

AutoTextEditField(String label, String initialValue, int maxNumChars, long style)
Constructs a smaller AutoTextEditField object, 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.
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.
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, getFocusRect, getLabel, getLabelLength, getMaxSize, getPreferredHeight, getPreferredWidth, getText, getText, getTextAbstractString, getTextLength, insert, insert, isPasteable, isSelectable, isSelecting, isSelectionCopyable, isSelectionDeleteable, isSymbolScreenAllowed, keyControl, layout, makeContextMenu, moveFocus, onFocus, onUnfocus, onVisibilityChange, paint, paste, select, selectionCopy, selectionDelete, setCursorPosition, setCursorPosition, setFilter, setFont, setLabel, setMaxSize, setText, toString

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

drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getWidth, invalidate, invalidate, isDirty, isEditable, isFocusable, isMuddy, isSelectionCutable, isVisible, keyStatus, keyUp, selectionCut, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setMuddy, setPosition, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

Constructor Detail

AutoTextEditField

public AutoTextEditField()

Constructs a default AutoTextEditField. It has no label and no initial text.

AutoTextEditField

public AutoTextEditField(String label,
                         String initialValue)

Constructs an AutoTextEditField object.

This method builds an editable autotext field that can hold up to BasicEditField.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 smaller AutoTextEditField object, 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.

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 BasicEditField

Parameters:

key - Character to insert.

Returns:

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

Since:

JDE 3.7.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 BasicEditField.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 - Ticks since device reset.

Returns:

True if the event was consumed; otherwise, false.

Since:

JDE 3.7.0

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 - Ticks since device reset.

Returns:

True if the event was consumed (ALT+SPACE was pressed); otherwise, false.

Since:

JDE 3.7.0

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 - Ticks since device reset.

Returns:

True if the event was consumed; otherwise, false.

Since:

JDE 3.7.0

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.

If a key is being held down while the user rolls the track wheel, and that key supports rolling character selection, then this method does not move the focus but instead uses the move amount to do rolling character selection. In this case, the method always consumes the entire roll amount and returns zero.

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 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 - Ticks since device reset.

Returns:

An integer representing the remaining scroll amount, or zero if this method trapped a rolling character selection event.

Since:

JDE 3.7.0

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.

Since:

JDE 3.7.0

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

Since:

JDE 3.7.0