ValuePicker

ДЕМОНСТРАЦИЯ

Компонент ValuePicker отображает значение любого типа. Он состоит из текстового поля и набора кнопок, определяемых действиями.

ValuePicker является базовым классом для ValuesPicker, EntityPicker и EntityComboBox.

XML-имя компонента: valuePicker.

Основы

ValuePicker может иметь заголовок и как настраиваемые, так и предопределенные действия:

value picker1

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

<valuePicker id="valuePicker"
             caption="msg://code">
    <actions>
        <action id="generate"
                icon="REFRESH"
                description="msg://description"/>
        <action id="clear" type="value_clear"/>
    </actions>
</valuePicker>

Что бы создать ValuePicker, связанный с данными, используйте атрибуты dataContainer и property:

<data>
    <instance id="userDc"
              class="ui.ex1.entity.User">
        <fetchPlan extends="_base"/>
        <loader/>
    </instance>
</data>
<layout spacing="true">
    <vbox spacing="true" id="vBox">
        <valuePicker id="loginValuePicker"
                     caption="msg://ui.ex1.entity/User.login"
                     dataContainer="userDc"
                     property="login">
            <actions>
                <action id="generate" icon="REFRESH"/>
            </actions>
        </valuePicker>

В приведенном выше примере экран определяет контейнер данных userDc для сущности User с атрибутом login. В ValuePicker атрибут dataContainer содержит ссылку на контейнер данных userDc, а атрибут property включает имя атрибута сущности login.

По умолчанию пользователь не может ввести значение вручную. Если вы установите для атрибута fieldEditable значение true, вы включите ручной ввод. Имейте в виду, что введенное значение не соответствует модели данных. Для обработки пользовательского ввода используйте слушатель FieldValueChangeEvent.

Рассмотрим пример ниже. У нас есть сущность User с атрибутом age. Давайте определим ageValuePicker в XML-дескрипторе с помощью fieldEditable="true":

<valuePicker id="ageValuePicker"
             caption="msg://ui.ex1.entity/User.age"
             dataContainer="userDc"
             property="age"
             fieldEditable="true">
    <actions>
        <action id="clear" type="value_clear"/>
    </actions>
</valuePicker>

Теперь пользователь может ввести значение вручную. Чтобы обработать это значение, интерпретируемое как String, подпишитесь на FieldValueChangeEvent в контроллере:

@Autowired
private ValuePicker<Integer> ageValuePicker;

@Subscribe("ageValuePicker")
public void onAgeValuePickerFieldValueChange(ValuePicker.FieldValueChangeEvent<Integer> event) {
    String text = event.getText(); (1)
    notifications.create()
            .withCaption("Entered value: " + text)
            .show();
    if (!Strings.isNullOrEmpty(text)) {
        ageValuePicker.setValue(Integer.parseInt(text)); (2)
    }
}
1 Получите значение пользовательского ввода в виде строки.
2 Установите проанализированное значение в ageValuePicker.

Действия

Вы можете определить пользовательские и предопределенные действия для ValuePicker, отображаемые в виде кнопок справа. Это можно сделать либо в XML-дескрипторе, используя вложенный элемент actions, либо программно в контроллере, используя метод addAction().

Предопределенное действие

Фреймворком предоставляется только одно предопределенное действие – value_clear:

<action id="clear" type="value_clear"/>

Используйте атрибуты type и id для объявления предопределенного действия в XML.

Используйте addAction(), чтобы установить его программно:

@Autowired
protected ValuePicker<String> loginValuePicker;
@Autowired
protected Actions actions;

@Subscribe
protected void onInit(InitEvent event) {
    loginValuePicker.addAction(actions.create(ValueClearAction.ID));
}

Пользовательские действия

Чтобы определить пользовательское действие в XML, используйте вложенный элемент actions. Укажите атрибуты id и icon для action:

<valuePicker id="loginValuePicker"
             caption="msg://ui.ex1.entity/User.login"
             dataContainer="userDc"
             property="login">
    <actions>
        <action id="generate" icon="REFRESH"/>
    </actions>
</valuePicker>

Затем реализуйте пользовательскую логику в контроллере экрана, подписавшись на Action.ActionPerformedEvent:

@Subscribe("loginValuePicker.generate") (1)
protected void onLoginValuePickerGenerate(Action.ActionPerformedEvent event) {
    loginValuePicker.setValue(RandomStringUtils.randomAlphabetic(5, 10));
}
1 Аннотация @Subscribe содержит id компонента ValuePicker и id действия, разделенные точкой.

Валидация

Для проверки введенных в компонент ValuePicker значений можно использовать валидатор во вложенном элементе validators.

Для ValuePicker доступны следующие предопределенные валидаторы:

В приведенном ниже примере показано использование NotNullValidator для countryValidField:

<entityComboBox id="countryValidField"
                caption="Select a country"
                optionsContainer="countriesDc">
    <validators>
        <notNull/>
    </validators>
</entityComboBox>

События и слушатели

Чтобы сгенерировать заглушку слушателя в Jmix Studio, выберите компонент в XML-дескрипторе экрана или на панели иерархии Jmix UI и используйте вкладку Handlers на панели инспектора Jmix UI.

В качестве альтернативы вы можете воспользоваться кнопкой Generate Handler на верхней панели контроллера экрана.

ContextHelpIconClickHandler

См. ContextHelpIconClickHandler.

FieldIconProvider

См.FieldIconProvider.

FieldValueChangeEvent

См. FieldValueChangeEvent.

Formatter

См. Formatter.

Validator

Добавляет экземпляр validator к компоненту. Валидатор должен выбросить ValidationException, если значение если значение недопустимо.

Если вас не устраивают предопределенные валидаторы, добавьте свой собственный экземпляр валидатора:

@Install(to = "iconComboBox", subject = "validator")
protected void iconComboBoxValidator(FontAwesome icon) {
    if (icon != null)
        if (icon == FontAwesome.FILE_PDF_O)
            throw new ValidationException("The file type you selected " +
                    "is not currently supported");
}

ValueChangeEvent

См. ValueChangeEvent.

XML-атрибуты ValuePicker

Просматривать и редактировать атрибуты, применимые к компоненту, можно с помощью панели инспектора Jmix UI в конструкторе экранов Studio.

align - caption - captionAsHtml - css - description - descriptionAsHtml - enable - box.expandRatio - fieldEditable - htmlSanitizerEnabled - icon - id - stylename - tabIndex - visible - width

XML-элементы ValuePicker

actions - formatter - validator