3.5.2.1.45. TextArea

TextArea is a multi-line text editor field.

XML-name of the component: textArea.

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.

  • 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
  • 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 setTextChangeTimeout() or using the textChangeTimeout attribute. 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 setTextChangeTimeout() or using the textChangeTimeout attribute.

      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.

  • textChangeTimeout defines the time of the pause in editing the text or a timeout period, when the textChangeEventMode is LAZY or TIMEOUT.

    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.