3.5.2.1.3. Button
ДЕМОНСТРАЦИЯ
API DOCS

Кнопка (Button) − компонент, обеспечивающий выполнение действия при нажатии.

Button

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

Кнопка может содержать текст или значок (или и то и другое). На рисунке ниже отображены разные виды кнопок.

gui buttonTypes

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

<button id="textButton" caption="msg://someAction" description="Press me"/>

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

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

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

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

<button id="iconButton" caption="" icon="SAVE"/>

Основная функция кнопки − выполнить некоторое действие при нажатии на нее. Определить метод контроллера, который будет вызываться при нажатии на кнопку, можно с помощью атрибута invoke. Значением атрибута должно быть имя метода контроллера, удовлетворяющего следующим условиям:

  • Метод должен быть public.

  • Метод должен возвращать void.

  • Метод должен либо не иметь аргументов, либо иметь один аргумент типа Component. Если метод имеет аргумент Component, то при вызове в него будет передан экземпляр вызвавшей кнопки.

В качестве примера показано описание кнопки, вызывающей метод someMethod:

<button invoke="someMethod" caption="msg://someButton"/>

В контроллере экрана необходимо определить метод someMethod:

public void someMethod() {
    //some actions
}

Атрибут invoke игнорируется, если для кнопки задан атрибут action. Атрибут action содержит имя действия, соответствующего данной кнопке.

Пример кнопки с атрибутом action:

<actions>
    <action id="someAction" caption="msg://someAction"/>
</actions>
<layout>
    <button action="someAction"/>
</layout>

Кнопке можно назначить любое действие, имеющееся в каком-либо компоненте, реализующем интерфейс Component.ActionsHolder (это актуально для Table, GroupTable, TreeTable, Tree). Причем неважно, каким образом эти действия добавлены - декларативно в XML-дескрипторе или программно в контроллере. В любом случае для использования такого действия достаточно в атрибуте action указать через точку имя компонента и идентификатор нужного действия. Например, в следующем примере кнопке назначается действие create таблицы coloursTable:

<button action="coloursTable.create"/>

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

Если для Button установлен экземпляр Action, то кнопка возьмет из него следующие свои свойства: caption, description, icon, enable, visible. Свойства caption, description и icon будут проставлены из действия только в том случае, если они не установлены в самом Button. Остальные перечисленные свойства действия имеют безусловный приоритет над свойствами кнопки.

Если свойства действия меняются уже после установки этого Action для Button, то соответственно меняться будут и свойства Button, то есть кнопка слушает изменение свойств действия. В этом случае меняются и свойства caption, description и icon, причем даже если они изначально были назначены на саму кнопку.
Стили компонента Button

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

<button primary="true"
        invoke="foo"/>

В теме Hover подсветка доступна по умолчанию; для её активации в теме, основанной на Halo, установите значение true для переменной стиля $cuba-highlight-primary-action.

actions primary

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

<button id="button"
        caption="Friendly button"
        stylename="friendly"/>

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

button.setStyleName(HaloTheme.BUTTON_FRIENDLY);

  • borderless - кнопка без полей.

  • borderless-colored - кнопка без полей с цветной надписью.

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

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

  • icon-align-right - выравнивание значка по правому краю надписи.

  • icon-align-top - расположение значка над надписью.

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

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

  • quiet - "незаметная" кнопка, поля которой не видны до наведения указателя мыши.

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

Атрибуты button

action - align - caption - captionAsHtml - css - description - descriptionAsHtml - disableOnClick - enable - box.expandRatio - icon - id - invoke - stylename - tabIndex - visible - width

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

borderless - borderless-colored - danger - friendly - huge - icon-align-right - icon-align-top - icon-only - large - primary - quiet - small - tiny