Пример текстового поля с заголовком, взятым из пакета локализованных сообщений:

<textField id="nameField" caption="msg://name"/>

В веб-клиенте с темой, основанной на Halo, к компоненту TextField можно применить предопределенные стили. Стили задаются в XML-дексрипторе или контроллере экрана с помощью атрибута stylename:

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

textField.setStyleName(HaloTheme.TEXTFIELD_INLINE_ICON);

Для создания текстового поля, связанного с данными, необходимо использовать атрибуты dataContainer и property.

<data>
    <instance id="customerDc" class="com.company.sales.entity.Customer" view="_local">
        <loader/>
    </instance>
</data>
<layout>
    <textField dataContainer="customerDc" property="name" caption="msg://name"/>
</layout>

Если поле не связано с атрибутом сущности (то есть не указан контейнер данных и название атрибута), то можно указать тип данных с помощью атрибута datatype. Тип данных используется для форматирования значения поля. В качестве значения атрибута может быть указано любое имя типа данных, зарегистрированного в метаданных приложения – см. Datatype. Как правило, в TextField используются следующие типы данных:

<textField id="integerField" datatype="int" caption="msg://integerFieldName"/>

databinding.conversion.error.int = Must be Integer

Вы можете определять пользовательские сообщения об ошибках конвертации декларативно, используя атрибут conversionErrorMessage в XML-дескрипторе:

<textField conversionErrorMessage="This field can work only with Integers" datatype="int"/>

textField.setConversionErrorMessage("This field can work only with Integers");

Текстовому полю может быть назначен валидатор - класс, реализующий интерфейс Field.Validator. Валидатор позволяет дополнительно к datatype ограничить вводимую пользователем информацию. Например, для создания поля ввода положительных целых чисел нужно создать класс валидатора:

public class PositiveIntegerValidator implements Field.Validator {
    @Override
    public void validate(Object value) throws ValidationException {
        Integer i = (Integer) value;
        if (i <= 0)
            throw new ValidationException("Value must be positive");
    }
}

<textField id="integerField" datatype="int">
    <validator class="com.sample.sales.gui.PositiveIntegerValidator"/>
</textField>

Компонент TextField поддерживает слушатель TextChangeListener, определённый в родительском интерфейсе TextInputField. События изменения текста обрабатываются асинхронно после ввода, не блокируя сам ввод.

textField.addTextChangeListener(event -> {
    int length = event.getText().length();
    textFieldLabel.setValue(length + " of " + textField.getMaxLength());
});
textField.setTextChangeEventMode(TextInputField.TextChangeEventMode.LAZY);

Параметром TextChangeEventMode задаётся режим передачи изменений на сервер для вызова события на серверной стороне. В платформе реализовано 3 режима передачи:

EnterPressListener позволяет указать действие, которое должно быть выполнено по нажатию клавиши Enter:

textField.addEnterPressListener(enterPressEvent ->
        notifications.create()
                .withCaption("Enter pressed")
                .show());

ValueChangeListener позволяет обрабатывать изменения значения в текстовом поле, когда пользователь уже закончил ввод, т.е. после нажатия клавиши Enter или при потере компонентом фокуса. В слушатель передается объект события типа ValueChangeEvent, который имеет следующие методы:

Если текстовое поле связано с атрибутом сущности (через dataContainer и property), и если для атрибута сущности в JPA-аннотации @Column указан параметр length, то TextField будет соответственно ограничивать максимальную длину вводимого текста.

<textField id="shortTextField" maxLength="10"/>

По умолчанию текстовое поле отсекает пробелы в начале и конце введенной строки. То есть если пользователь ввел строку " aaa bbb " то значением поля, возвращаемым методом getValue() и сохраняемым в связанный атрибут сущности, будет строка "aaa bbb". Для того, чтобы отключить отсечение пробелов, используйте атрибут trim со значением false.

Текстовое поле всегда вместо введенной пустой строки возвращает null. Соответственно, при включенном атрибуте trim строка, состоящая из одних пробелов также превратится в null.

Метод setCursorPosition() используется для установки позиции курсора в указанный индекс (начинается с 0). После вызова метода поле принимает фокус ввода.