5.5.2.1.37. TextArea
LIVE DEMO

TextArea is a multi-line text editor field.

XML-name of the component: textArea

TextArea component is implemented for both Web Client and Desktop Client.

TextArea mostly replicates the functionality of the TextField component and has the following specific attributes:

  • cols and rows set the number of columns and rows of text:

    <textArea id="textArea" cols="20" rows="5" caption="msg://name"/>

    The values of width and height have priority over the values of cols and rows.

  • resizableDirection – defines the way a user can change the size of the component, unless the percentage size is set for the component.

    <textArea id="textArea" resizableDirection="BOTH"/>
    gui textField resizable

    There are four resize modes available:

    • BOTH - the component is resizable in both directions. The component is not resizable if the percentage size is set for the component.

    • NONE - the component can not be resized.

    • VERTICAL - the component is resizable only vertically. The component can not be resized vertically if the percentage size is set for the component.

    • HORIZONTAL - the component is resizable only horizontally. The component can not be resized horizontally if the percentage width is set for the component.

    The area size change events can be tracked using the ResizeListener interface. For example:

    textArea.addResizeListener(e -> showNotification("Resized"));

  • wordwrap - set this attribute to false to turn off word wrapping.

TextArea supports TextChangeListener defined in its parent TextInputField interface. Text change events are processed asynchronously after typing in order not to block the typing.

textArea.addTextChangeListener(event -> {
    int length = event.getText().length();
    textAreaLabel.setValue(length + " of " + textArea.getMaxLength());
});
gui TextArea 2

The TextChangeEventMode defines the way the changes are transmitted to the server to cause a server-side event. There are 3 predefined event modes:

  • LAZY (default) - an event is triggered when there is a pause in editing the text. The length of the pause can be modified with setInputEventTimeout(). A text change event is forced before a possible ValueChangeEvent, even if the user did not keep a pause while entering the text.

  • TIMEOUT - an event is triggered after a timeout period. If more changes are made during this period, the event sent to the server-side includes the changes made up to the last change. The length of the timeout can be set with setInputEventTimeout().

    If a ValueChangeEvent would occur before the timeout period, a TextChangeEvent is triggered before it, on the condition that the text content has changed since the previous TextChangeEvent.

  • EAGER - an event is triggered immediately for every change in the text content, typically caused by a key press. The requests are separate and are processed sequentially one after another. Change events are nevertheless communicated asynchronously to the server, so further input can be typed while event requests are being processed.

    TextArea styles

    In Web Client with a Halo-based theme, you can set predefined styles to the TextArea component using the stylename attribute either in the XML descriptor or in the screen controller:

    <textArea id="textArea"
          stylename="borderless"/>

    When setting a style programmatically, select one of the HaloTheme class constants with the TEXTAREA_ prefix:

    textArea.setStyleName(HaloTheme.TEXTAREA_BORDERLESS);

    • align-center - align the text inside the area to center.

    • align-right - align the text inside the area to the right.

    • borderless - removes the border and background from the text area.

Attributes of textArea

align - caption - caseConversion - cols - datasource - datatype - description - editable - enable - height - icon - id - maxLength - property - required - requiredMessage - resizableDirection - rows - settingsEnabled - stylename - tabIndex - trim - visible - width - wordwrap

Predefined styles of textArea

align-center - align-right - borderless

API

addResizeListener - addTextChangeListener - addValueChangeListener - applySettings - commit - discard - isModified - saveSettings