TextBox

TextBox is a text editor that takes up the whole main pane, operating effectively in full screen mode. Contents are automatically wrapped around from one row to the next.

Since Java Runtime 2.1 for Symbian, TextBox is shown as pop-up TextBoxes as default. On devices that support Java Runtime 1.3 for S60 or newer, TextBoxes can also be created as pop-up TextBoxes.

A TextBox can have input constraints, such as PASSWORD, which obscures the actual characters that are being typed.

A TextBox turns automatically active, when it becomes the foreground Displayable or when it resumes input focus. TextBox supports copy and paste functionality.

Figure: Example of a full screen TextBox

Source codes for the example:

Needed JAD attribute for fullscreen TextBox

Nokia-UI-Enhancement: FullScreenTextBox

MIDlet source code

import javax.microedition.midlet.*;
import javax.microedition.lcdui.*;

public class ExampleTextbox extends MIDlet {    
   Display display = Display.getDisplay(this);    
 
   public void startApp()     
      
    // TextBox(title, text, size, contrains)        
    TextBox textbox = new TextBox("TextBox Example", "This is an example of a TextBox.\n"
            +"It has several lines of text.\n"
            +"\n"
            +"Lines that do not fit on the screen will be divided into two or more lines.", 255, 0);
    display.setCurrent(textbox);    
   }
   public void pauseApp() {
   }
   public void destroyApp(boolean unconditional) {
   }
}

TextBox and TextField with input constraint TextField.ANY support input of the set of characters as specified by item 42 in the Change Log Section on Page 9 of the JSR 118 specifications.

TextBox and TextField have an upper limit on the maximum number of characters that can be stored in them. For the Series 40 platform this is set to 5000 characters.

Additional operations such as text selecting, text copying and pasting are not available in Series 40.

Keyboard support

The support for a full keyboard in TextBoxes works in the same way as that of text input in native editors. Note, however, that some of the text constraints are meaningless in full keyboard editors:

Full keyboard editors do not always have automatic casing functionality so, for example, INITIAL_CAPS_WORD and INITIAL_CAPS_SENTENCE are ignored in them.
Since predictive text input (T9) is always turned off (or completely unavailable) in full keyboard input, the NON_PREDICTIVE mode does not have any effect on the editor.
In devices that allow swapping from full keyboard mode to numeric keypad and vice versa, these constraints work as expected in numeric keypad mode.
Symbian platform supports copy/paste functionality.

Pop-up TextBox

Pop-up TextBoxes are supported in devices that include Java Runtime 1.3 for S60 or newer. For more information, see section pop-up TextBoxes.

New lines

On Symbian devices, the user can insert line separators to the editor. Each line separator forces a single line break in the editor. This is visible as an LF character (\n, U+000A) in TextBox/TextField getString or getChars(char[]). TextBox/TextField can handle all new line character combinations defined in section New line handling.

Constraints and modifiers

The following tables present the different possible TextBox modifiers and constraints.

**Table:** Editing styles used with different input constraints
TextBox modifier	Basic editing style
`ANY`	Normal, unconstrained editing. All input modes are possible. Predictive text input method is possible.
`URL` or `EMAILADDR`	Alpha Editing in special URL / email address entry mode. Only character set constraint is that enter key is ignored (no line feed character). Automatic case capitalization modes such as text case mode are disabled. Predictive text input method is disabled.
`PHONENUMBER`	Phone number entry (standard number mode). If an application programmatically adds a `String` that contains invalid characters, the invalid characters are removed from the string before the number is presented. Predictive text input method is disabled.
`NUMERIC`	Basic number editing: Predictive text input method is disabled. the allowed characters are minus sign '-' in the beginning and number characters (0-9). In ITU-T keypad, minus sign is entered with Asterisk key that toggles the minus sign in the front of the string; for entering numbers, the user can move the insertion point. In QWERTY keyboard, the same happens with ‘-‘ key. Locale-specific number modes are accessible (for example an Arabic UI language device would allow changing the number entry mode between Latin number mode and Arabic-Indic digits entry).
`DECIMAL`	As defined in MIDP 2.1 API specification. Only a decimal separator (period "." or comma “,”),the minus sign "-", and the decimal digits are allowed in the application-visible text property of `TextBox/TextField`; i.e. when passed to `TextField` or `TextBox` programmatically or returned to the application.

**Table:** TextBox/TextField input constraint modifiers
Input constraint modifier	Supported with Input Constraints	Description of modifier
`PASSWORD`	All	Text entered into `TextBox/TextField` is confidential data that is obscured. Entered characters as masked with ‘*’ characters to protect the content from outsiders. Automatic case changing is disabled. Predictive text input method is disabled.
`UNEDITABLE`	All	The contents of `TextBox/TextField` are not user-editable, but the cursor is visible. When user tries to edit the text, normal key press tone is generated. Editing space indicator is not shown.
`INITIAL_CAPS_SENTENCE`	`ANY`, but not with `ANY \| PASSWORD`.	The modifier sets the editor’s initial case mode to text case. The user is allowed to change the mode. If predictive text input method is supported in the implementation, it is possible to use it also in an `INITIAL_CAPS_SENTENCE` type editor. If the current input language does not have the concept of capitals, this modifier is simply ignored. The modifier is used if the input mode changes to a language with capital letters.
`INITIAL_CAPS_WORD`	None. This is not supported. If the user tries to set this modifier, the attempt is ignored.	The modifier sets the editor’s initial case mode to title case.
`NON_PREDICTIVE` or `SENSITIVE`	`ANY`	Disables predictive text input method.

Interaction with phonebook/contact list

The JTWI Specification mandates access to device phone book from a PHONENUMBER type TextBox/TextField.

If the focus is on a TextField or TextBox with a PHONENUMBER type, the user interface allows the user to activate a feature that allows him/her to select a single phone number from the system phonebook or contacts database.
The selected phone number replaces the contents of TextBox/TextField. This feature uses a system-specific UI for the phone number fetch.
If the UNEDITABLE constraint is set, the phonebook fetch operation is not visible in the UI.

If the focus is on a TextField or TextBox with the EMAILADDR type, the user interface allows the user to activate a feature that allows him/her to select a single e-mail address from the system phone book or contacts database.
The selected address replaces the contents of TextBox/TextField. This feature uses system-specific UI for the phone number fetch.
If the UNEDITABLE constraint is set, then the phone book fetch operation is not visible in the UI.

Initial input modes

MIDlet can set the initial input mode by calling the setInitialInputMode(String characterSubset) method.

The parameter characterSubset is a character subset specifier string, which can be a Unicode character block name (java.lang.Character.UnicodeBlock), an input subset as defined by the Java SE class java.awt.im.InputSubset, or a MIDP-defined subset.

**Table:** The effect of MIDP input modes on the editing style of the native text editor component used in the implementation.
		Editor (native) properties
MIDP input mode	Local input language	Input mode	Casing
`IS_LATIN`	If the common input language or the display language in the device is a Latin language, that language is used as the local input language, otherwise English is used.	Latin text input mode; in Japanese, half width Latin mode	Text case
`IS_LATIN_DIGITS`	Input language is not changed.	Number input mode	-
`MIDP_UPPERCASE_LATIN`	See `IS_LATIN`	See `IS_LATIN`	Upper case
`MIDP_LOWERCASE_LATIN`	See `IS_LATIN`	See `IS_LATIN`	Lower case
`UCB_BASIC_LATIN`	See `IS_LATIN`	See `IS_LATIN`	Text case
`UCB_GREEK`	Greek	Text input mode	Text case
`UCB_CYRILLIC`	If the common input language or the display language in the device is a Cyrillic language, that language is used as the local input language, otherwise Russian is used.	Text input mode	Text case
`UCB_HEBREW`	Hebrew	Text input mode	-
`UCB_ARABIC`	If the common input language or the display language in the device is an Arabic language, that language is used as the local input language, otherwise Arabic is used.	Text input mode	-
`UCB_THAI`	Thai	Text input mode	-
`UCB_HIRAGANA`	Japanese	Hiragana/kanji input mode	-
`UCB_KATAKANA`	Japanese	Katakana input mode, full width	-
`IS_HALFWIDTH_KATAKANA`	Japanese	Katakana input mode, half width	-
`IS_KANJI`	Japanese	Hiragana/kanji input mode	-
`IS_FULLWIDTH_DIGITS`	Japanese	Number input mode, full width	-
`IS_FULLWIDTH_LATIN`	Japanese	Latin input mode, full width	Text case
`IS_SIMPLIFIED_HANZI`	Chinese Simplified (Peoples Republic of China)	The default input method, which normally is Pinyin but the user may have changed it in General Settings.	-
`IS_TRADITIONAL_HANZI`	If the common input language or the display language in the device is a Traditional Hanzi language, that language is used as the local input language, otherwise the local input language is not changed.	The default input method, which normally is Stroke for Hong Kong and Zhuyin for Taiwan but the user may have changed it in General Settings.	-

Note: Automatic character casing modes (such as text case) are not used with constraints EMAILADDR, URL or PASSWORD, although mentioned in the above table.

For information on TextBox implementation in Touch UI -enabled devices, see section Displayables and commands.