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 TextField instance is constructed, 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 numeric characters to be entered.

The implementation is not required to do any syntactic validation of the contents of the text object. Applications must be prepared to perform such checking themselves.

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	DECIMAL The user is allowed to enter numeric values with optional decimal fractions, for example "-123", "0.123", or ".5".
static int	EMAILADDR The user is allowed to enter an e-mail address.
static int	INITIAL_CAPS_SENTENCE This flag is a hint to the implementation that during text editing, the initial letter of each sentence should be capitalized.
static int	INITIAL_CAPS_WORD This flag is a hint to the implementation that during text editing, the initial letter of each word should be capitalized.
static int	NON_PREDICTIVE Indicates that the text entered does not consist of words that are likely to be found in dictionaries typically used by predictive input schemes.
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	SENSITIVE Indicates that the text entered is sensitive data that the implementation must never store into a dictionary or table for use in predictive, auto-completing, or other accelerated input schemes.
static int	UNEDITABLE Indicates that editing is currently disallowed.
static int	URL The user is allowed to enter a URL.

Fields inherited from class javax.microedition.lcdui.Item

BUTTON, HYPERLINK, LAYOUT_2, LAYOUT_BOTTOM, LAYOUT_CENTER, LAYOUT_DEFAULT, LAYOUT_EXPAND, LAYOUT_LEFT, LAYOUT_NEWLINE_AFTER, LAYOUT_NEWLINE_BEFORE, LAYOUT_RIGHT, LAYOUT_SHRINK, LAYOUT_TOP, LAYOUT_VCENTER, LAYOUT_VEXPAND, LAYOUT_VSHRINK, PLAIN

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.
String	getLabel() Gets the label of this Item object.
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	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 TextField.
void	setLabel(String label) Sets the label of the Item.
int	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

addCommand, getLayout, getMinimumHeight, getMinimumWidth, getPreferredHeight, getPreferredWidth, notifyStateChanged, removeCommand, setDefaultCommand, setItemCommandListener, setLayout, setPreferredSize

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. The implementation must restrict the contents to consist of an optional minus sign followed by an optional string of numerals.

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. The exact set of characters allowed is specific to the device and to the device's network and may include non-numeric characters.

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.

DECIMAL

public static final int DECIMAL

The user is allowed to enter numeric values with optional decimal fractions, for example "-123", "0.123", or ".5".

The implementation may display a period "." or a comma "," for the decimal fraction separator, depending on the conventions in use on the device. Similarly, the implementation may display other device-specific characters as part of a decimal string, such as spaces or commas for digit separators. However, the only characters allowed in the actual contents of the text object are period ".", minus sign "-", and the decimal digits.

The actual contents of a DECIMAL text object may be empty. If the actual contents are not empty, they must conform to a subset of the syntax for a FloatingPointLiteral as defined by the Java Language Specification, section 3.10.2. This subset syntax is defined as follows: the actual contents must consist of an optional minus sign "-", followed by one or more whole-number decimal digits, followed by an optional fraction separator, followed by zero or more decimal fraction digits. The whole-number decimal digits may be omitted if the fraction separator and one or more decimal fraction digits are present.

The syntax defined above is also enforced whenever the application attempts to set or modify the contents of the text object by calling a constructor or a method.

Parsing this string value into a numeric value suitable for computation is the responsibility of the application. If the contents are not empty, the result can be parsed successfully by Double.valueOf and related methods if they are present in the runtime environment.

The sign and the fraction separator consume space in the text object. Applications should account for this when assigning a maximum size for the text object.

Constant 5 is assigned to DECIMAL.

Since:

MIDP 2.0

PASSWORD

public static final 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.

UNEDITABLE

public static final int UNEDITABLE

Indicates that editing is currently disallowed. When this flag is set, the implementation must prevent the user from changing the text contents of this object. The implementation should also provide a visual indication that the object's text cannot be edited. The intent of this flag is that this text object has the potential to be edited, and that there are circumstances where the application will clear this flag and allow the user to edit the contents.

The UNEDITABLE modifier can be combined with other input constraints by using the bit-wise OR operator (|).

Constant 0x20000 is assigned to UNEDITABLE.

Since:

MIDP 2.0

SENSITIVE

public static final int SENSITIVE

Indicates that the text entered is sensitive data that the implementation must never store into a dictionary or table for use in predictive, auto-completing, or other accelerated input schemes. A credit card number is an example of sensitive data.

The SENSITIVE modifier can be combined with other input constraints by using the bit-wise OR operator (|).

Constant 0x40000 is assigned to SENSITIVE.

Since:

MIDP 2.0

NON_PREDICTIVE

public static final int NON_PREDICTIVE

Indicates that the text entered does not consist of words that are likely to be found in dictionaries typically used by predictive input schemes. If this bit is clear, the implementation is allowed to (but is not required to) use predictive input facilities. If this bit is set, the implementation should not use any predictive input facilities, but it instead should allow character-by-character text entry.

The NON_PREDICTIVE modifier can be combined with other input constraints by using the bit-wise OR operator (|).

Constant 0x80000 is assigned to NON_PREDICTIVE.

Since:

MIDP 2.0

INITIAL_CAPS_WORD

public static final int INITIAL_CAPS_WORD

This flag is a hint to the implementation that during text editing, the initial letter of each word should be capitalized. This hint should be honored only on devices for which automatic capitalization is appropriate and when the character set of the text being edited has the notion of upper case and lower case letters. The definition of word boundaries is implementation-specific.

If the application specifies both the INITIAL_CAPS_WORD and the INITIAL_CAPS_SENTENCE flags, INITIAL_CAPS_WORD behavior should be used.

The INITIAL_CAPS_WORD modifier can be combined with other input constraints by using the bit-wise OR operator (|).

Constant 0x100000 is assigned to INITIAL_CAPS_WORD.

Since:

MIDP 2.0

INITIAL_CAPS_SENTENCE

public static final int INITIAL_CAPS_SENTENCE

This flag is a hint to the implementation that during text editing, the initial letter of each sentence should be capitalized. This hint should be honored only on devices for which automatic capitalization is appropriate and when the character set of the text being edited has the notion of upper case and lower case letters. The definition of sentence boundaries is implementation-specific.

If the application specifies both the INITIAL_CAPS_WORD and the INITIAL_CAPS_SENTENCE flags, INITIAL_CAPS_WORD behavior should be used.

The INITIAL_CAPS_SENTENCE modifier can be combined with other input constraints by using the bit-wise OR operator (|).

Constant 0x200000 is assigned to INITIAL_CAPS_SENTENCE.

Since:

MIDP 2.0

CONSTRAINT_MASK

public static final 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 or the maximum capacity actually assigned

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, or null if the TextField is to be made empty

Throws:

IllegalArgumentException - if the text is illegal for the current input constraints

IllegalArgumentException - if the text would exceed the current maximum capacity

Since:

JDE 4.0.2

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

NullPointerException - if data is null

Since:

JDE 4.0.2

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

Since:

JDE 4.0.2

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 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 are illegal for the current input constraints

IllegalArgumentException - if the insertion would exceed the current maximum capacity

NullPointerException - if src is null

Since:

JDE 4.0.2

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

NullPointerException - if data is null

Since:

JDE 4.0.2

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

Since:

JDE 4.0.2

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

Returns:

assigned maximum capacity - may be smaller than requested.

Throws:

IllegalArgumentException - if maxSize is zero or less.

Since:

JDE 4.0.2

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

Since:

JDE 4.0.2

getConstraints

public int getConstraints()

Get the current input constraints of the TextField.

Returns:

the current constraints value (see input constraints)

getLabel

public String getLabel()

Description copied from class: Item

Gets the label of this Item object.

Overrides:

getLabel in class Item

Following copied from class: javax.microedition.lcdui.Item

Returns:

the label string

setLabel

public void setLabel(String label)

Description copied from class: Item

Sets the label of the Item. If label is null, specifies that this item has no label.

Overrides:

setLabel in class Item

Since:

JDE 4.0.2

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