Programming Wireless Devices with the Java2 Platform

9.2 TextBox

The TextBox class is a Screen that allows the user to enter and edit text. The input devices and input methods^[1] for the text entry differ dramatically from device to device. Many devices have only a numeric keypad, which allows text entry by repetitive tapping of the number keys. Also, there can be separate user-changeable input modes: for example, separate modes for entering text and numbers.

^[1] Input methods are software components that interpret user operations on input devices, such as typing keys, speaking, or writing using a pen device to generate text input.

Many numeric keypad devices have a more advanced input method called predictive input.^[2] If there are several alternate input methods available, the user can often select which input mode to use in the editor. Some MIDP devices may have full-character keyboards, and devices with touch screen often have on-screen virtual keyboards. The input methods differ also from language to language. For example, in Chinese devices there are several different input modes. These different methods are not directly visible to applications, but developers should bear in mind that in many devices the input of long character strings might be cumbersome or rather slow. In MIDP 2.0, an application now has more concrete control on the input modes used, as described later in this subsection.

^[2] Predictive input enables text entry with a numeric keypad using only one key press per letter in most common cases.

An application defines the maximum size of the TextBox, which is the maximum number of characters that the editor can contain. The application also sets the input constraints for the editor. These parameters are described in detail in the next section (Section 9.2.1, "Input Constraints.") The characters in the TextBox can be modified and retrieved by the application either as a String or a sequence of characters.

The capabilities of the device determine a limit on the maximum size. The maximum size available may be smaller than the application had requested. The maximum size value is returned from both the setMaxSize and getMaxSize methods. The TextBox constructor and methods that change the text contents throw an IllegalArgumentException if the contents exceed maximum size. This means that when the application needs to use some initial value in the TextBox, it should compare the value returned from getMaxSize to the size of the String that it intends to use in the TextBox.

A TextBox must have Commands added to it. Otherwise, the user will not be able to trigger any action and will be stuck in the TextBox.

This sample code illustrates the creation of a TextBox with an initialized editable phone number and two commands.

TextBox text = new TextBox("Phone",
                   "18005551212", 50,
                   TextField.PHONENUMBER);
text.addCommand(backCommand);
text.addCommand(okCommand);

9.2.1 Input Constraints

The application can set the input constraint individually for each TextBox. The constraints are defined in the TextField class (see Section 10.4, "TextField") but are also available in TextBoxes. The available input constraint are ANY, NUMERIC, DECIMAL, PHONENUMBER, URL, and EMAILADDR. The device can use the input constraints to make it easier for the user to input allowed characters or can use them to format the field value for display. This means that the available input modes are likely to be affected by the input constraints.

The NUMERIC and DECIMAL constraints force the contents to numerical values. For example, if the device has a specific input mode for numbers, then the editor is fixed to that mode. NUMERIC is used for entering integer numbers that are, however, returned to applications as strings. DECIMAL is a new constraint in MIDP Specification version 2.0. It is used for entering numerical values that might contain decimal fractions. PHONENUMBER is used for entering phone numbers. Other types are used for alphanumerical entry without any character restrictions other than those imposed by the device itself.

The ANY constraint is the most generic alphanumeric type for creating a generic text editor for entering free-form text. The input constraints EMAILADDR and URL allow the input of the same characters as ANY but give hints about the contents of the editor. These constraints do not automatically validate the format or syntax of the input but may be used by the device implementation to choose a better input mode: for example, automatic capitalization and predictive input may be turned off by default in EMAILADDR and URL editors.

The PHONENUMBER type constrains the entered characters to those available in phone numbers. The set of special characters in phone numbers differs from device to device and is likely based on the network standard for which the device is intended. In a PHONENUMBER TextBox, the numeric keypad can be automatically enabled for direct input of numbers, and the output can be formatted as a phone number using device-specific or network-specific formatting rules.

The text editor may also include device-specific operations. For instance, a PHONENUMBER TextBox may have an operation that allows the user to copy a phone number to be input to the editor from the device-specific phone book application. The device may also enable the "TALK" button on the phone to dial the number. This provides applications with a simple way to present a phone number to the user and to allow the user to dial that number.

There are additional modifiers for the input constraints. The input constraint modifiers are:

• PASSWORD: Used when confidential data needs to be entered. The device typically masks the data with a "*" character.

• UNEDITABLE: When this modifier is active, the user cannot edit the contents.

• SENSITIVE: Used to indicate that the text entered is sensitive and must never be stored in any auto-completion or predictive input dictionaries that the devices might normally use.

• NON_PREDICTIVE: Indicates that device should not use predictive input even if such an input method is available on the device. The mode can be used if the text to be entered is something that most likely cannot be entered with predictive input methods. The user interaction thus becomes more seamless, since the user does not need to turn predictive input off manually. On a device that does not have predictive input, this modifier is simply ignored.

• INITIAL_CAPS_WORD: Is a hint to the implementation that during text editing, the initial letter of each word should be capitalized. The flag is useful, for example, for entering names in an address book application.

• INITIAL_CAPS_SENTENCE: This flag is a hint to the implementation that during text editing, the initial letter of each sentence should be capitalized.

The modifiers are used by combining the set of modifiers with constraints using the bitwise OR operator. For example, the constraint "NUMERIC | PASSWORD" creates an editor that allows the input of numeric passwords only.

9.2.2 Input Modes

The application can request that the implementation use a particular input mode when the user initiates the editing of a TextBox. As described earlier, devices often have multiple input modes for text entry. These input modes allow easy text entry for certain types of text, such as numeric or lowercase alphabets, or specific modes for different languages. If the requested mode is not supported by the device, normal text entry mode is used.

The MIDP Specification does not try to specify all the possible input modes found in devices. Rather, the specification is based on the idea that the applications themselves define for which characters input should be made as convenient as possible. The input modes are identified by strings. The MIDP Specification defines standard rules for the input mode strings and specifies a set of concrete strings that may be used by devices. The specification also allows the set to be extended by the device implementations. The initial input mode is set with the method:

public void setInitialInputMode(String characterSubset)

This method allows the application to specify the input mode best suited for the editor. If a device supports the input mode, the TextBox is initially set to that mode, but the user may select another one from the device-specific menus.

Many of the input mode strings are based on Unicode character blocks. For example, the UCB_BASIC_LATIN input mode allows the easy input of Latin characters, and UCB_HIRAGANA is the input mode that is specific to the Japanese language Hiragana script characters. There are also input modes that define subsets of the Unicode blocks. For example, the following Latin-specific modes are available: MIDP_UPPERCASE_LATIN for uppercase mode, MIDP_LOWERCASE_LATIN for lowercase input mode, and IS_LATIN_DIGITS for Latin number entry.

The input mode settings have a lower priority than the input constraints. If the input constraint and input mode are in conflict, then the input mode is ignored. For example, if the constraint is set to NUMERIC and mode to MIDP_UPPERCASE_LATIN, the input mode is ignored and numeric input is activated.

Often an initial input mode is used simply with the input constraint ANY. In many cases, however, the input modes can be combined with constraints other than ANY. For example, the NUMERIC constraint together with UCB_ARABIC input mode initially sets the editor to number entry with Arabic-Indic digit input mode (if supported by the device.)