|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.lcdui.Displayable | +--javax.microedition.lcdui.Screen | +--javax.microedition.lcdui.TextBox
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 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
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.
Constructor Summary | |
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. |
Method Summary | |
void |
delete(int offset,
int length)
Deletes characters from the TextBox . |
int |
getCaretPosition()
Gets the current input position. |
int |
getChars(char[] data)
Copies the contents of the TextBox into a
character array starting at
index zero. |
int |
getConstraints()
Gets the current input constraints of the TextBox . |
int |
getMaxSize()
Returns the maximum size (number of characters) that can be stored in this TextBox . |
String |
getString()
Gets the contents of the TextBox as a string value. |
void |
insert(char[] data,
int offset,
int length,
int position)
Inserts a subrange of an array of characters into the contents of the TextBox . |
void |
insert(String src,
int position)
Inserts a string into the contents of the TextBox . |
void |
setChars(char[] data,
int offset,
int length)
Sets the contents of the TextBox from a character
array, replacing the
previous contents. |
void |
setConstraints(int constraints)
Sets the input constraints of the TextBox . |
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 . |
int |
setMaxSize(int maxSize)
Sets the maximum size (number of characters) that can be contained in this TextBox . |
void |
setString(String text)
Sets the contents of the TextBox as a string
value, replacing the previous contents. |
void |
setTicker(Ticker ticker)
Sets a ticker for use with this Displayable ,
replacing any
previous ticker. |
void |
setTitle(String s)
Sets the title of the Displayable . |
int |
size()
Gets the number of characters that are currently stored in this TextBox . |
Methods inherited from class javax.microedition.lcdui.Displayable |
addCommand, getHeight, getTicker, getTitle, getWidth, isShown, removeCommand, setCommandListener, sizeChanged |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
public TextBox(String title, String text, int maxSize, int constraints)
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.title
- the title text to be shown with the displaytext
- the initial contents of the text editing area,
null
may be used to
indicate no initial contentmaxSize
- the maximum capacity in characters. The implementation
may limit
boundary maximum capacity and the actually assigned capacity may
me smaller than requested. A defensive application will test the
actually given
capacity with getMaxSize()
.constraints
- see input
constraintsIllegalArgumentException
- if maxSize
is zero or lessIllegalArgumentException
- if the constraints
parameter is invalidIllegalArgumentException
- if text
is illegal
for the specified constraintsIllegalArgumentException
- if the length of the string exceeds
the requested maximum capacityMethod Detail |
public String getString()
TextBox
as a string value.setString(java.lang.String)
public void setString(String text)
TextBox
as a string
value, replacing the previous contents.text
- the new value of the TextBox
, or
null
if the TextBox
is to
be made emptyIllegalArgumentException
- if text
is illegal for the current
input constraintsIllegalArgumentException
- if the text would exceed the current
maximum capacitygetString()
public int getChars(char[] data)
TextBox
into a
character array starting at
index zero. Array elements beyond the characters copied are left
unchanged.data
- the character array to receive the valueArrayIndexOutOfBoundsException
- if the array is too short for the
contentsNullPointerException
- if data
is null
setChars(char[], int, int)
public void setChars(char[] data, int offset, int length)
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
.
data
- the source of the character dataoffset
- the beginning of the region of characters to copylength
- the number of characters to copyArrayIndexOutOfBoundsException
- if offset
and length
do not specify
a valid range within the data arrayIllegalArgumentException
- if data
is illegal for the current
input constraintsIllegalArgumentException
- if the text would exceed the current
maximum capacitygetChars(char[])
public void insert(String src, int position)
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 getCaretPosition()
method.
For example,
text.insert(s, text.getCaretPosition())
inserts the string
s
at the current caret position.
src
- the String
to be insertedposition
- the position at which insertion is to occurIllegalArgumentException
- if the resulting contents
would be illegal for the current
input constraintsIllegalArgumentException
- if the insertion would
exceed the current
maximum capacityNullPointerException
- if src
is null
public void insert(char[] data, int offset, int length, int position)
TextBox
. The offset
and
length
parameters indicate the subrange of
the data array to be used for insertion. Behavior is otherwise
identical to 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
.
data
- the source of the character dataoffset
- the beginning of the region of characters to copylength
- the number of characters to copyposition
- the position at which insertion is to occurArrayIndexOutOfBoundsException
- if offset
and length
do not
specify a valid range within the data arrayIllegalArgumentException
- if the resulting contents
would be illegal for the current
input constraintsIllegalArgumentException
- if the insertion would
exceed the current
maximum capacityNullPointerException
- if data
is null
public void delete(int offset, int length)
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()
.
offset
- the beginning of the region to be deletedlength
- the number of characters to be deletedIllegalArgumentException
- if the resulting contents
would be illegal for the current
input constraintsStringIndexOutOfBoundsException
- if offset
and length
do not
specify a valid range within the contents of the TextBox
public int getMaxSize()
TextBox
.setMaxSize(int)
public int setMaxSize(int maxSize)
TextBox
. If the current contents of the
TextBox
are larger than
maxSize
, the contents are truncated to fit.maxSize
- the new maximum sizeIllegalArgumentException
- if maxSize
is zero or less.IllegalArgumentException
- if the contents
after truncation would be illegal for the current
input constraintsgetMaxSize()
public int size()
TextBox
.public int getCaretPosition()
0
if at the beginningpublic void setConstraints(int constraints)
TextBox
. If the
current contents
of the TextBox
do not match the new constraints,
the contents are
set to empty.constraints
- see
input constraintsIllegalArgumentException
- if the value of the constraints
parameter is invalidgetConstraints()
public int getConstraints()
TextBox
.setConstraints(int)
public void setInitialInputMode(String characterSubset)
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.
characterSubset
- a string naming a Unicode character subset,
or null
public void setTitle(String s)
Displayable
. If
null
is given,
removes the title.
If the Displayable
is actually visible on
the display,
the implementation should update
the display as soon as it is feasible to do so.
The existence of a title may affect the size
of the area available for Displayable
content.
If the application adds, removes, or sets the title text at runtime,
this can dynamically change the size of the content area.
This is most important to be aware of when using the
Canvas
class.
setTitle
in class Displayable
s
- the new title, or null
for no titleDisplayable.getTitle()
public void setTicker(Ticker ticker)
Displayable
,
replacing any
previous ticker.
If null
, removes the ticker object
from this Displayable
. The same ticker may be shared by
several Displayable
objects within an application. This is done by calling
setTicker()
with the same Ticker
object on several
different Displayable
objects.
If the Displayable
is actually visible on the display,
the implementation should update
the display as soon as it is feasible to do so.
The existence of a ticker may affect the size
of the area available for Displayable's
contents.
If the application adds, removes, or sets the ticker text at runtime,
this can dynamically change the size of the content area.
This is most important to be aware of when using the
Canvas
class.
setTicker
in class Displayable
ticker
- the ticker object used on this screenDisplayable.getTicker()
|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |