File	Doc	Category	Size	Date	Package
TextField.java	API Doc	phoneME MR2 API (J2ME)	49751	Wed May 02 18:00:24 BST 2007	javax.microedition.lcdui

TextField

• java.lang.Object
  • Item

(408) 555-1212 

setInitialInputMode("MIDP_UPPERCASE_LATIN"); 

textfield.setInitialInputMode("UCB_HIRAGANA"); 

Fields Summary
public static final int	ANY The user is allowed to enter any text. Line breaks may be entered. Constant 0 is assigned to ANY.
public static final int	EMAILADDR The user is allowed to enter an e-mail address. Constant 1 is assigned to EMAILADDR.
public static final int	NUMERIC The user is allowed to enter only an integer value. The implementation must restrict the contents either to be empty or to consist of an optional minus sign followed by a string of one or more decimal numerals. Unless the value is empty, it will be successfully parsable using {@link java.lang.Integer#parseInt(String)}. The minus sign consumes space in the text object. It is thus impossible to enter negative numbers into a text object whose maximum size is 1. Constant 2 is assigned to NUMERIC.
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. Implementations may also provide a feature to look up the phone number in the device's phone or address database. The exact set of characters allowed is specific to the device and to the device's network and may include non-numeric characters, such as a "+" prefix character. Some platforms may provide the capability to initiate voice calls using the {@link javax.microedition.midlet.MIDlet#platformRequest MIDlet.platformRequest} method. Constant 3 is assigned to PHONENUMBER.
public static final int	URL The user is allowed to enter a URL. Constant 4 is assigned to URL.
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.
public static final int	PASSWORD Indicates that the text entered is confidential data that should be obscured whenever possible. The contents may be visible while the user is entering data. However, the contents must never be divulged to the user. In particular, the existing contents must not be shown when the user edits the contents. The means by which the contents are obscured is implementation-dependent. For example, each character of the data might be masked with a "*" character. The PASSWORD modifier is useful for entering confidential information such as passwords or personal identification numbers (PINs). Data entered into a PASSWORD field is treated similarly to SENSITIVE in that the implementation must never store the contents into a dictionary or table for use in predictive, auto-completing, or other accelerated input schemes. If the PASSWORD bit is set in a constraint value, the SENSITIVE and NON_PREDICTIVE bits are also considered to be set, regardless of their actual values. In addition, the INITIAL_CAPS_WORD and INITIAL_CAPS_SENTENCE flag bits should be ignored even if they are set. The PASSWORD modifier can be combined with other input constraints by using the bit-wise OR operator (|). The PASSWORD modifier is not useful with some constraint values such as EMAILADDR, PHONENUMBER, and URL. These combinations are legal, however, and no exception is thrown if such a constraint is specified. Constant 0x10000 is assigned to PASSWORD.
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.
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.
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.
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.
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.
public static final int	CONSTRAINT_MASK The mask value for determining the constraint mode. The application should use the bit-wise 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.
TextFieldLF	textFieldLF The look&feel associated with this TextField. Set in the constructor.
com.sun.midp.lcdui.DynamicCharacterArray	buffer buffer to store the text
int	constraints Input constraints
String	initialInputMode the initial input mode for when the text field gets focus

Constructors Summary
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. 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. param label item label param text the initial contents, or null if the TextField is to be empty param maxSize the maximum capacity in characters param constraints see input constraints throws IllegalArgumentException if maxSize is zero or less throws IllegalArgumentException if the value of the constraints parameter is invalid throws IllegalArgumentException if text is illegal for the specified constraints throws IllegalArgumentException if the length of the string exceeds the requested maximum capacity super(label); synchronized (Display.LCDUILock) { // IllegalArgumentException thrown here buffer = new DynamicCharacterArray(maxSize); // Constraint value is checked here. Since textFieldLF is not // yet created, no LF notification will happen. setConstraintsImpl(constraints); // Create a LF with empty content itemLF = textFieldLF = LFFactory.getFactory().getTextFieldLF(this); // this will use inputClient // Right now setCharsImpl notifies LF a content change. // If LF is created as an absolutely last thing then // setCharsImple here does not need the notification. if (text == null) { setCharsImpl(null, 0, 0); } else { setCharsImpl(text.toCharArray(), 0, text.length()); } }
TextField(String label, String text, int maxSize, int constraints, boolean forTextBox) Creates a new TextField object with the given label, initial contents, maximum size in characters, and constraints. Behaves the same as the public TextField constructor above except for an additional argument forTextBox which signals this TextField will be used alone as a TextBox widget. param label item label param text the initial contents, or null if the TextField is to be empty param maxSize the maximum capacity in characters param constraints see input constraints param forTextBox true if this textField will be used to implement a TextBox object. when false, this method's results are identical to the public TextField constructor. throws IllegalArgumentException if maxSize is zero or less throws IllegalArgumentException if the value of the constraints parameter is invalid throws IllegalArgumentException if text is illegal for the specified constraints throws IllegalArgumentException if the length of the string exceeds the requested maximum capacity super(label); synchronized (Display.LCDUILock) { // IllegalArgumentException thrown here buffer = new DynamicCharacterArray(maxSize); // Constraint value is checked here. Since textFieldLF is not // yet created, no LF notification will happen. setConstraintsImpl(constraints); if (forTextBox) { itemLF = textFieldLF = LFFactory.getFactory().getTextBoxLF(this); } else { // Create a LF with empty content itemLF = textFieldLF = LFFactory.getFactory().getTextFieldLF(this); } // // this will use inputClient // Right now setCharsImpl notifies LF a content change. // If LF is created as an absolutely last thing then // setCharsImple here does not need the notification. if (text == null) { setCharsImpl(null, 0, 0); } else { setCharsImpl(text.toCharArray(), 0, text.length()); } }

Methods Summary
boolean	acceptFocus() Return whether the Item takes user input focus. return Always return true so user can scroll or highlight selection. return true;
public void	delete(int offset, int length) Deletes characters from the TextField. The offset and length parameters must specify a valid range of characters within the contents of the TextField. 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(). param offset the beginning of the region to be deleted param length the number of characters to be deleted throws IllegalArgumentException if the resulting contents would be illegal for the current input constraints throws StringIndexOutOfBoundsException if offset and length do not specify a valid range within the contents of the TextField synchronized (Display.LCDUILock) { deleteImpl(offset, length); }
void	deleteImpl(int offset, int length) Deletes characters from the TextField. The offset and length parameters must specify a valid range of characters within the contents of the TextField. 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(). param offset the beginning of the region to be deleted param length the number of characters to be deleted throws IllegalArgumentException if the resulting contents would be illegal for the current input constraints throws StringIndexOutOfBoundsException if offset and length do not specify a valid range within the contents of the TextField if (length == 0) { return; } // Update buffer with latest user input textFieldLF.lUpdateContents(); // Keep old contents in case we need to restore below String oldContents = buffer.toString(); // StringIndexOutOfBoundsException can be thrown here buffer.delete(offset, length); if (!textFieldLF.lValidate(buffer, constraints)) { // Restore to old contents buffer.delete(0, buffer.length()); buffer.insert(0, oldContents); throw new IllegalArgumentException(); } // Notify LF that contents has changed due to delete textFieldLF.lDelete(offset, length);
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. return the current caret position, 0 if at the beginning synchronized (Display.LCDUILock) { return textFieldLF.lGetCaretPosition(); }
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. param data the character array to receive the value return the number of characters copied throws ArrayIndexOutOfBoundsException if the array is too short for the contents throws NullPointerException if data is null see #setChars synchronized (Display.LCDUILock) { textFieldLF.lUpdateContents(); try { buffer.getChars(0, buffer.length(), data, 0); } catch (IndexOutOfBoundsException e) { throw new ArrayIndexOutOfBoundsException(e.getMessage()); } return buffer.length(); }
public int	getConstraints() Gets the current input constraints of the TextField. return the current constraints value (see input constraints) see #setConstraints return constraints;
public int	getMaxSize() Returns the maximum size (number of characters) that can be stored in this TextField. return the maximum size in characters see #setMaxSize synchronized (Display.LCDUILock) { return buffer.capacity(); }
public java.lang.String	getString() Gets the contents of the TextField as a string value. return the current contents see #setString synchronized (Display.LCDUILock) { textFieldLF.lUpdateContents(); return buffer.toString(); }
public void	insert(java.lang.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 {@link #getCaretPosition() getCaretPosition()} method. For example, text.insert(s, text.getCaretPosition()) inserts the string s at the current caret position. param src the String to be inserted param position the position at which insertion is to occur throws IllegalArgumentException if the resulting contents would be illegal for the current input constraints throws IllegalArgumentException if the insertion would exceed the current maximum capacity throws NullPointerException if src is null synchronized (Display.LCDUILock) { // NullPointerException will be thrown by src.toCharArray insertImpl(src.toCharArray(), 0, src.length(), position); }
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 {@link #insert(String, int) 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. param data the source of the character data param offset the beginning of the region of characters to copy param length the number of characters to copy param 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 throws IllegalArgumentException if the resulting contents would be illegal for the current input constraints throws IllegalArgumentException if the insertion would exceed the current maximum capacity throws NullPointerException if data is null synchronized (Display.LCDUILock) { insertImpl(data, offset, length, position); }
void	insertImpl(char[] data, int offset, int length, int position) Inserts data into the buffer. param data - data to be inserted param offset - param length - param position - textFieldLF.lUpdateContents(); int pos = buffer.insert(data, offset, length, position); if (!textFieldLF.lValidate(buffer, constraints)) { buffer.delete(pos, length); // reverse insertion throw new IllegalArgumentException(); } // Notify LF contents has changed due a insertion textFieldLF.lInsert(data, offset, length, pos);
void	itemDeleted() Notify the item to the effect that it has been recently deleted. In addition to default action call TraverseOut for the TextField textFieldLF.itemDeleted(); super.itemDeleted();
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. 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. param data the source of the character data param offset the beginning of the region of characters to copy param length the number of characters to copy throws ArrayIndexOutOfBoundsException if offset and length do not specify a valid range within the data array throws IllegalArgumentException if data is illegal for the current input constraints throws IllegalArgumentException if the text would exceed the current maximum capacity see #getChars synchronized (Display.LCDUILock) { setCharsImpl(data, offset, length); }
void	setCharsImpl(char[] data, int offset, int length) Sets the contents of the TextField from a character array, replacing the previous contents. param data the source of the character data param offset the beginning of the region of characters to copy param length the number of characters to copy throws ArrayIndexOutOfBoundsException if offset and length do not specify a valid range within the data array throws IllegalArgumentException if data is illegal for the current input constraints throws IllegalArgumentException if the text would exceed the current maximum capacity if (data == null) { buffer.delete(0, buffer.length()); } else { if (offset < 0 || offset > data.length || length < 0 || length > data.length || offset + length < 0 || offset + length > data.length) { throw new ArrayIndexOutOfBoundsException(); } if (length > buffer.capacity()) { throw new IllegalArgumentException(); } if (length > 0) { DynamicCharacterArray dca = new DynamicCharacterArray(length); dca.set(data, offset, length); if (!textFieldLF.lValidate(dca, constraints)) { throw new IllegalArgumentException(); } } buffer.set(data, offset, length); } // Notify LF contents has changed due to setChars textFieldLF.lSetChars();
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. param constraints see input constraints throws IllegalArgumentException if constraints is not any of the ones specified in input constraints see #getConstraints synchronized (Display.LCDUILock) { setConstraintsImpl(constraints); }
void	setConstraintsImpl(int constraints) Sets the input constraints of the TextField. param constraints see input constraints throws IllegalArgumentException if constraints is not any of the ones specified in input constraints if ((constraints & CONSTRAINT_MASK) < ANY || (constraints & CONSTRAINT_MASK) > DECIMAL) { throw new IllegalArgumentException(); } this.constraints = constraints; // Since this function is called from Constructor before // LF is created, checking is necessary. if (textFieldLF == null) { return; } textFieldLF.lSetConstraints(); // If current contents doesn't satisfy new constraints, // set it to empty. textFieldLF.lUpdateContents(); int curLen = buffer.length(); if (curLen > 0 && !textFieldLF.lValidate(buffer, constraints)) { buffer.delete(0, curLen); textFieldLF.lDelete(0, curLen); }
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 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. param characterSubset a string naming a Unicode character subset, or null synchronized (Display.LCDUILock) { initialInputMode = characterSubset; textFieldLF.lSetInitialInputMode(initialInputMode); }
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. param maxSize the new maximum size return assigned maximum capacity - may be smaller than requested. throws IllegalArgumentException if maxSize is zero or less. throws IllegalArgumentException if the contents after truncation would be illegal for the current input constraints see #getMaxSize synchronized (Display.LCDUILock) { textFieldLF.lUpdateContents(); int oldCapacity = buffer.capacity(); if (oldCapacity == maxSize) { return maxSize; } buffer.setCapacity(maxSize); if (!textFieldLF.lValidate(buffer, constraints)) { buffer.setCapacity(oldCapacity); throw new IllegalArgumentException(); } // Notify LF that contents has changed due to maxSize textFieldLF.lSetMaxSize(maxSize); return buffer.capacity(); }
public void	setString(java.lang.String text) Sets the contents of the TextField as a string value, replacing the previous contents. param text the new value of the TextField, or null if the TextField is to be made empty throws IllegalArgumentException if text is illegal for the current input constraints throws IllegalArgumentException if the text would exceed the current maximum capacity see #getString synchronized (Display.LCDUILock) { if (text == null || text.length() == 0) { setCharsImpl(null, 0, 0); } else { setCharsImpl(text.toCharArray(), 0, text.length()); } }
public int	size() Gets the number of characters that are currently stored in this TextField. return number of characters in the TextField synchronized (Display.LCDUILock) { textFieldLF.lUpdateContents(); return buffer.length(); }