Button

A button performs an action when a user clicks on it.

Component’s XML-name: button

Basics

Buttons can have a caption, an icon, or both:

button

An example of defining a button with a caption and a tooltip retrieved from localized messages:

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

The button’s caption is set using the caption attribute, the tooltip – using the description attribute.

If the disableOnClick attribute is set to true, the button will be automatically disabled when clicked, typically to prevent (accidental) extra clicks on a button. You can later re-enable the button by invoking the setEnabled(true) method.

The icon attribute defines icon location in the theme catalog or the icon name in the icon set. See Icons for more information on working with icons.

Example of creating a button with an icon:

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

Click Handler

You can handle button clicks in the screen controller by subscribing to Button.ClickEvent:

@Subscribe("helloButton") (1)
protected void onHelloButtonClick(Button.ClickEvent event) {
    Button button = event.getSource(); (2)
    // ...
}
1 The @Subscribe annotation contains the button id.
2 If needed, you can get the clicked button from the event object.

Action

Another way of handling button clicks is associating the button with an Action:

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

You can associate a button with any action defined in the window or in a table-like component (they implement Component.ActionsHolder interface). In case of window action, specify the action id in the action attribute of the button, as in the example above. In case of a component, specify the component id and the id of the action separated by a dot. In the next example a button is associated with the create action of the usersTable component:

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

Button actions can also be created programmatically in the screen controller by deriving them from BaseAction class.

If an Action instance is set for a Button, the following Button properties have priority over the Action properties:

All listed properties will be imported from Action only if they are not set in the Button itself.

Shortcut

The shortcut attribute is used to specify a key combination for a button. Possible modifiers: ALT, CTRL, SHIFT - are separated by the "-" character. For example:

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

Predefined Styles

TODO