| java.lang.Object
 javax.microedition.lcdui.Displayable
javax.microedition.lcdui.Screen
javax.microedition.lcdui.TextBox
| TextBox | | public class TextBox extends Screen (Code) | | The TextBox class is a Screen that allows
the user to enter and edit
text.
A TextBox has a maximum size, which is the maximum
number of characters
that can be stored in the object at any time (its capacity). This limit is
enforced when the TextBox instance is constructed,
when the user is editing text within the TextBox, as well as
when the application program calls methods on the
TextBox that modify its
contents. The maximum size is the maximum stored capacity and is unrelated
to the number of characters that may be displayed at any given time.
The number of characters displayed and their arrangement into rows and
columns are determined by the device.
The implementation may place a boundary on the maximum size, and the
maximum size actually assigned may be smaller than the application had
requested. The value actually assigned will be reflected in the value
returned by
TextBox.getMaxSize() getMaxSize() . A defensively-written
application should compare this value to the maximum size requested and be
prepared to handle cases where they differ.
The text contained within a TextBox may be more
than can be displayed at
one time. If this is the case, the implementation will let the user scroll
to view and edit any part of the text. This scrolling occurs transparently
to the application.
If the constraints are set to
TextField.ANY The text may contain line breaks.
The display of the text must break accordingly and the user must be
able to enter line break characters.
TextBox has the concept of
input constraints that is identical to
TextField. The constraints parameters of
methods within the
TextBox class use constants defined in the
TextField TextField class. See the description of
input constraints
in the TextField class for the definition of these
constants. TextBox also has the same notions as
TextField of the actual contents and the
displayed contents, described in the same section.
TextBox also has the concept of input
modes that is identical
to TextField. See the description of input
modes in the TextField class for more details.
since:
MIDP 1.0
|
| Constructor Summary | |
| public | TextBox(String title, String text, int maxSize, int constraints)
Creates a new TextBox object with the given title
string, initial
contents, maximum size in characters, and constraints.
If the text parameter is null, the
TextBox is created empty.
The maxSize parameter must be greater than zero.
An IllegalArgumentException is thrown if the
length of the initial contents string exceeds maxSize.
However,
the implementation may assign a maximum size smaller than the
application had requested. |
| Method Summary | |
| public void | delete(int offset, int length)
Deletes characters from the TextBox. | | public int | getCaretPosition()
Gets the current input position. | | public int | getChars(char[] data)
Copies the contents of the TextBox into a
character array starting at
index zero. | | public int | getConstraints()
Gets the current input constraints of the TextBox. | | public int | getMaxSize()
Returns the maximum size (number of characters) that can be
stored in this TextBox. | | public String | getString()
Gets the contents of the TextBox as a string value. | | public void | insert(String src, int position)
Inserts a string into the contents of the TextBox.
The string is
inserted just prior to the character indicated by the
position parameter, where zero specifies the first
character of the contents of the TextBox. | | public void | insert(char[] data, int offset, int length, int position)
Inserts a subrange of an array of characters into the contents of
the TextBox. | | public void | setChars(char[] data, int offset, int length)
Sets the contents of the TextBox from a character
array, replacing the
previous contents. | | public void | setConstraints(int constraints)
Sets the input constraints of the TextBox. | | public void | setInitialInputMode(String characterSubset)
Sets a hint to the implementation as to the input mode that should be
used when the user initiates editing of this
TextBox. | | public int | setMaxSize(int maxSize)
Sets the maximum size (number of characters) that can be
contained in this
TextBox. | | public void | setString(String text)
Sets the contents of the TextBox as a string
value, replacing the previous contents. | | public int | size()
Gets the number of characters that are currently stored in this
TextBox. |
| textBoxLF | | FormLF textBoxLF(Code) | | Look & feel object associated with this TextBox
|
| TextBox | | public TextBox(String title, String text, int maxSize, int constraints)(Code) | | Creates a new TextBox object with the given title
string, initial
contents, maximum size in characters, and constraints.
If the text parameter is null, the
TextBox is created empty.
The maxSize parameter must be greater than zero.
An IllegalArgumentException is thrown if the
length of the initial contents string exceeds maxSize.
However,
the implementation may assign a maximum size smaller than the
application had requested. If this occurs, and if the length of the
contents exceeds the newly assigned maximum size, the contents are
truncated from the end in order to fit, and no exception is thrown.
Parameters:
title - the title text to be shown with the display
Parameters:
text - the initial contents of the text editing area,null may be used toindicate no initial content
Parameters:
maxSize - the maximum capacity in characters. The implementationmay limitboundary maximum capacity and the actually assigned capacity mayme smaller than requested. A defensive application will test theactually givencapacity with TextBox.getMaxSize().
Parameters:
constraints - see inputconstraints
throws:
IllegalArgumentException - if maxSize is zero or less
throws:
IllegalArgumentException - if the constraintsparameter is invalid
throws:
IllegalArgumentException - if text is illegalfor the specified constraints
throws:
IllegalArgumentException - if the length of the string exceedsthe requested maximum capacity |
| delete | | public void delete(int offset, int length)(Code) | | Deletes characters from the TextBox.
The offset and length parameters must
specify a valid range of characters within
the contents of the TextBox.
The offset parameter must be within the
range [0..(size())], inclusive.
The length parameter
must be a non-negative integer such that
(offset + length) <= size().
Parameters:
offset - the beginning of the region to be deleted
Parameters:
length - the number of characters to be deleted
throws:
IllegalArgumentException - if the resulting contentswould be illegal for the currentinput constraints
throws:
StringIndexOutOfBoundsException - if offsetand length do notspecify a valid range within the contents of the TextBox |
| getCaretPosition | | public int getCaretPosition()(Code) | | Gets the current input position. For some UIs this may block and ask
the user for the intended caret position, and on other UIs this may
simply return the current caret position.
the current caret position, 0 if at the beginning |
| getChars | | public int getChars(char[] data)(Code) | | Copies the contents of the TextBox into a
character array starting at
index zero. Array elements beyond the characters copied are left
unchanged.
Parameters:
data - the character array to receive the value the number of characters copied
throws:
ArrayIndexOutOfBoundsException - if the array is too short for thecontents
throws:
NullPointerException - if data is null
See Also: TextBox.setChars |
| getMaxSize | | public int getMaxSize()(Code) | | Returns the maximum size (number of characters) that can be
stored in this TextBox.
the maximum size in characters
See Also: TextBox.setMaxSize |
| insert | | public void insert(String src, int position)(Code) | | Inserts a string into the contents of the TextBox.
The string is
inserted just prior to the character indicated by the
position parameter, where zero specifies the first
character of the contents of the TextBox. If
position is
less than or equal to zero, the insertion occurs at the beginning of
the contents, thus effecting a prepend operation. If
position is greater than or equal to the current size of
the contents, the insertion occurs immediately after the end of the
contents, thus effecting an append operation. For example,
text.insert(s, text.size()) always appends the string
s to the current contents.
The current size of the contents is increased by the number of
inserted characters. The resulting string must fit within the current
maximum capacity.
If the application needs to simulate typing of characters it can
determining the location of the current insertion point
("caret")
using the with
TextBox.getCaretPosition() getCaretPosition() method.
For example,
text.insert(s, text.getCaretPosition()) inserts the string
s at the current caret position.
Parameters:
src - the String to be inserted
Parameters:
position - the position at which insertion is to occur
throws:
IllegalArgumentException - if the resulting contentswould be illegal for the currentinput constraints
throws:
IllegalArgumentException - if the insertion wouldexceed the currentmaximum capacity
throws:
NullPointerException - if src is null |
| insert | | public void insert(char[] data, int offset, int length, int position)(Code) | | Inserts a subrange of an array of characters into the contents of
the TextBox. The offset and
length parameters indicate the subrange of
the data array to be used for insertion. Behavior is otherwise
identical to
TextBox.insert(String,int) insert(String, int) .
The offset and length parameters must
specify a valid range of characters within
the character array data.
The offset parameter must be within the
range [0..(data.length)], inclusive.
The length parameter
must be a non-negative integer such that
(offset + length) <= data.length.
Parameters:
data - the source of the character data
Parameters:
offset - the beginning of the region of characters to copy
Parameters:
length - the number of characters to copy
Parameters:
position - the position at which insertion is to occur
throws:
ArrayIndexOutOfBoundsException - if offsetand length do notspecify a valid range within the data array
throws:
IllegalArgumentException - if the resulting contentswould be illegal for the currentinput constraints
throws:
IllegalArgumentException - if the insertion wouldexceed the currentmaximum capacity
throws:
NullPointerException - if data is null |
| setChars | | public void setChars(char[] data, int offset, int length)(Code) | | Sets the contents of the TextBox from a character
array, replacing the
previous contents. Characters are copied from the region of the
data array
starting at array index offset and running for
length characters.
If the data array is null, the TextBox
is set to be empty and the other parameters are ignored.
The offset and length parameters must
specify a valid range of characters within
the character array data.
The offset parameter must be within the
range [0..(data.length)], inclusive.
The length parameter
must be a non-negative integer such that
(offset + length) <= data.length.
Parameters:
data - the source of the character data
Parameters:
offset - the beginning of the region of characters to copy
Parameters:
length - the number of characters to copy
throws:
ArrayIndexOutOfBoundsException - if offsetand length do not specifya valid range within the data array
throws:
IllegalArgumentException - if datais illegal for the current input constraints
throws:
IllegalArgumentException - if the text would exceed the currentmaximum capacity
See Also: TextBox.getChars |
| setConstraints | | public void setConstraints(int constraints)(Code) | | Sets the input constraints of the TextBox. If the
current contents
of the TextBox do not match the new constraints,
the contents are
set to empty.
Parameters:
constraints - seeinput constraints
throws:
IllegalArgumentException - if the value of the constraintsparameter is invalid
See Also: TextBox.getConstraints |
| setInitialInputMode | | public void setInitialInputMode(String characterSubset)(Code) | | Sets a hint to the implementation as to the input mode that should be
used when the user initiates editing of this
TextBox. The
characterSubset parameter names a subset of Unicode
characters that is used by the implementation to choose an initial
input mode. If null is passed, the implementation should
choose a default input mode.
See Input Modes for a full
explanation of input modes.
Parameters:
characterSubset - a string naming a Unicode character subset,or null |
| setMaxSize | | public int setMaxSize(int maxSize)(Code) | | Sets the maximum size (number of characters) that can be
contained in this
TextBox. If the current contents of the
TextBox are larger than
maxSize, the contents are truncated to fit.
Parameters:
maxSize - the new maximum size assigned maximum capacity - may be smaller than requested.
throws:
IllegalArgumentException - if maxSize is zero or less.
throws:
IllegalArgumentException - if the contentsafter truncation would be illegal for the current input constraints
See Also: TextBox.getMaxSize |
| size | | public int size()(Code) | | Gets the number of characters that are currently stored in this
TextBox.
the number of characters |
|
|