MID Profile

javax.microedition.lcdui
Class TextBox

java.lang.Object
  |
  +--javax.microedition.lcdui.Displayable
        |
        +--javax.microedition.lcdui.Screen
              |
              +--javax.microedition.lcdui.TextBox

public class TextBox
extends Screen

The TextBox class is a Screen that allows the user to enter and edit text. The TextBox has a title that is shown at the top of the display. It can be given a piece of text that is used as the initial value. The TextBox has a maximum capacity (in terms of the number of characters) that is set by the application. When the TextBox reaches this maximum capacity, the user is not allowed to enter additional characters unless some are deleted first.

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

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.


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 deleteChars(int offset, int length)
          Deletes characters from the TextBox.
 int getChars(char[] data)
          Copies the contents of the TextBox into a character array starting at index zero.
 int getConstraints()
          Get the current input constraints of the TextBox.
 int getMaxSize()
          Returns the maximum size (number of characters) that can be stored in this TextBox.
 int getSize()
          Gets the number of characters that are currently stored in this TextBox.
 String getString()
          Gets the contents of the TextBox as a string value.
 void insertChars(char[] data, int offset, int length, int position)
          Inserts a subrange of an array of characters just prior to the given position.
 void insertString(String src, int position)
          Inserts a string into the contents just prior to the given position.
 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 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.
 
Methods inherited from class javax.microedition.lcdui.Screen
getTicker, getTitle, setTicker, setTitle
 
Methods inherited from class javax.microedition.lcdui.Displayable
addCommand, isShown, removeCommand, setListener
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TextBox

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.
Parameters:
title - the title text to be shown at the top of 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
constraints - see input constraints
Throws:
IllegalArgumentException - if maxSize is zero or less
IllegalArgumentException - if the constraints parameter is invalid
IllegalArgumentException - if the length of the string exceeds the requested maximum capacity
OutOfMemoryError - if the implementation cannot accommodate the requested maximum size
Method Detail

getString

public String getString()
Gets the contents of the TextBox as a string value.
Returns:
the current contents

setString

public void setString(String text)
Sets the contents of the TextBox as a string value, replacing the previous contents.
Parameters:
text - the new value of the TextBox
Throws:
IllegalArgumentException - if the text is illegal for the current input constraints
IllegalArgumentException - if the text would exceed the current maximum capacity

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:
ArrayIndexOutOfBoundsException - if the array is too short for the contents

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.
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:
ArrayIndexOutOfBoundsException - if offset and length do not specify a valid range within the data array
IllegalArgumentException - if the text is illegal for the current input constraints
IllegalArgumentException - if the text would exceed the current maximum capacity

insertString

public void insertString(String src,
                         int position)
Inserts a string into the contents just prior to the given position. The given position must be between zero and the current maximum size. If the position is beyond the end of the current contents, the effect is as if string were appended to the contents with no intervening characters. Thus, text.insertString(str, text.getMaxSize()) always appends the string str. The current size of the contents is increased by the number of inserted characters. The resulting string must fit within the current maximum capacity.

Parameters:
src - the String to be inserted
position - the position at which insertion is to occur
Throws:
ArrayIndexOutOfBoundsException - if position is invalid
IllegalArgumentException - if the resulting content is illegal for the current input constraints
IllegalArgumentException - if the insertion would exceed the current maximum capacity

insertChars

public void insertChars(char[] data,
                        int offset,
                        int length,
                        int position)
Inserts a subrange of an array of characters just prior to the given position. The offset and length parameters indicate the subrange of the data array to be used for insertion. Behavior is otherwise identical to insertString().

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:
ArrayIndexOutOfBoundsException - if position is invalid
ArrayIndexOutOfBoundsException - if offset and length do not specify a valid range within the data array
IllegalArgumentException - if the resulting content is illegal for the current input constraints
IllegalArgumentException - if the insertion would exceed the current maximum capacity

deleteChars

public void deleteChars(int offset,
                        int length)
Deletes characters from the TextBox.
Parameters:
offset - the beginning of the region to be deleted
length - the number of characters to be deleted
Throws:
ArrayIndexOutOfBoundsException - if offset and length do not specify a valid range within the content of TextBox
IllegalArgumentException - if the resulting content is illegal for the current input constraints

getMaxSize

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

setMaxSize

public void 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
Throws:
IllegalArgumentException - if maxSize is zero or less
OutOfMemoryError - if the implementation cannot accommodate the requested maximum size

getSize

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

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:
IllegalArgumentException - if the value of the constraints parameter is invalid

getConstraints

public int getConstraints()
Get the current input constraints of the TextBox.
Returns:
the current constraints value (see input constraints)

MID Profile

Submit a comment or suggestion Version 0.9 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.