3.5.5.1. Декларативное создание действий

В XML-дескрипторе экрана для любого компонента, реализующего интерфейс Component.ActionsHolder, в том числе для всего экрана или фрейма, может быть задан набор действий. Делается это в элементе actions, который содержит вложенные элементы action.

Элемент action может иметь следующие атрибуты:

  • id − идентификатор, должен быть уникален в рамках данного компонента ActionsHolder.

  • caption - название действия.

  • description - описание действия.

  • enable - признак доступности действия (true / false).

  • icon - значок действия.

  • primary - атрибут, определяющий подсветку кнопок, обеспечивающих выполнение этого действия (true / false). Если выбрано true, для подсветки будет использован особый стиль.

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

    Следующие действия являются primary по умолчанию, если не установлено иное: create у табличных компонентов и lookupSelectAction в экранах выбора.

    actions primary

  • shortcut - комбинация клавиш для вызова.

    Комбинации можно жёстко задавать в XML-дескрипторе. Возможные модификаторы - ALT, CTRL, SHIFT - отделяются символом "-". Например:

    <action id="create" shortcut="ALT-N"/>

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

    <action id="edit" shortcut="${TABLE_EDIT_SHORTCUT}"/>

    • TABLE_EDIT_SHORTCUT

    • COMMIT_SHORTCUT

    • CLOSE_SHORTCUT

    • FILTER_APPLY_SHORTCUT

    • FILTER_SELECT_SHORTCUT

    • NEXT_TAB_SHORTCUT

    • PREVIOUS_TAB_SHORTCUT

    • PICKER_LOOKUP_SHORTCUT

    • PICKER_OPEN_SHORTCUT

    • PICKER_CLEAR_SHORTCUT

    Кроме того, есть возможность задавать комбинацию с помощью полного имени интерфейса Config и имени метода, возвращающего нужную комбинацию:

    <action id="remove" shortcut="${com.haulmont.cuba.client.ClientConfig#getTableRemoveShortcut}"/>

  • visible - признак видимости действия (true / false).

Рассмотрим примеры декларативного объявления действий.

  • Объявление действий на уровне экрана:

    <window>
    <actions>
        <action id="sayHello" caption="msg://sayHello" shortcut="ALT-T"/>
    </actions>

    <layout>
        <button action="sayHello"/>
    </layout>
</window>
    // controller
@Inject
private Notifications notifications;

@Subscribe("sayHello")
protected void onSayHelloActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
                .withCaption("Hello")
                .withType(Notifications.NotificationType.HUMANIZED)
                .show();
}

    Здесь объявляется действие с идентификатором sayHello и названием из пакета сообщений. С этим действием связывается кнопка, заголовок которой будет установлен в название действия. Контроллер экрана подписан на событие действия ActionPerformedEvent, так что метод onSayHelloActionPerformed() будет вызван при нажатии на кнопку, а также при нажатии комбинации клавиш ALT-T.

  • Объявление действий для PopupButton:

    <popupButton id="sayBtn" caption="Say">
    <actions>
        <action id="hello" caption="Say Hello"/>
        <action id="goodbye" caption="Say Goodbye"/>
    </actions>
</popupButton>
    // controller
@Inject
private Notifications notifications;

private void showNotification(String message) {
    notifications.create()
            .withCaption(message)
            .withType(NotificationType.HUMANIZED)
            .show();
}

@Subscribe("sayBtn.hello")
private void onSayBtnHelloActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
            .withCaption("Hello")
            .show();
}

@Subscribe("sayBtn.goodbye")
private void onSayBtnGoodbyeActionPerformed(Action.ActionPerformedEvent event) {
    notifications.create()
            .withCaption("Hello")
            .show();
}

  • Объявление действий для Table:

    <groupTable id="customersTable" width="100%" dataContainer="customersDc">
    <actions>
        <action id="create" type="create"/>
        <action id="edit" type="edit"/>
        <action id="remove" type="remove"/>
        <action id="copy" caption="Copy" icon="COPY" trackSelection="true"/>
    </actions>
    <columns>
        <!-- -->
    </columns>
    <rowsCount/>
    <buttonsPanel alwaysVisible="true">
        <!-- -->
        <button action="customersTable.copy"/>
    </buttonsPanel>
</groupTable>
    // controller

@Subscribe("customersTable.copy")
protected void onCustomersTableCopyActionPerformed(Action.ActionPerformedEvent event) {
    // ...
}

    Здесь помимо стандартных действий таблицы create, edit и remove объявлено действие copy. Для этого действия указан также атрибут trackSelection="true", в результате чего действие и связанная с ним кнопка становятся недоступными, если в таблице не выбрана ни одна строка. Это удобно, если действие предназначено для выполнения над текущей выбранной строкой таблицы.

  • Объявление действий для PickerField:

    <pickerField id="userPickerField" dataContainer="customerDc" property="user">
    <actions>
        <action id="lookup" type="picker_lookup"/>
        <action id="show" description="Show user" icon="USER"/>
    </actions>
</pickerField>
    // controller

@Subscribe("userPickerField.show")
protected void onUserPickerFieldShowActionPerformed(Action.ActionPerformedEvent event) {
    //
}

    В данном примере для компонента PickerField объявлено стандартное действие picker_lookup и дополнительное действие show. Так как в кнопках PickerField, отображающих действия, используются значки, а не надписи, атрибут caption явно установлен в пустую строку, иначе названием действия и заголовком кнопки стал бы идентификатор действия. Атрибут description позволяет отображать всплывающую подсказку при наведении мыши на кнопку действия.

Ссылки на любые декларативно объявленные действия можно получить в контроллере экрана либо непосредственно путем инжекции, либо из компонентов, реализующих интерфейс Component.ActionsHolder. Это может понадобиться для программной установки свойств действия. Например:

@Named("customersTable.copy")
private Action customersTableCopy;

@Inject
private PickerField<User> userPickerField;

@Subscribe
protected void onBeforeShow(BeforeShowEvent event) {
    customersTableCopy.setEnabled(false);
    userPickerField.getActionNN("show").setEnabled(false);
}