|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
|
+--net.rim.device.api.ui.Field
|
+--net.rim.device.api.ui.component.TextFieldBase
Provides fundamental text input functionality for components (via inheritance) and containers (via InputHelper class), delivering InputMethod services and AttributedString features.
Implements abstract lightweight text component behaviour, providing (1) input method event handling and (2) attributed text processing.
Unlike TextField class, TextFieldBase doesn't provide: Artic's text formatting, text content laying-out, painting and focus handling.
It is the base class for InputHelper class hierarchy. It was branched out from TextField class to be also the base class for TextField in the nearest future.
| 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. |
|
| 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. |
|
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. |
|
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 |
isSelectable()
Determines if this field supports selection of text. |
|
boolean |
isSelecting()
Determines if this field is currently selecting text. |
|
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. |
|
protected boolean |
keyControl(char key,
int status,
int time)
Handles control character generation events. |
|
boolean |
paste(Clipboard cb)
Pastes text scrap into this field. |
|
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 |
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. |
|
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 java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final long CONSUME_INPUT
Useful for fields that have Field.READONLY style set.
Modified value due to conflict with #JUMP_FOCUS_AT_END style.
public static final long NO_NEWLINE
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.
| Method Detail |
public boolean backspace()
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.
public int backspace(int count)
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.
count - Number of characters to delete.
public int backspace(int count,
int context)
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.
count - Number of characters to delete.context - Information specifying the origin of the change.public char charAt(int offset)
Index zero is the first character position after this field's label.
offset - Index of the character to retrieve.IndexOutOfBoundsException - if offset is less than zero, or
greater than or equal to the value returned from getTextLength().public void clear(int context)
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).
context - Context ID for this action.public void displayFieldFullMessage()
public void fieldChangeNotify(int context)
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.
fieldChangeNotify in class Fieldcontext - Information specifying the origin of the change.public int getCursorPosition()
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).
public TextFilter getFilter()
public String getLabel()
public int getLabelLength()
The length returned includes any additional character appended for layout purposes.
Therefore the value may not be the same as #getLabel().length()
public int getMaxSize()
This method does not include this field's label as part of its accounting.
public String getText()
public String getText(int offset, int length)
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.
offset - First character to return.length - Number of characters to return.
public void getText(int srcBegin,
int srcEnd,
char[] dst,
int dstBegin)
Note: This method adjusts for the label in the field's contents, so the srcBegin and srcEnd parameters decribe the field's actual contents.
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.public AbstractString getTextAbstractString()
Note: The underlying buffer can be modified by this field if
methods such as insert(java.lang.String) or selectionDelete() are invoked.
public int getTextLength()
public int insert(String text)
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).
text - String to insert.public int insert(String text, int context)
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.
text - String to insert.context - Information specifying the origin of the change. false
indicates user-initiated insertion.public boolean isSelectable()
This method returns true as long as this field contains at least one character.
isSelectable in class Fieldpublic final boolean isSelecting()
isSelecting in class Fieldprotected boolean isSymbolScreenAllowed()
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.
true if this field supports the symbol screen;
false if it does not.
public boolean keyChar(char key,
int status,
int time)
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:
NO_NEWLINE), and the ENTER key was pressed. EDITABLE (exception: if in
select mode, and the ENTER key was pressed). key - Character generated by the event.status - Modifier key status.time - Number of milliseconds since the device was turned on.
protected boolean keyControl(char key,
int status,
int time)
This field's manager invokes this method to send this field a control character event.
keyControl in class Fieldkey - Character generated.status - Modifier key status. See KeypadListener.time - Number of milliseconds since the device was turned on.public boolean paste(Clipboard cb)
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.
cb - Clipboard object holding the text scrap.public void selectionCopy(Clipboard cb)
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.
selectionCopy in class Fieldcb - Clipboard to contain copied text.public void selectionDelete()
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.
selectionDelete in class FieldField.isSelectionDeleteable(),
Field.selectionCut(net.rim.device.api.system.Clipboard)public void setCursorPosition(int offset)
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.
offset - Character position to receive the cursor, counting from the
first character in this field's value.
protected void setCursorPosition(int offset,
int context)
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).
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.public void setFilter(TextFilter filter)
filter - Text filter for this field.public void setLabel(String newLabel)
newLabel - New label for this field.public void setMaxSize(int maxSize)
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.
MaxSize - New maximum number of characters for this edit field's
value.IllegalArgumentException - If maxNumChars is less than zero.
public void setSelection(int aNewCursor,
boolean aNewCursorLeadingEdge,
int aNewAnchor)
aNewCursor - New cursor position.aNewCursorLeadingEdge - True if the cursor is at the leading edge of the character.aNewAnchor - New anchor position.public void setText(String text) throws IllegalArgumentException
text.text - New string value for this field; if null, this method clears
the field.IllegalArgumentException - If the text cannot be entered into an
edit field.protected void setText(String text, int context) throws IllegalArgumentException
text - New string value for this field; if null, this method clears
the field.context - Information specifying the origin of the change.IllegalArgumentException - If the text cannot be entered
into an edit field.
protected void update(int aStart,
int aLength,
int aNewLength,
int aCursorOffset,
boolean aMoveCursor,
boolean aIsInsertionOrDeletion)
Text starting at aStart, of length aLength, has just been replaced by text of aNewLength.
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 accordinglyaIsInsertionOrDeletion - if true, insertion or deletion of text occurred, as the opposite to attribute change
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.