Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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

### 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. 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:
  `IllegalArgumentException` - if `maxSize` is zero or less
  `IllegalArgumentException` - if the `constraints` parameter is invalid
  `IllegalArgumentException` - if `text` is illegal for the specified constraints
  `IllegalArgumentException` - if the length of the string exceeds the requested maximum capacity

Method Detail

### getString

    public 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(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:
    `IllegalArgumentException` - if `text` is illegal for the current input constraints
    `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:
    `ArrayIndexOutOfBoundsException` - if the array is too short for the contents
    `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:
    `ArrayIndexOutOfBoundsException` - if `offset` and `length` do not specify a valid range within the data array
    `IllegalArgumentException` - if `data` is illegal for the current input constraints
    `IllegalArgumentException` - if the text would exceed the current maximum capacity
  See Also:
    `getChars(char[])`

### insert

    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`. 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:
    `IllegalArgumentException` - if the resulting contents would be illegal for the current input constraints
    `IllegalArgumentException` - if the insertion would exceed the current maximum capacity
    `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:
    `ArrayIndexOutOfBoundsException` - if `offset` and `length` do not specify a valid range within the data array
    `IllegalArgumentException` - if the resulting contents would be illegal for the current input constraints
    `IllegalArgumentException` - if the insertion would exceed the current maximum capacity
    `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:
    `IllegalArgumentException` - if the resulting contents would be illegal for the current input constraints
    `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:
    `IllegalArgumentException` - if `maxSize` is zero or less.
    `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. 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.

  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:
    `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(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

### setTitle

    public void setTitle(String s)

  Sets the title of the `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.

  Overrides:
    `setTitle` in class `Displayable`
  Parameters:
    `s` - the new title, or `null` for no title
  Since:
    MIDP 2.0
  See Also:
    `Displayable.getTitle()`

### setTicker

    public void setTicker(Ticker ticker)

  Sets a ticker for use with this `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.

  Overrides:
    `setTicker` in class `Displayable`
  Parameters:
    `ticker` - the ticker object used on this screen
  Since:
    MIDP 2.0
  See Also:
    `Displayable.getTicker()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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