TextArea

TextArea component can be used for displaying and editing text. The text can be single-line or wrapped to multiple lines. A basic single-line TextArea can be created with following code:

TextArea textArea = new TextArea(“This is a text area! :)”);

Figure: Single-line TextArea

You can specify the amount of displayed rows and columns in the TextArea constructor, or you can use setRows() and setColumns() methods. The amount of columns is used as a hint for specifying the width of the TextArea, but with proportional fonts it is not entirely accurate. Note that some layout managers force the TextArea to fill all horizontal space, causing the set amount of columns to be ignored. 

TextArea textArea = new TextArea(“This is a text area. :)”, 20, 4);

Figure: Multi-line TextArea

If you want the TextArea to grow by its content, i.e. dynamically resize to have just the right amount of rows to display all the text at once, use method setGrowByContent(true). When this flag is set, the TextArea can grow beyond the limits set by the rows variable. This feature works only for multi-line TextAreas, so set the TextArea to have two rows or more before enabling this feature.

The TextArea is editable by default. If you use the TextArea for only displaying text, use setEditable(false) method. You can set the TextArea UIID to “Label” to copy the styling from the Label component.

Example:

TextArea textArea = new TextArea("This is a non-editable text area set to grow by content and its UIID set to \"Label\". 
It is useful for displaying long texts wrapping to multiple lines.", 2, 10);
textArea.setEditable(false);
textArea.setGrowByContent(true);
textArea.setUIID("Label");

Figure: Non-editable TextArea with “Label” UIID

TextArea in different Series 40 device types

On most Series 40 devices the LWUIT TextArea component uses the system native TextField implementation from Nokia UI package. The native editor is used to enable complex input methods (such as T9), text prediction and application internationalisation.

Figure 4 displays an example of a situation where the virtual keyboard is in T9 mode and in-place editing is used. The virtual keyboard pops up automatically when the TextArea is focused.

Figure: Editing TextArea in Series 40 full touch target in portrait orientation

Figure 5 displays an example of a situation where the virtual keyboard is in QWERTY mode and the text editing area fills the available screen space.

Figure: Editing TextArea in Series 40 full touch target in landscape orientation

Series 40 touch and type devices use in-place editing. The hardware keypad is used for text input. “Clear” command is available as right softkey function. See figure 6 for an example.

Figure: Editing TextArea in Series 40 touch and type target

In newer Series 40 non-touch devices, TextArea is integrated with Nokia TextEditor. In some Series 40 6th Edition phones, or phones with preceeding editions, TextArea pops up a dedicated editing screen, TextBox, when Edit mode is activated. See figure 7 for an example.

Figure: Editing TextArea in Series 40 non-touch phone that does not support Nokia TextEditor

TextArea Input Constraints

You can specify input constraints that are passed to the native text editor. The constraints are based on the LCDUI TextField API and hint what kind of input is allowed in the TextArea. The virtual keyboard changes its key layout according to the constraints, and the physical keyboard switches to a mode best suitable to the constraints.

  • ANY

    • Allows any type of input into a text field, if a constraint is not supported by an underlying implementation this will be the default.

  • EMAILADDR

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

  • NUMERIC

    • The user is allowed to enter only an integer value.

  • PHONENUMBER

    • The user is allowed to enter a phone number.

  • URL

    • The user is allowed to enter a URL.

  • DECIMAL

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

Example:

TextArea phoneNumberTextArea = new TextArea(1, 10, TextArea.PHONENUMBER);

Figure: Editing TextArea with PHONENUMBER constraint set

The constraints can be combined with additional input flags by bitwise OR’ing:

  • PASSWORD

    • Indicates that the text entered is confidential data that should be obscured whenever possible.

  • UNEDITABLE

    • Indicates that editing is currently disallowed.

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

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

  • INITIAL_CAPS_SENTENCE

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

  • INITIAL_CAPS_WORD

    • This flag is a hint to the implementation that during text editing, the initial letter of each word should be capitalised.

Example:

TextArea passwordInput = new TextArea(1, 10, TextArea.ANY | TextArea.PASSWORD);

Figure: Editing  TextField with PASSWORD flag set

Last updated March 14th, 2014

Feedback
© Nokia 2014.