net.rim.device.api.input
Class InputHelperBase

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.component.TextFieldBase
          net.rim.device.api.input.InputHelperBase

All Implemented Interfaces:

ITextInputStyle

Direct Known Subclasses:

InputHelper

public class InputHelperBase
extends TextFieldBase

Provides text input features and functionality of the input framework for Screen and Field classes

Since:

BlackBerry API 6.0.0

Field Summary
static long	CONSUME_INPUT Determines whether or not this field should consume all input characters; if it would normally.
static long	NO_NEWLINE Ignore newlines from user input or pasting.

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

InputHelperBase()
Constructs an InputHelperBase instance.

InputHelperBase(long inputStyle)
Constructs an InputHelperBase instance.

InputHelperBase(Screen scr)
Constructs an InputHelperBase instance.

InputHelperBase(Screen scr, long inputStyle)
Constructs an InputHelperBase instance with specified input style.

Method Summary
boolean	backspace() Deletes character to the left of the cursor, or deletes selection.
int	backspace(int count) Deletes specified number of characters to the left of the cursor.
int	backspace(int count, int context) Deletes specified number of characters to the left of the cursor, with indication of source of this action.
char	charAt(int offset) Retrieves the character at the specified offset.
void	clear(int context) Clears this field's contents.
void	displayFieldFullMessage() Displays a 'field full' message.
void	fieldChangeNotify(int context) Invoked for this field when a change event occurs.
AccessibleContext	getAccessibleContext() Returns accessible representation of the field for a screen reader
int	getAnchorPosition()
Screen	getAssociatedScreen() Gets a screen associated with this helper.
int	getCaretPosition()
static StringBuffer	getCharVariants(int keycode) Gets character variants (including umlauts) mapped to the keycode, depending on the device model, current input method, (virtual) keyboard layout, etc.
int	getCursorPosition() Retrieves character offset for current cursor position in this field.
TextFilter	getFilter() Gets the text filter set for this field.
String	getLabel() Retrieves this field's label.
int	getLabelLength() Retrieves the length of this field's label The length returned includes any additional character appended for layout purposes.
int	getMaxSize() Retrieves the maximum number of characters allowed for this field's value.
String	getText() Retrieves this field's text, not including the label.
String	getText(int offset, int length) Retrieves a portion of this field's text.
void	getText(int srcBegin, int srcEnd, char[] dst, int dstBegin) Retrieves this field's text.
AbstractString	getTextAbstractString() Retrieves read-only handle to the underlying buffer.
ITextInputConnector	getTextInputConnector() Retrieves the currently registered requests listener.
int	getTextLength() Retrieves length of this field's text, not including the label.
int	insert(String text) Inserts string programmatically into this field.
int	insert(String text, int context) Inserts string into this field.
boolean	isFocusable() States whether or not this helper accepts the focus.
boolean	isPasteable() Determines if this field supports paste operations.
boolean	isScreenInput() Checks if the helper is in screen input mode.
boolean	isSelectable() Determines if this field supports selection of text.
boolean	isSelecting() Determines if this field is currently selecting text.
boolean	isSelectionCopyable() Determines if this field supports copy operations.
boolean	isSelectionDeleteable() Determines if this field supports cut operations.
protected boolean	isSymbolScreenAllowed() Determines if this field supports use of the symbol screen.
boolean	keyChar(char key, int status, int time) Traps key generation events.
boolean	keyControl(char key, int status, int time) Handles control character generation events.
protected void	makeContextMenu(ContextMenu contextMenu) Builds this field's context menu.
boolean	paste(Clipboard cb) Pastes text scrap into this field.
void	select(boolean enable) Enables or disables selection mode.
void	selectionCopy(Clipboard cb) Copies the current selection to the clipboard.
void	selectionDelete() Deletes character to the right of the cursor, or deletes selection.
void	setCursorPosition(int offset) Places cursor on specific character within this field, at user request.
void	setCursorPosition(int offset, int context) Places cursor on specific character within this field.
void	setFilter(TextFilter filter) Sets the text filter for this field.
void	setFont(Font font) Sets the font for this field and updates the display if necessary.
void	setInputStyle(long style) Sets text style for this helper's content.
void	setLabel(String newLabel) Sets this field's label.
void	setLookupPosition(int x, int y, int widthOfText, int heightOfText) If ITextInputConnector listener is not registered with the helper then this method sets desirable (constant) position of the helper's lookup screen.
void	setMIDPDisplayable(Displayable displayable) Associates the specified instance of MIDP Displayable with this helper, to dispatch input events to.
void	setMaxSize(int maxSize) Sets maximum number of characters allowed for this field's value.
boolean	setScreenInput(boolean screenInputMode) Sets this helper into 'screen input mode' or 'non-screen input mode'.
void	setSelection(int aNewCursor, boolean aNewCursorLeadingEdge, int aNewAnchor) Set the selection.
void	setText(String text) Sets the text value for this field.
protected void	setText(String text, int context) Sets the text value for this field, with indication of the source of this action.
void	setTextInputConnector(ITextInputConnector listener) Registers an input framework request handler defined by a third party, with the InputHelperBase instance.
protected void	update(int delta) Updates this edit field.
protected void	update(int aStart, int aLength, int aNewLength, int aCursorOffset, boolean aMoveCursor, boolean aIsInsertionOrDeletion) The update() method is called by the input framework when text or attributes change.
void	wipe() Overwrites this field's unused contents.

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

cursorClick, cursorUnclick, drawFocus, drawHighlightRegion, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isLeftToRight, isMuddy, isScrollCopyable, isSelectionCutable, isSpellCheckable, isStyle, isVisible, keyDown, keyRepeat, keyStatus, keyUp, layout, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paint, 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, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout

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, getTextInputStyle, isEditable, isUnicodeInputAllowed, updateInputStyle

Field Detail

CONSUME_INPUT

public static final long CONSUME_INPUT

Determines whether or not this field should consume all input characters; if it would normally.

Useful for fields that have Field.READONLY style set.

Modified value due to conflict with #JUMP_FOCUS_AT_END style.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

NO_NEWLINE

public static final long NO_NEWLINE

Ignore newlines from user input or pasting.

Edit fields built with this style ignore newlines entered via cut and paste functionality and the keyboard. Labels can have newlines, but this field will strip newlines out of initial field values.

See Also:

Constant Field Values

Since:

BlackBerry API 6.0.0

Constructor Detail

InputHelperBase

public InputHelperBase()

Constructs an InputHelperBase instance.

Since:

BlackBerry API 6.0.0

InputHelperBase

public InputHelperBase(long inputStyle)

Constructs an InputHelperBase instance.

Parameters:

inputStyle - Combination of field style bits to specify display and filter attributes, e.g. BasicEditField.FILTER_NUMERIC, Field.EDITABLE, Field.FOCUSABLE.

Since:

BlackBerry API 6.0.0

InputHelperBase

public InputHelperBase(Screen scr)

Constructs an InputHelperBase instance.

Parameters:

scr - Screen instance associated with this helper.

Since:

BlackBerry API 6.0.0

InputHelperBase

public InputHelperBase(Screen scr,
                       long inputStyle)

Constructs an InputHelperBase instance with specified input style.

Parameters:

scr - Associated with this helper Screen instance

inputStyle - Combination of field style bits to specify display and filter attributes, e.g. BasicEditField.FILTER_NUMERIC, Field.EDITABLE, Field.FOCUSABLE.

Since:

BlackBerry API 6.0.0

Method Detail

getCaretPosition

public int getCaretPosition()

Overrides:

getCaretPosition in class TextFieldBase

See Also:

InputMethodRequest#getCaretPosition

Since:

BlackBerry API 6.0.0

getAnchorPosition

public int getAnchorPosition()

Overrides:

getAnchorPosition in class TextFieldBase

See Also:

InputMethodRequest#getAnchorPosition

Since:

BlackBerry API 6.0.0

getLabelLength

public int getLabelLength()

Retrieves the length of this field's label

The length returned includes any additional character appended for layout purposes. Therefore the value may not be the same as #getLabel().length()

Overrides:

getLabelLength in class TextFieldBase

Returns:

Length of this field's label string and any additional layout character.

Since:

BlackBerry API 6.0.0

backspace

public int backspace(int count)

Deletes specified number of characters to the left of the cursor.

This method ignores the current selection and deletes a number of characters to the left of the current cursor position. If this method runs into the beginning of this field's editable value, it deletes as many characters as possible.

Overrides:

backspace in class TextFieldBase

Parameters:

count - Number of characters to delete.

Returns:

Number of characters actually deleted.

Since:

BlackBerry API 6.0.0

charAt

public char charAt(int offset)

Retrieves the character at the specified offset.

Index zero is the first character position after this field's label.

Overrides:

charAt in class TextFieldBase

Parameters:

offset - Index of the character to retrieve.

Returns:

Character at your specified offset.

Throws:

IndexOutOfBoundsException - if offset is less than zero, or greater than or equal to the value returned from InputHelperBase.getTextLength().

Since:

BlackBerry API 6.0.0

clear

public void clear(int context)

Clears this field's contents.

Override this method if you want the default text to be non empty when the field is cleared. For example, a URLEditField might call setText("http://", context).

Overrides:

clear in class TextFieldBase

Parameters:

context - Context ID for this action.

Since:

BlackBerry API 6.0.0

wipe

public void wipe()

Overwrites this field's unused contents.

Overrides:

wipe in class TextFieldBase

Since:

BlackBerry API 6.0.0

selectionDelete

public void selectionDelete()

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

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

If no characters are selected, this method deletes the character immediately to the right of the cursor. If the cursor is currently on the last character in the field, this method does nothing.

Overrides:

selectionDelete in class TextFieldBase

See Also:

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

Since:

BlackBerry API 6.0.0

selectionCopy

public void selectionCopy(Clipboard cb)

Copies the current selection to the clipboard.

Note that this method always succeeds, even if zero characters are copied onto the clipboard. If at least one character exists in the selection to copy, then this method overwrites the clipboard's previous contents. If there is no selection, then this method clears the contents of the clipboard.

Overrides:

selectionCopy in class TextFieldBase

Parameters:

cb - Clipboard to contain copied text.

Throws:

NullPointerException - if cb is null.

Since:

BlackBerry API 6.0.0

getLabel

public String getLabel()

Retrieves this field's label.

Overrides:

getLabel in class TextFieldBase

Returns:

This field's label, or null if this field has no label.

Since:

BlackBerry API 6.0.0

getMaxSize

public int getMaxSize()

Retrieves the maximum number of characters allowed for this field's value.

This method does not include this field's label as part of its accounting.

Overrides:

getMaxSize in class TextFieldBase

Returns:

Maximum number of characters allowed in this edit field.

Since:

BlackBerry API 6.0.0

getText

public String getText()

Retrieves this field's text, not including the label.

Overrides:

getText in class TextFieldBase

Returns:

Text value contained in this field.

Since:

BlackBerry API 6.0.0

getText

public String getText(int offset,
                      int length)

Retrieves a portion of this field's text.

Provide a character offset and length to retrieve a substring of this field's contents.

Note: This method includes the label in the field's contents, so if you pass in an offset of zero, the first character returned is the first character of the label.

Note: Different system themes may modify the contents of the label.

Overrides:

getText in class TextFieldBase

Parameters:

offset - First character to return.

length - Number of characters to return.

Returns:

Substring of this field's contents.

Since:

BlackBerry API 6.0.0

getText

public void getText(int srcBegin,
                    int srcEnd,
                    char[] dst,
                    int dstBegin)

Retrieves this field's text.

This method adjusts for the label in the field's contents, so the srcBegin and srcEnd parameters describe the field's actual contents.

When srcEnd is a negative value, or srcBegin is greater than srcEnd, this method leaves dst as is and does not throw an exception.

Overrides:

getText in class TextFieldBase

Parameters:

srcBegin - First character in source to retrieve.

srcEnd - Last character in source to retrieve.

dst - Character buffer to contain retrieved text.

dstBegin - Offset into buffer to receive the first retrieved character.

Throws:

ArrayIndexOutOfBoundsException - if one of the following is true:

• srcBegin or dstBegin is negative
• srcEnd is greater than the length of this field's text
• the length of dst is less than (srcEnd - srcBegin + 1)
• dstBegin is greater than the last index of dst

NullPointerException - if dst is null.

Since:

BlackBerry API 6.0.0

getTextAbstractString

public AbstractString getTextAbstractString()

Retrieves read-only handle to the underlying buffer.

Note: The underlying buffer can be modified by this field if methods such as InputHelperBase.insert(java.lang.String) or InputHelperBase.selectionDelete() are invoked.

Overrides:

getTextAbstractString in class TextFieldBase

Returns:

Underlying buffer for this field.

Since:

BlackBerry API 6.0.0

getTextLength

public int getTextLength()

Retrieves length of this field's text, not including the label.

Overrides:

getTextLength in class TextFieldBase

Returns:

Number of characters in this field's text value.

Since:

BlackBerry API 6.0.0

insert

public int insert(String text)

Inserts string programmatically into this field.

This method attempts to insert your specified string at the current 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 characters as possible are inserted.

Note: use this method for programmatic changes to this field; be default, this method simply invokes insert(yourString, FieldChangeListener.PROGRAMMATIC).

Overrides:

insert in class TextFieldBase

Parameters:

text - String to insert.

Returns:

Number of characters successfully inserted.

Since:

BlackBerry API 6.0.0

insert

public int insert(String text,
                  int context)

Inserts string into this field.

This method attempts to insert your specified string at the current 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 characters as possible are inserted.

Overrides:

insert in class TextFieldBase

Parameters:

text - String to insert.

context - Information specifying the origin of the change. false indicates user-initiated insertion.

Returns:

Number of characters successfully inserted.

Since:

BlackBerry API 6.0.0

setLabel

public void setLabel(String newLabel)

Sets this field's label.

Overrides:

setLabel in class TextFieldBase

Parameters:

newLabel - New label for this field.

Since:

BlackBerry API 6.0.0

update

protected void update(int delta)

Updates this edit field.

This field invokes this method when text is inserted or deleted so this field can update itself.

Overrides:

update in class TextFieldBase

Parameters:

delta - Number of characters by which the field has changed, negative or positive (negative means that characters have been deleted).

Since:

BlackBerry API 6.0.0

setMaxSize

public void setMaxSize(int maxSize)

Sets maximum number of characters allowed for this field's value.

If this field currently holds more than your provided number, this method truncates this field's contents to fit.

This method does not include the label in its accounting.

Overrides:

setMaxSize in class TextFieldBase

Parameters:

maxSize - New maximum number of characters for this edit field's value.

Throws:

IllegalArgumentException - If maxNumChars is less than zero.

Since:

BlackBerry API 6.0.0

setCursorPosition

public void setCursorPosition(int offset)

Places cursor on specific character within this field, at user request.

This method does not include the label as part of its accounting (that is, an offset of zero represents the first character in this field's text value).

This method assumes the repositioning request was user-initiated.

Overrides:

setCursorPosition in class TextFieldBase

Parameters:

offset - Character position to receive the cursor, counting from the first character in this field's value.

Since:

BlackBerry API 6.0.0

getCursorPosition

public int getCursorPosition()

Retrieves character offset for current cursor position in this field.

This method does not include the label as part of its accounting (that is, a returned offset of zero means that the cursor is currently sitting on the first character in this field's value).

Overrides:

getCursorPosition in class TextFieldBase

Returns:

Character position of current cursor position within this field's value.

Since:

BlackBerry API 6.0.0

paste

public boolean paste(Clipboard cb)

Pastes text scrap into this field.

If this field is EDITABLE, this method pastes the scrap currently on the clipboard after the current cursor position.

This method attempts to insert as many characters as it can into this field. If this field's capacity is reached before all characters are pasted, then only those that fit are pasted.

If this field currently has some text selected, this method replaces the selection with the scrap from the clipboard.

Overrides:

paste in class TextFieldBase

Parameters:

cb - Clipboard object holding the text scrap.

Returns:

True if this field is editable; otherwise, false.

Since:

BlackBerry API 6.0.0

setFilter

public void setFilter(TextFilter filter)

Sets the text filter for this field.

Overrides:

setFilter in class TextFieldBase

Parameters:

filter - Text filter for this field.

Since:

BlackBerry API 6.0.0

getFilter

public TextFilter getFilter()

Gets the text filter set for this field.

Specified by:

getFilter in interface ITextInputStyle

Overrides:

getFilter in class TextFieldBase

Returns:

the text filter set for this field if exist otherwise return null;

Since:

BlackBerry API 6.0.0

setText

public void setText(String text)
             throws IllegalArgumentException

Sets the text value for this field. The current text in the field is REPLACED by text.

Overrides:

setText in class TextFieldBase

Parameters:

text - New string value for this field; if null, this method clears the field.

Throws:

IllegalArgumentException - If the text cannot be entered into an edit field.

Since:

BlackBerry API 6.0.0

setText

protected void setText(String text,
                       int context)
                throws IllegalArgumentException

Sets the text value for this field, with indication of the source of this action.

Overrides:

setText in class TextFieldBase

Parameters:

text - New string value for this field; if null, this method clears the field.

context - Information specifying the origin of the change.

Throws:

IllegalArgumentException - If the text cannot be entered into an edit field.

Since:

BlackBerry API 6.0.0

setSelection

public void setSelection(int aNewCursor,
                         boolean aNewCursorLeadingEdge,
                         int aNewAnchor)

Set the selection.

Overrides:

setSelection in class TextFieldBase

Parameters:

aNewCursor - New cursor position.

aNewCursorLeadingEdge - True if the cursor is at the leading edge of the character.

aNewAnchor - New anchor position.

Since:

BlackBerry API 6.0.0

update

protected void update(int aStart,
                      int aLength,
                      int aNewLength,
                      int aCursorOffset,
                      boolean aMoveCursor,
                      boolean aIsInsertionOrDeletion)

The update() method is called by the input framework when text or attributes change. The update() method can be overridden in derived classes to format and layout the new text.

Text starting at aStart, of length aLength, has just been replaced by text of aNewLength.

Overrides:

update in class TextFieldBase

Parameters:

aStart - A position in the text where the update starts.

aLength - Length of the text chunk has been updated.

aNewLength - Length of the new text chunk that replaced old text chunk.

aCursorOffset - indicates cursor offset from aStart (may be non-zero in composed text).

aMoveCursor - if true, cursor and anchor are moved accordingly

aIsInsertionOrDeletion - if true, insertion or deletion of text occurred, as the opposite to attribute change

Since:

BlackBerry API 6.0.0

isSelecting

public final boolean isSelecting()

Determines if this field is currently selecting text.

Overrides:

isSelecting in class TextFieldBase

Returns:

True if this field currently is in select mode (i.e. rolling the trackwheel expands or contracts the extent of the currently selected text).

See Also:

Field.select(boolean)

Since:

BlackBerry API 6.0.0

isSelectable

public boolean isSelectable()

Determines if this field supports selection of text.

This method returns true as long as this field contains at least one character.

Overrides:

isSelectable in class TextFieldBase

Returns:

True if this field supports the selection of text; otherwise, false.

Since:

BlackBerry API 6.0.0

select

public void select(boolean enable)

Enables or disables selection mode.

Invoking this method to false sets the current selection to zero characters, and turns off the behaviour of increasing the selection with cursor movement.

Overrides:

select in class TextFieldBase

Parameters:

enable - True to enable selecting mode; false to disable it.

Since:

BlackBerry API 6.0.0

isSelectionCopyable

public boolean isSelectionCopyable()

Determines if this field supports copy operations.

This method returns true if there is currently a selection (fields that can select text always have a selection, even if it's zero characters in size).

Overrides:

isSelectionCopyable in class TextFieldBase

Returns:

True if this field currently has a selection.

Since:

BlackBerry API 6.0.0

isSelectionDeleteable

public boolean isSelectionDeleteable()

Determines if this field supports cut operations.

Overrides:

isSelectionDeleteable in class TextFieldBase

Returns:

True if this field supports cut; otherwise, false.

Since:

BlackBerry API 6.0.0

isPasteable

public boolean isPasteable()

Determines if this field supports paste operations.

Overrides:

isPasteable in class TextFieldBase

Returns:

True if this field is Field.EDITABLE; otherwise, false.

Since:

BlackBerry API 6.0.0

isSymbolScreenAllowed

protected boolean isSymbolScreenAllowed()

Determines if this field supports use of the symbol screen.

Use this method to determine if this field supports the symbol screen (all edit fields do by default). The user can press ALT+SPACE to show the symbol screen.

Subclasses may override this method to return different values depending on if they want the symbol screen to be allowed.

The implementation in this class unconditionally returns true.

Overrides:

isSymbolScreenAllowed in class TextFieldBase

Returns:

true if this field supports the symbol screen; false if it does not.

Since:

BlackBerry API 6.0.0

displayFieldFullMessage

public void displayFieldFullMessage()

Displays a 'field full' message.

Overrides:

displayFieldFullMessage in class TextFieldBase

Since:

BlackBerry API 6.0.0

setCursorPosition

public void setCursorPosition(int offset,
                              int context)

Places cursor on specific character within this field.

This method does not include the label as part of its accounting (that is, an offset of zero represents the first character in this field's text value).

Overrides:

setCursorPosition in class TextFieldBase

Parameters:

offset - Character position to receive the cursor, counting from the first character in this field's value.

context - Information specifying the origin of the change.

Since:

BlackBerry API 6.0.0

backspace

public 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 are 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.

Overrides:

backspace in class TextFieldBase

Returns:

True if this method successfully removed a character or selection; otherwise, false.

Since:

BlackBerry API 6.0.0

backspace

public int backspace(int count,
                     int context)

Deletes specified number of characters to the left of the cursor, with indication of source of this action.

This method ignores the current selection and deletes a number of characters to the left of the current cursor position. If this method runs into the beginning of this field's editable value, it deletes as many characters as possible.

You can specify whether this method was invoked programmatically, or as an event prompted by the user.

Overrides:

backspace in class TextFieldBase

Parameters:

count - Number of characters to delete.

context - Information specifying the origin of the change.

Returns:

Number of characters actually deleted.

Since:

BlackBerry API 6.0.0

fieldChangeNotify

public void fieldChangeNotify(int context)

Invoked for this field when a change event occurs.

Custom fields should call this function when their state changes.

The dirty state is cleared if the change was programmatic, and is set (dirtied) if the change was user driven.

Overrides:

fieldChangeNotify in class TextFieldBase

Parameters:

context - Information specifying the origin of the change.

Since:

BlackBerry API 6.0.0

makeContextMenu

protected void makeContextMenu(ContextMenu contextMenu)

Builds this field's context menu.

Field.getContextMenu() invokes this method to construct this field's context menu.

This method populates the context menu with cut, copy, paste, and clear selection entries, if appropriate (i.e., the field is Field.EDITABLE).

Overrides:

makeContextMenu in class TextFieldBase

Parameters:

contextMenu - The context menu to build.

See Also:

ContextMenu

Since:

BlackBerry API 6.0.0

setFont

public void setFont(Font font)

Sets the font for this field and updates the display if necessary.

Overrides:

setFont in class TextFieldBase

Parameters:

font - New font for this field.

Since:

BlackBerry API 6.0.0

getAccessibleContext

public AccessibleContext getAccessibleContext()

Description copied from class: TextFieldBase

Returns accessible representation of the field for a screen reader

Overrides:

getAccessibleContext in class TextFieldBase

Returns:

AccessibleContext instance

See Also:

Field.getAccessibleContext()

Since:

BlackBerry API 6.0.0

setMIDPDisplayable

public void setMIDPDisplayable(Displayable displayable)

Associates the specified instance of MIDP Displayable with this helper, to dispatch input events to. The instance of MIDP Displayable can be MIDP Canvas, or one of subclasses of MIDP Screen: Alert, Form, List, or TextBox.

Parameters:

displayable - The MIDP Displayable instance to be associated with this helper.

Since:

BlackBerry API 6.0.0

setInputStyle

public void setInputStyle(long style)

Sets text style for this helper's content.

Parameters:

style - Combination of field style bits to specify display and filter attributes, e.g. BasicEditField.FILTER_NUMERIC, Field.EDITABLE, Field.FOCUSABLE.

Since:

BlackBerry API 6.0.0

keyChar

public boolean keyChar(char key,
                       int status,
                       int time)

Traps key generation events.

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

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

• This field does not accept new lines (was built with InputHelperBase.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.

Overrides:

keyChar in class TextFieldBase

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.

Since:

BlackBerry API 6.0.0

keyControl

public boolean keyControl(char key,
                          int status,
                          int time)

Handles control character generation events.

This field's manager invokes this method to send this field a control character event.

Overrides:

keyControl in class TextFieldBase

Parameters:

key - Character generated.

status - Modifier key status. See KeypadListener.

time - Number of milliseconds since the device was turned on.

Returns:

True if this method consumed the event; otherwise, false.

Since:

BlackBerry API 6.0.0

isFocusable

public boolean isFocusable()

States whether or not this helper accepts the focus.

Overrides:

isFocusable in class Field

Returns:

True if the help accepts focus, otherwise false.

Since:

BlackBerry API 6.0.0

getAssociatedScreen

public Screen getAssociatedScreen()

Gets a screen associated with this helper.

Overrides:

getAssociatedScreen in class TextFieldBase

Returns:

An associated Screen.

Since:

BlackBerry API 6.0.0

isScreenInput

public boolean isScreenInput()

Checks if the helper is in screen input mode.

Being in screen input mode means that input events are dispatched to this helper that uses TID service to process the input events.

Not being in screen input mode means that input events are dispatched to a component if any has been added to a container (e.g. Screen) associated with this helper and has been given the focus.

If no component was added to the container then the helper cannot be switched to non-screen input mode.

In order to switch between screen input mode and non-screen input mode, an application have to call setScreenInput() method directly. Adding a component to the container does not guarantee automatic switch of the helper to non-screen input mode.

Returns:

True if the helper is in screen input mode, otherwise false.

Since:

BlackBerry API 6.0.0

setScreenInput

public boolean setScreenInput(boolean screenInputMode)

Sets this helper into 'screen input mode' or 'non-screen input mode'. The 'screen input mode' means that the helper has the focus, receives input method events from the TID framework, and lets an application screen class use them. The 'non-screen input mode' means that the application screen's field-with-focus has the focus, receives input method events from the TID framework, and uses them internally.

Parameters:

screenInputMode - True to set screen input mode; false to set non-screen input mode.

Returns:

True if the desired mode was set successfully for this helper; otherwise false.

Throws:

IllegalStateException - if there is no screen associated with this helper.

Since:

BlackBerry API 6.0.0

getCharVariants

public static StringBuffer getCharVariants(int keycode)

Gets character variants (including umlauts) mapped to the keycode, depending on the device model, current input method, (virtual) keyboard layout, etc.

Parameters:

keycode - A keycode.

Returns:

Character variants for the keycode.

Since:

BlackBerry API 6.0.0

getTextInputConnector

public ITextInputConnector getTextInputConnector()

Retrieves the currently registered requests listener.

Since:

BlackBerry API 6.0.0

setTextInputConnector

public void setTextInputConnector(ITextInputConnector listener)

Registers an input framework request handler defined by a third party, with the InputHelperBase instance. The handler is to provide the input framework with information about the typed text, e.g. the text location, so that the input framework will know where to display lookup popup, etc.

Parameters:

requestsListener - Input framework request handler.

Throws:

IllegalStateException - if there is already a listener registered and listener is not null.

Since:

BlackBerry API 6.0.0

setLookupPosition

public void setLookupPosition(int x,
                              int y,
                              int widthOfText,
                              int heightOfText)

If ITextInputConnector listener is not registered with the helper then this method sets desirable (constant) position of the helper's lookup screen. TID framework decides on exact position of the lookup.

Specifies a rectangle (x,y,w,h) where text is placed in the application screen. The lookup is to be positioned nearby.

Parameters:

x - X position of a text.

y - Y position of a text.

widthOfText - width of text.

heightOfText - height of text.

See Also:

IInputLocationRequests.getTextLocation(net.rim.device.api.im.TextHitInfo, net.rim.device.api.ui.XYRect)

Since:

BlackBerry API 6.0.0