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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.component.TextField
Direct Known Subclasses:
BasicEditField, RichTextField

public class TextField
extends Field

A simple editable text field.

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 Sym brings up the symbol screen from which the user can select a symbol. Depending on the keyboard Sym could alternatively be Alt+Space or Alt+ZX.

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+backsapce 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


Field Summary
static long CONSUME_INPUT
          Determines whether or not this field should consume all input characters; if it would normally.
static int DEFAULT_MAXCHARS
          Default maximum number of characters allowed in this field.
static int JUMP_FOCUS_AT_END
          Enables jump-to-end of field behaviour.
static long NO_COMPLEX_INPUT
          Suggests complex input (e.g.
static long NO_EDIT_MODE_INPUT
          If set, edit mode is disabled on this field
static long NO_LEARNING
          Suggests auto learning feature disable for current text component.
static long NO_NEWLINE
          Ignore newlines from user input or pasting.
static long NO_SWITCHING_INPUT
          Do not allow IM switching in this field Edit fields built with this style do not allow IM switching within this field.
 
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
TextField()
          Constructor
TextField(long style)
          Constructor
 
Method Summary
protected  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.
protected  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.
protected  void displayFieldFullMessage()
          Displays a 'field full' message.
protected  void drawFocus(Graphics graphics, boolean on)
          Draws the focus indicator for this field.
 int drawText(Graphics graphics, int offset, int length, int x, int y, DrawTextParam drawTextParam)
          Draw a run of text (aOffset, aLength) at (aX, aY) using parameters aDrawTextParam.
protected  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 getCursorPosition()
          Retrieves character offset for current cursor position in this field.
 TextFilter getFilter()
          Gets the text filter set for this field.
 void getFocusRect(XYRect rect)
          Retrieves the extent of the focus region.
 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.
 int getPreferredHeight()
          Retrieves this field's preferred height.
 int getPreferredWidth()
          Retrieves this field's preferred width.
 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.
 int getTextLength()
          Retrieves length of this field's text, not including the label.
 int insert(String text)
          Inserts string programmatically into this field.
protected  int insert(String text, int context)
          Inserts string into this field.
 boolean isPasteable()
          Determines if this field supports paste operations.
 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.
protected  boolean keyChar(char key, int status, int time)
          Traps key generation events.
protected  boolean keyControl(char key, int status, int time)
          Handles control character generation events.
protected  void layout(int width, int height)
          Lays out this field's contents.
protected  void makeContextMenu(ContextMenu contextMenu)
          Builds this field's context menu.
protected  int moveFocus(int amount, int status, int time)
          Handles moving focus within this field.
protected  void moveFocus(int x, int y, int status, int time)
          Handles moving the focus to an exact position within this field.
protected  boolean navigationClick(int status, int time)
          Mark navigationClick handled.
protected  boolean navigationUnclick(int status, int time)
          Handle navigationUnclick if navigation click handled.
protected  void onFocus(int direction)
          Positions cursor when this field first receives the focus.
protected  void paint(Graphics aGraphics)
          Redraws this field.
 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.
protected  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 setLabel(String newLabel)
          Sets this field's label.
 void setMaxSize(int maxSize)
          Sets maximum number of characters allowed for this field's value.
 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.
 String toString()
          Retrieves this field's text in a string.
protected  void update(int delta)
          Updates this edit field.
 void wipe()
          Overwrites this field's unused contents.
 
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, keyDown, keyRepeat, keyStatus, keyUp, navigationMovement, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, selectionCut, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setMuddy, setNonSpellCheckable, setPosition, setVisualState, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 



Field Detail

DEFAULT_MAXCHARS

public static final int DEFAULT_MAXCHARS
Default maximum number of characters allowed in this field. Does not include label in count.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

NO_SWITCHING_INPUT

public static final long NO_SWITCHING_INPUT
Do not allow IM switching in this field

Edit fields built with this style do not allow IM switching within this field.

See Also:
Constant Field Values
Since:
BlackBerry API 4.6.0

NO_EDIT_MODE_INPUT

public static final long NO_EDIT_MODE_INPUT
If set, edit mode is disabled on this field

See Also:
Constant Field Values
Since:
BlackBerry API 4.5.0

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 TextField.JUMP_FOCUS_AT_END style.

See Also:
Constant Field Values
Since:
BlackBerry API 4.2.1

JUMP_FOCUS_AT_END

public static final int JUMP_FOCUS_AT_END
Enables jump-to-end of field behaviour.

In fields built with this style, when rolling down out of this field the cursor first jumps to the end of the field, rather than exiting the field. Normally, focus leaves on a roll down if the cursor is already at the last character of the field.

See Also:
Constant Field Values

NO_LEARNING

public static final long NO_LEARNING
Suggests auto learning feature disable for current text component. Depending on Input method/Conversion Engine implementation this can be ignored or respected.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.2

NO_COMPLEX_INPUT

public static final long NO_COMPLEX_INPUT
Suggests complex input (e.g. Chinese ) disable for current text component. Depending on Input method/Conversion Engine implementation this can be ignored or respected.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.2

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 4.2.1


Constructor Detail

TextField

public TextField()
Constructor

Since:
BlackBerry API 5.0.0

TextField

public TextField(long style)
Constructor

Since:
BlackBerry API 5.0.0


Method Detail

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns accessible representation of the field for a screen reader

Overrides:
getAccessibleContext in class Field
Returns:
AccessibleContext instance
Since:
BlackBerry API 4.6.1

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

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

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.

Parameters:
count - Number of characters to delete.
Returns:
Number of characters actually deleted.
Since:
BlackBerry API 4.2.1

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.

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 TextField.getTextLength().
Since:
BlackBerry API 4.0.2

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

Parameters:
context - Context ID for this action.
Since:
BlackBerry API 4.2.1

wipe

public void wipe()
Overwrites this field's unused contents.

Since:
BlackBerry API 4.2.1

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 Field
See Also:
Field.isSelectionDeleteable(), Field.selectionCut(net.rim.device.api.system.Clipboard)
Since:
BlackBerry API 4.2.1

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.

Overrides:
selectionCopy in class Field
Parameters:
cb - Clipboard to contain copied text.

getLabel

public String getLabel()
Retrieves this field's label.

Returns:
This field's label, or null if this field has no label.
Since:
BlackBerry API 4.2.1

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.

Returns:
Maximum number of characters allowed in this edit field.
Since:
BlackBerry API 4.2.1

getPreferredHeight

public int getPreferredHeight()
Retrieves this field's preferred height.

Managers make use of this value during layout. Edit fields determine their preferred height based on the height of the font they're using to display their text contents.

Overrides:
getPreferredHeight in class Field
Returns:
Preferred height for this field (height of current font).
Since:
BlackBerry API 4.2.1

getPreferredWidth

public int getPreferredWidth()
Retrieves this field's preferred width.

Managers make use of this value during layout. All editable fields to be as wide as possible. Non editable fields to be layed out with as little space as possible.

Overrides:
getPreferredWidth in class Field
Returns:
Preferred width for this field.
Since:
BlackBerry API 4.2.1

getText

public String getText()
Retrieves this field's text, not including the label.

Returns:
Text value contained in this field.
Since:
BlackBerry API 4.0.2

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.

Parameters:
offset - First character to return.
length - Number of characters to return.
Returns:
Substring of this field's contents.
Since:
BlackBerry API 4.0.2

getText

public void getText(int srcBegin,
                    int srcEnd,
                    char[] dst,
                    int dstBegin)
Retrieves this field's text.

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

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.
Since:
BlackBerry API 4.2.1

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 TextField.insert(java.lang.String) or TextField.selectionDelete() are invoked.

Returns:
Underlying buffer for this field.
Since:
BlackBerry API 4.2.1

getTextLength

public int getTextLength()
Retrieves length of this field's text, not including the label.

Returns:
Number of characters in this field's text value.
Since:
BlackBerry API 4.0.2

insert

public int insert(String text)
Inserts string programmatically into this field.

This method attempts to insert your specified string 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).

Parameters:
text - String to insert.
Returns:
Number of characters successfully inserted.
Since:
BlackBerry API 4.2.1

insert

protected int insert(String text,
                     int context)
Inserts string into this field.

This method attempts to insert your specified string 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.

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 4.2.1

layout

protected void layout(int width,
                      int height)
Lays out this field's contents.

This field's manager invokes this method during the layout process to instruct this field to arrange its contents, given an amount of available space.

Specified by:
layout in class Field
Parameters:
width - Horizontal space available.
height - Vertical space available.
Since:
BlackBerry API 4.2.1

setLabel

public void setLabel(String newLabel)
Sets this field's label.

Parameters:
newLabel - New label for this field.
Since:
BlackBerry API 4.2.1

keyChar

protected 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:

Overrides:
keyChar in class Field
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 4.2.1

keyControl

protected 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 Field
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 4.2.1

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.

Parameters:
delta - Number of characters by which the field has changed, negative or positive (negative means that characters have been deleted).
Since:
BlackBerry API 4.2.1

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.

Parameters:
MaxSize - New maximum number of characters for this edit field's value.
Throws:
IllegalArgumentException - If maxNumChars is less than zero.
Since:
BlackBerry API 4.2.1

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.

Parameters:
offset - Character position to receive the cursor, counting from the first character in this field's value.
Since:
BlackBerry API 4.0.2

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

Returns:
Character position of current cursor position within this field's value.
Since:
BlackBerry API 4.0.2

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 Field
Parameters:
cb - Clipboard object holding the text scrap.
Returns:
True if this field is editable; otherwise, false.
Since:
BlackBerry API 4.2.1

setFilter

public void setFilter(TextFilter filter)
Sets the text filter for this field.

Parameters:
filter - Text filter for this field.
Since:
BlackBerry API 4.2.1

getFilter

public TextFilter getFilter()
Gets the text filter set for this field.

Returns:
the text filter set for this field if exist otherwise return null;
Since:
BlackBerry API 4.2.1

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.

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 4.2.1

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.

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 4.2.1

paint

protected void paint(Graphics aGraphics)
Redraws this field.

This field's manager invokes this method during the repainting process to instruct this field to repaint itself.

Specified by:
paint in class Field
Parameters:
graphics - Graphics context for repainting this field.
Since:
BlackBerry API 4.2.1

drawFocus

protected void drawFocus(Graphics graphics,
                         boolean on)
Draws the focus indicator for this field.

This field's manager invokes this method after painting the field, in order to overpaint the focus indicator. By default, this method simply inverts the pixels in the focus's extent.

Note that if currently selecting more than one character in this field, then the focus region occupies the entire extent of the selected text.

Overrides:
drawFocus in class Field
Parameters:
graphics - Graphics context for drawing the focus.
on - This parameter is ignored -- the focus is aways set at the location at which it is drawn.

navigationClick

protected boolean navigationClick(int status,
                                  int time)
Mark navigationClick handled.

The source of the navigation event can be determined by checking the KeypadListener.STATUS_TRACKWHEEL and KeypadListener.STATUS_FOUR_WAY bits in the status parameter; exactly one of them will be set.

Overrides:
navigationClick in class Field
Parameters:
status - Bitfield of values defined by KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Since:
BlackBerry API 4.2.0

navigationUnclick

protected boolean navigationUnclick(int status,
                                    int time)
Handle navigationUnclick if navigation click handled.

The source of the navigation event can be determined by checking the KeypadListener.STATUS_TRACKWHEEL and KeypadListener.STATUS_FOUR_WAY bits in the status parameter; exactly one of them will be set.

Overrides:
navigationUnclick in class Field
Parameters:
status - Bitfield of values defined by KeypadListener.
time - Number of milliseconds since the device was turned on.
Returns:
True if this method consumed the event; otherwise, false.
Since:
BlackBerry API 4.2.0

moveFocus

protected int moveFocus(int amount,
                        int status,
                        int time)
Handles moving focus within this field.

This field's manager invokes this method to prompt this field to handle a focus move event. If the event is an ALT-roll, then focus movement happens horizontally (character by character for trackwheel, begin/end of line for trackball); otherwise, focus movement happens vertically (line by line for trackwheel, page by page for trackball).

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.

Overrides:
moveFocus in class Field
Parameters:
amount - Number of positions to move, positive means down or forward, negative up or backwards.
status - Modifier key status.
time - Number of milliseconds since the device was turned on.
Returns:
Remaining scroll amount not used up, with the same sign.
Since:
BlackBerry API 4.0.2

moveFocus

protected void moveFocus(int x,
                         int y,
                         int status,
                         int time)
Handles moving the focus to an exact position within this field.

This field's manager invokes this method when moving the focus to an exact position within this field, and only when this field already has the focus.

Overrides:
moveFocus in class Field
Parameters:
x - Distance from left edge of this field for new focus position.
y - Distance from top edge of this field for new focus position.
status - Modifier key status.
time - Number of milliseconds since the device was turned on.

onFocus

protected void onFocus(int direction)
Positions cursor when this field first receives the focus.

Text fields exhibit special behaviour for onFocus.

If no cursor position was currently set... If the focus entered this field from the "top", then this method places the initial cursor at the first character in this field's value.

If the focus entered this field from the "bottom", then this method places the initial cursor on the last character in this field's value.

If the focus event indicated no direction, this method does nothing.

If the cursor position was already set... If the cursor position was preivously set externally (ie through a call to TextField.setCursorPosition(int), then the cursor is rendered at the set position. However, this state is erased once the control gains focus.

Overrides:
onFocus in class Field
Parameters:
direction - Direction of cursor movement; greater than zero means it came from above this field, less than zero means it came from below this field, zero means focus is being set to the field directly (that is, not by means of a trackwhell roll).

isSelecting

public final boolean isSelecting()
Determines if this field is currently selecting text.

Overrides:
isSelecting in class Field
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)

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 Field
Returns:
True if this field supports the selection of text; otherwise, false.

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 Field
Parameters:
enable - True to enable selecting mode; false to disable it.

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 Field
Returns:
True if this field currently has a selection.

isSelectionDeleteable

public boolean isSelectionDeleteable()
Determines if this field supports cut operations.

Overrides:
isSelectionDeleteable in class Field
Returns:
True if this field supports cut; otherwise, false.

isPasteable

public boolean isPasteable()
Determines if this field supports paste operations.

Overrides:
isPasteable in class Field
Returns:
True if this field is Field.EDITABLE; otherwise, false.

getFocusRect

public void getFocusRect(XYRect rect)
Retrieves the extent of the focus region.

The framework invokes this method to retrieve this field's current focus region.

Overrides:
getFocusRect in class Field
Parameters:
rect - To contain the focus extent for this field, in local coordinates.

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.

Returns:
true if this field supports the symbol screen; false if it does not.
Since:
BlackBerry API 4.2.1

displayFieldFullMessage

protected void displayFieldFullMessage()
Displays a 'field full' message.

Since:
BlackBerry API 4.2.1

setCursorPosition

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

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.

toString

public String toString()
Retrieves this field's text in a string.

Overrides:
toString in class Object
Returns:
String containing this field's text.

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

Returns:
True if this method successfully removed a character or selection; otherwise, false.
Since:
BlackBerry API 4.2.1

backspace

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

Parameters:
count - Number of characters to delete.
context - Information specifying the origin of the change.
Returns:
Number of characters actually deleted.
Since:
BlackBerry API 4.2.1

drawText

public int drawText(Graphics graphics,
                    int offset,
                    int length,
                    int x,
                    int y,
                    DrawTextParam drawTextParam)
Draw a run of text (aOffset, aLength) at (aX, aY) using parameters aDrawTextParam. May be overridden by derived classes to provide special behaviour - highly discouraged, use AttributedString instead (due to open in 4.2.2).

Parameters:
graphics - context for repainting this field.
offset - Offset of the line being drawn (Offset of first character being drawn is offset+drawTextParam.getStartOffset())
length - Length of the line being drawn (Offset of over-the-last character being drawn is offset+drawTextParam.getEndOffset())
x - Horizontal position of drawing anchor.
y - Vertical position of drawing anchor.
drawTextParam - Text drawing parameters.If null use default parameters
Returns:
The advance of the text in pixels. Normal implementation of text components returns 0, meaning that advance should be taken from run attributes. However, legacy inheriting components may override this method to return value different from 0, in which case it will be taken into account.
Since:
BlackBerry API 4.2.1

fieldChangeNotify

protected 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 Field
Parameters:
context - Information specifying the origin of the change.
Since:
BlackBerry API 4.3.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 Field
Parameters:
contextMenu - Context menu to build.
See Also:
ContextMenu
Since:
BlackBerry API 4.2.1

setFont

public void setFont(Font font)
Sets the font for this field and updates the display if necessary.

Overrides:
setFont in class Field
Parameters:
font - New font for this field.
Since:
BlackBerry API 4.2.1





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.