MIDP3.0

javax.microedition.lcdui
Class TextBox

java.lang.Object
  extended by javax.microedition.lcdui.Displayable
      extended by javax.microedition.lcdui.Screen
          extended by javax.microedition.lcdui.TextBox

public class TextBox
extends Screen

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.

Since:
MIDP 1.0

Constructor Summary
TextBox(java.lang.String title, java.lang.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 getHeight()
          Returns the height in pixels of the displayable area in the TextBox that is used to render the text without scrolling.
 int getMaxSize()
          Returns the maximum size (number of characters) that can be stored in this TextBox.
 java.lang.String getString()
          Gets the contents of the TextBox as a string value.
 int getWidth()
          Returns the width in pixels of the displayable area in the TextBox that is used to render the text without scrolling.
 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(java.lang.String src, int position)
          Inserts a string into the contents of the TextBox.
 void setCaret(int index)
          Sets the index of the caret.
 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 setHighlight(int index, int length)
          Sets the highlight on a range in the text.
 void setInitialInputMode(java.lang.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(java.lang.String text)
          Sets the contents of the TextBox as a string value, replacing the previous contents.
 int size()
          Gets the number of characters that are currently stored in this TextBox.
 
Methods inherited from class javax.microedition.lcdui.Displayable
addCommand, getCommand, getCommandLayoutPolicy, getCommands, getCurrentDisplay, getMenu, getTicker, getTitle, invalidateCommandLayout, isShown, removeCommand, removeCommandOrMenu, setCommand, setCommandLayoutPolicy, setCommandListener, setMenu, setTicker, setTitle, sizeChanged
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TextBox

public TextBox(java.lang.String title,
               java.lang.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. 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
text - the initial contents of the text editing area, null may be used to indicate no initial content
maxSize - 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 constraints
Throws:
java.lang.IllegalArgumentException - if maxSize is zero or less
java.lang.IllegalArgumentException - if the constraints parameter is invalid
java.lang.IllegalArgumentException - if text is illegal for the specified constraints
java.lang.IllegalArgumentException - if the length of the string exceeds the requested maximum capacity
Method Detail

getString

public java.lang.String getString()
Gets the contents of the TextBox as a string value.

Returns:
the current contents
See Also:
setString(java.lang.String)

setString

public void setString(java.lang.String text)
Sets the contents of the TextBox as a string value, replacing the previous contents.

Parameters:
text - the new value of the TextBox, or null if the TextBox is to be made empty
Throws:
java.lang.IllegalArgumentException - if text is illegal for the current input constraints
java.lang.IllegalArgumentException - if the text would exceed the current maximum capacity
See Also:
getString()

getChars

public int getChars(char[] data)
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
Returns:
the number of characters copied
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the array is too short for the contents
java.lang.NullPointerException - if data is null
See Also:
setChars(char[], int, int)

setChars

public void setChars(char[] data,
                     int offset,
                     int length)
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
offset - the beginning of the region of characters to copy
length - the number of characters to copy
Throws:
java.lang.ArrayIndexOutOfBoundsException - if offset and length do not specify a valid range within the data array
java.lang.IllegalArgumentException - if data is illegal for the current input constraints
java.lang.IllegalArgumentException - if the text would exceed the current maximum capacity
See Also:
getChars(char[])

insert

public void insert(java.lang.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. 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.

Parameters:
src - the String to be inserted
position - the position at which insertion is to occur
Throws:
java.lang.IllegalArgumentException - if the resulting contents would be illegal for the current input constraints
java.lang.IllegalArgumentException - if the insertion would exceed the current maximum capacity
java.lang.NullPointerException - if src is null

insert

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

Parameters:
data - the source of the character data
offset - the beginning of the region of characters to copy
length - the number of characters to copy
position - the position at which insertion is to occur
Throws:
java.lang.ArrayIndexOutOfBoundsException - if offset and length do not specify a valid range within the data array
java.lang.IllegalArgumentException - if the resulting contents would be illegal for the current input constraints
java.lang.IllegalArgumentException - if the insertion would exceed the current maximum capacity
java.lang.NullPointerException - if data is null

delete

public void delete(int offset,
                   int length)
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
length - the number of characters to be deleted
Throws:
java.lang.IllegalArgumentException - if the resulting contents would be illegal for the current input constraints
java.lang.StringIndexOutOfBoundsException - if offset and length do not specify a valid range within the contents of the TextBox

getMaxSize

public int getMaxSize()
Returns the maximum size (number of characters) that can be stored in this TextBox.

Returns:
the maximum size in characters
See Also:
setMaxSize(int)

setMaxSize

public int setMaxSize(int maxSize)
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
Returns:
assigned maximum capacity - may be smaller than requested.
Throws:
java.lang.IllegalArgumentException - if maxSize is zero or less.
java.lang.IllegalArgumentException - if the contents after truncation would be illegal for the current input constraints
See Also:
getMaxSize()

size

public int size()
Gets the number of characters that are currently stored in this TextBox.

Returns:
the number of characters

getCaretPosition

public int getCaretPosition()
Gets the current input position.

Returns:
the current caret position, 0 if at the beginning

setConstraints

public void setConstraints(int constraints)
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 - see input constraints
Throws:
java.lang.IllegalArgumentException - if the value of the constraints parameter is invalid
See Also:
getConstraints()

getConstraints

public int getConstraints()
Gets the current input constraints of the TextBox.

Returns:
the current constraints value (see input constraints)
See Also:
setConstraints(int)

setInitialInputMode

public void setInitialInputMode(java.lang.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. 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
Since:
MIDP 2.0

setCaret

public void setCaret(int index)
Sets the index of the caret. The caret can be used to indicate a position in the text.

Parameters:
index - the character index before which to place the caret; -1 if the caret is not displayed.
Since:
MIDP 3.0

setHighlight

public void setHighlight(int index,
                         int length)
Sets the highlight on a range in the text.

Parameters:
index - the index of the first character to be highlighted.
length - the length in characters to be highlighted.
Since:
MIDP 3.0

getWidth

public int getWidth()
Returns the width in pixels of the displayable area in the TextBox that is used to render the text without scrolling. This displayable area only includes the area in which the text can be displayed. This area MUST NOT include any Title,Ticker, or any other artifact such as the scrollbar which does not render the text.

Specified by:
getWidth in class Displayable
Returns:
the width in pixels available to display text in the TextBox
Since:
MIDP 3.0

getHeight

public int getHeight()
Returns the height in pixels of the displayable area in the TextBox that is used to render the text without scrolling. This displayable area only includes the area in which the text can be displayed. This area MUST NOT include any Title,Ticker, or any other artifact such as the scrollbar which does not render the text.

Specified by:
getHeight in class Displayable
Returns:
the height in pixels available to display text in the TextBox
Since:
MIDP 3.0

MIDP3.0

Send a comment or suggestionVersion 3.0 of Mobile Information Device Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 2002-2009 Motorola Inc. Portions copyright 1993-2002 Sun Microsystems, Inc. and Motorola, Inc. All Rights Reserved.