Button

Кнопка (Button) выполняет действия при нажатии пользователем.

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

Основы

У кнопки может быть текст, значок или и то и другое.

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

<button id="helloButton"
        caption="msg://button.caption"
        description="msg://button.description"/>

Название кнопки задается с помощью атрибута caption, всплывающая подсказка − с помощью атрибута description.

Для обработки нажатия на кнопку создайте слушатель события ClickEvent в контроллере экрана:

@Subscribe("helloButton")
private void onHelloButtonClick(Button.ClickEvent event) {
    // ...
}

Если атрибут disableOnClick имеет значение true, кнопка будет автоматически отключена после нажатия по ней. Обычно это делается для того, чтобы предотвратить случайные повторные нажатия. Впоследствии, можно снова включить кнопку вызовом метода setEnabled(true).

Атрибут icon указывает на местоположение значка в каталоге темы или имя элемента в используемом наборе значков. Подробную информацию о том, где следует располагать файлы значков, можно прочитать в разделе Значки.

Пример создания кнопки со значком:

<button id="saveButton"
        caption="Save"
        icon="SAVE"/>

Action

Другой способ обработки нажатий на кнопку – связать ее с интерфейсом Action:

<actions>
    <action id="someAction"
            caption="Click Me!"/>
</actions>
<layout>
    <vbox spacing="true">
        <button action="someAction"/>
</layout>

Кнопке можно назначить любое действие, определенное в окне или табличном компоненте (они реализуют интерфейс Component.ActionsHolder). В случае действия, определенном в окне, укажите id действия в атрибуте кнопки action, как в примере выше. В случае действия, определенном в компоненте, укажите id компонента и id действия, разделенные точкой. В следующем примере кнопка связана с действием create компонента usersTable:

<table id="usersTable"
       width="100%"
       dataContainer="usersDc">
    <actions>
        <action id="create"
                type="create"/>
    </actions>
    <buttonsPanel>
        <button id="usersTableCreateBtn"
                action="usersTable.create"/>
    </buttonsPanel>
</table>

Действие для кнопки можно также создавать программно, в контроллере экрана, используя наследование от класса BaseAction.

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

Перечисленные свойства будут взяты из Action только в том случае, если они не установлены в самом Button.

Shortcut

С помощью атрибута shortcut можно задать комбинацию клавиш для кнопки. Возможные модификаторы: ALT, CTRL, SHIFT – отделяются символом "-". Например:

<button id="saveButton2"
        description="Save"
        icon="SAVE"
        shortcut="ALT-S"/>

Предопределенные стили

Атрибут primary позволяет задать подсветку отдельных кнопок. Подсветка автоматически применится к кнопке, если у действия, вызываемого этой кнопкой, атрибут primary имеет значение true.

<button id="primaryBtn"
        caption="Primary button"
        primary="true"/>

В темах hover и helium подсветка доступна по умолчанию; для ее активации в теме, основанной на halo, установите значение true для переменной стиля $jmix-highlight-primary-action.

Предопределенные стили компонента Button задаются в XML-дескрипторе или контроллере экрана с помощью атрибута stylename:

<button id="styledBtn1"
        caption="Borderless"
        stylename="borderless"/>

Чтобы применить стиль программно, выберите одну из констант класса ThemeClassNames с префиксом BUTTON_:

styledBtn1.setStyleName(ThemeClassNames.BUTTON_BORDERLESS);

Предопределенные стили:

borderless - кнопка без полей. Совместим с любым другим стилем Button.

borderless-colored - кнопка без полей с цветной надписью. Совместим с любым другим стилем Button.

danger - выделенная кнопка, обозначающая действие, потенциально небезопасное для пользователя (которое, например, может вызвать потерю данных и прочие необратимые изменения). Совместим с любым другим стилем Button.

friendly - выделенная кнопка, обозначающая основное действие, безопасное для пользователя (например, не вызывающее потери данных и прочих необратимых изменений). Совместим с любым другим стилем Button.

icon-align-right - выравнивание значка по правому краю надписи. Совместим с любым другим стилем Button.

icon-align-top - расположение значка над надписью. Совместим с любым другим стилем Button.

icon-only - отображается только значок, кнопка квадратной формы.

primary - кнопка основного действия (например, кнопка, получающая фокус при нажатии кнопки Enter в форме ввода). Используйте внимательно, не более одной основной кнопки на представление.

quiet - "незаметная" кнопка, поля которой не видны до наведения указателя мыши. Совместим с любым другим стилем Button.

Внешний вид компонента Button можно настроить с помощью переменных SCSS с префиксом $jmix-button-*. Эти переменные можно изменить в визуальном редакторе после создания новой темы.

Метод Click

Метод click() интерфейса Button симулирует нажатие кнопки, уведомляя всех слушателей на стороне сервера. simulates a button click, notifying all server-side listeners.

Если кнопка отключена, никаких действий не предпринимается.

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

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

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

ClickEvent

ClickEvent отправляется при нажатии пользователем на кнопку.

@Subscribe("helloButton") (1)
private void onHelloButton1Click(Button.ClickEvent event) {
    Button button = event.getSource(); (2)
    // ...
}

1	Аннотация `@Subscribe` содержит id кнопки.
2	При необходимости нажатую кнопку можно получить из объекта события.

Чтобы создать слушателя этого события программно, используйте метод компонента addClickListener().

Все XML-атрибуты

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

action - align - caption - captionAsHtml - colspan - css - description - descriptionAsHtml - disableOnClick - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - primary - responsive - rowspan - shortcut - stylename - tabIndex - visible - width