3.5.2.1.7. CheckBox
LIVE DEMO
API DOCS

CheckBox is a component with two states: selected or deselected.

CheckBox

Component’s XML-name: checkBox.

An example of a checkbox with a label retrieved from a localized messages pack:

<checkBox id="accessField" caption="msg://accessFieldCaption"/>

Selecting / deselecting of the checkbox changes its value: Boolean.TRUE or Boolean.FALSE. The value can be retrieved using getValue() method and set using setValue(). Submitting null using setValue() will change the value to Boolean.FALSE and uncheck the checkbox.

Changes of the checkbox value, as well as of any other components implementing the Field interface, can be tracked using a ValueChangeListener. The origin of the ValueChangeEvent can be tracked using isUserOriginated() method. For example:

@Inject
private CheckBox accessField;
@Inject
private Notifications notifications;

@Subscribe
protected void onInit(InitEvent event) {
    accessField.addValueChangeListener(valueChangeEvent -> {
        if (Boolean.TRUE.equals(valueChangeEvent.getValue())) {
            notifications.create()
                    .withCaption("set")
                    .show();
        } else {
            notifications.create()
                    .withCaption("not set")
                    .show();
        }
    });
}

The dataContainer and property attributes should be used to create a checkbox associated with data.

<data>
    <instance id="customerDc" class="com.company.sales.entity.Customer" view="_local">
        <loader/>
    </instance>
</data>
<layout>
    <checkBox dataContainer="customerDc" property="active"/>
</layout>

According to the example the screen includes the description of customerDc data container for a Customer entity with active attribute. The dataContainer attribute of the checkBox component should contain a reference to a data container; the property attribute should contain the name of an entity attribute which value should be displayed in the checkbox. The attribute should have Boolean type. If the attribute value is null the checkbox is deselected.

The appearance of the CheckBox component can be customized using SCSS variables with $cuba-checkbox-* prefix. You can change these variables in the visual editor after creating a theme extension or a custom theme.

Attributes of checkBox

align - caption - captionAsHtml - contextHelpText - contextHelpTextHtmlEnabled - css - dataContainer - description - descriptionAsHtml - editable - enable - box.expandRatio - height - htmlSanitizerEnabled - icon - id - property - stylename - tabIndex - visible - width

API

addValueChangeListener commit - discard - isModified - setContextHelpIconClickHandler