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

## javax.microedition.lcdui
Class TextField

    java.lang.Object
      |
      +--javax.microedition.lcdui.Item
            |
            +--javax.microedition.lcdui.TextField

public class TextField
extends Item

A TextField is an editable text component that may be placed into a `Form`. It can be given a piece of text that is used as the initial value.

A TextField 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 TextField, as well as when the application program calls methods on the TextField 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.

### Input Constraints

The TextField shares the concept of input constraints with the `TextBox` object. The different constraints allow the application to request that the user's input be restricted in a variety of ways. The implementation is required to restrict the user's input as requested by the application. For example, if the application requests the NUMERIC constraint on a TextField, the implementation must allow only numerals to be entered.

The implementation may provide special formatting for the value entered. For example, a PHONENUMBER field may be separated and punctuated as appropriate for the phone number conventions in use, grouping the digits into country code, area code, prefix, etc. Any spaces or punctuation provided are not considered part of the text field's value. For example, a TextField with the PHONENUMBER constraint might display as follows:

     (408) 555-1212

but the value of the field visible to the application would be a string representing a legal phone number like "4085551212". Note that in some networks a '+' prefix is part of the number and returned as a part of the string.

Field Summary
`static int` | `ANY` The user is allowed to enter any text.
`static int` | `CONSTRAINT_MASK` The mask value for determining the constraint mode.
`static int` | `EMAILADDR` The user is allowed to enter an e-mail address.
`static int` | `NUMERIC` The user is allowed to enter only an integer value.
`static int` | `PASSWORD` The text entered must be masked so that the characters typed are not visible.
`static int` | `PHONENUMBER` The user is allowed to enter a phone number.
`static int` | `URL` The user is allowed to enter a URL.

Constructor Summary
`TextField(String label, String text, int maxSize, int constraints)` Creates a new TextField object with the given label, initial contents, maximum size in characters, and constraints.

Method Summary
`void` | `delete(int offset, int length)` Deletes characters from the TextField.
`int` | `getCaretPosition()` Gets the current input position.
`int` | `getChars(char[] data)` Copies the contents of the TextField into a character array starting at index zero.
`int` | `getConstraints()` Get the current input constraints of the TextField.
`int` | `getMaxSize()` Returns the maximum size (number of characters) that can be stored in this TextField.
`String` | `getString()` Gets the contents of the TextField 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 TextField.
`void` | `insert(String src, int position)` Inserts a string into the contents of the TextField.
`void` | `setChars(char[] data, int offset, int length)` Sets the contents of the TextField from a character array, replacing the previous contents.
`void` | `setConstraints(int constraints)` Sets the input constraints of the TextField.
`void` | `setMaxSize(int maxSize)` Sets the maximum size (number of characters) that can be contained in this TextField.
`void` | `setString(String text)` Sets the contents of the TextField as a string value, replacing the previous contents.
`int` | `size()` Gets the number of characters that are currently stored in this TextField.

Methods inherited from class javax.microedition.lcdui.Item
`getLabel, setLabel`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ANY

    public static final int ANY

  The user is allowed to enter any text.

  Constant 0 is assigned to ANY.

### EMAILADDR

    public static final int EMAILADDR

  The user is allowed to enter an e-mail address.

  Constant 1 is assigned to EMAILADDDR.

### NUMERIC

    public static final int NUMERIC

  The user is allowed to enter only an integer value.

  Constant 2 is assigned to NUMERIC.

### PHONENUMBER

    public static final int PHONENUMBER

  The user is allowed to enter a phone number. The phone number is a special case, since a phone-based implementation may be linked to the native phone dialing application. The implementation may automatically start a phone dialer application that is initialized so that pressing a single key would be enough to make a call. The call must not made automatically without requiring user's confirmation.

  Constant 3 is assigned to PHONENUMBER.

### URL

    public static final int URL

  The user is allowed to enter a URL.

  Constant 4 is assigned to URL.

### PASSWORD

    public static int PASSWORD

  The text entered must be masked so that the characters typed are not visible. The actual contents of the text field are not affected, but each character is displayed using a mask character such as "*". The character chosen as the mask character is implementation-dependent. This is useful for entering confidential information such as passwords or PINs (personal identification numbers).

  The PASSWORD modifier can be combined with other input constraints by using the logical OR operator (|). However, The PASSWORD modifier is nonsensical with some constraint values such as EMAILADDR, PHONENUMBER, and URL.

  Constant 0x10000 is assigned to PASSWORD.

### CONSTRAINT_MASK

    public static int CONSTRAINT_MASK

  The mask value for determining the constraint mode. The application should use the logical AND operation with a value returned by getConstraints() and CONSTRAINT_MASK in order to retrieve the current constraint mode, in order to remove any modifier flags such as the PASSWORD flag.

  Constant 0xFFFF is assigned to CONSTRAINT_MASK.

Constructor Detail

### TextField

    public TextField(String label,
                     String text,
                     int maxSize,
                     int constraints)

  Creates a new TextField object with the given label, initial contents, maximum size in characters, and constraints. If the text parameter is null, the TextField is created empty. The maxSize parameter must be greater than zero.
  Parameters:
    `label` - item label
    `text` - the initial contents, or null if the TextField is to be empty
    `maxSize` - the maximum capacity in characters
    `constraints` - see input constraints
  Throws:
    IllegalArgumentException - if maxSize is zero or less
    IllegalArgumentException - if the value of 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 TextField as a string value.
  Returns:
    the current contents

### setString

    public void setString(String text)

  Sets the contents of the TextField as a string value, replacing the previous contents.
  Parameters:
    `text` - the new value of the TextField
  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 TextField 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 TextField 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 TextField 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

### insert

    public void insert(String src,
                       int position)

  Inserts a string into the contents of the TextField. 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 TextField. 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 determing 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 are illegal for the current input constraints
    IllegalArgumentException - if the insertion would exceed the current maximum capacity

### 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 TextField. 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)`.

  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 are illegal for the current input constraints
    IllegalArgumentException - if the insertion would exceed the current maximum capacity

### delete

    public void delete(int offset,
                       int length)

  Deletes characters from the TextField.

  Parameters:
    `offset` - the beginning of the region to be deleted
    `length` - the number of characters to be deleted
  Throws:
    StringIndexOutOfBoundsException - if offset and length do not specify a valid range within the contents of the TextField
    IllegalArgumentException - if the resulting contents are illegal for the current input constraints

### getMaxSize

    public int getMaxSize()

  Returns the maximum size (number of characters) that can be stored in this TextField.
  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 TextField. If the current contents of the TextField are larger than maxSize, the contents are truncated to fit.
  Parameters:
    `maxSize` - the new maximum size
  Throws:
    IllegalArgumentException - if maxSize is zero or less

### size

    public int size()

  Gets the number of characters that are currently stored in this TextField.
  Returns:
    number of characters in the TextField

### getCaretPosition

    public int getCaretPosition()

  Gets the current input position. For some UIs this may block some time and ask the user about the intended caret position, on some UIs may just return the caret position.
  Returns:
    the current caret position, 0 if in the beginning.

### setConstraints

    public void setConstraints(int constraints)

  Sets the input constraints of the TextField. If the the current contents of the TextField do not match the new constraints, the contents are set to empty.
  Parameters:
    `constraints` - see input constraints
  Throws:
    IllegalArgumentException - if constraints is not any of the ones specified in input constraints

### getConstraints

    public int getConstraints()

  Get the current input constraints of the TextField.
  Returns:
    the current constraints value (see input constraints)

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

Submit a comment or suggestion Version 0.95 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.