listBox

listBox allows users to select a single value from a scrollable list of items.

XML Element

listBox

Java Class

JmixListBox

Basics

LIVE DEMO

A listBox can be populated programmatically with setItems(). Components such as separators can be inserted between particular items.

XML
<vbox width="AUTO">
    <h4 text="Simple ListBox"/>
    <listBox id="listBox"/>
</vbox>
<vbox width="AUTO">
    <h4 text="ListBox with separator"/>
    <listBox id="listBox2"/>
</vbox>
Java
@ViewComponent
protected JmixListBox<String> listBox;
@ViewComponent
protected JmixListBox<String> listBox2;

@Subscribe
protected void onInit(InitEvent event) {
    List<String> items = List.of("Jmix", "Vaadin", "SpringBoot", "EclipseLink");
    listBox.setItems(items);
    listBox2.setItems(items);

    listBox.setValue("Jmix");
    listBox2.setValue("Jmix");

    listBox2.addComponents("Vaadin", new Hr());
}

Items from a Data Container

LIVE DEMO

Use itemsContainer to populate the component with entities from a collection data container.

<data>
    <collection id="productsDc"
                class="io.jmix.uisamples.entity.Product"
                fetchPlan="_local">
        <loader id="productsDl">
            <query>
                <![CDATA[select e from Product e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
<layout>
    <listBox itemsContainer="productsDc"/>
</layout>

Enumeration Items

Use itemsEnum to populate listBox with the values of an enumeration:

<listBox itemsEnum="com.company.onboarding.entity.OnboardingStatus"/>

Disabled Items

LIVE DEMO

itemEnabledProvider is applied to each item of this listBox to determine whether the item should be enabled (true) or disabled (false). Disabled items are displayed as grayed out and the user cannot select them. All the items are enabled by default.

Imagine listBox displaying a list of users. You want to display only users that have the "Completed" onboarding status as enabled, while users with "In progress" or "Not started" status should be disabled.

@ViewComponent
protected JmixListBox<Product> listBox;

@Subscribe
protected void onInit(InitEvent event) {
    initListBox();
}

protected void initListBox() {
    listBox.setItems(getListBoxItems());
    listBox.setItemEnabledProvider(product -> product.count() > 0);
}

@Supply(to = "listBox", subject = "renderer")
protected ComponentRenderer<Text, Product> listBoxRenderer() {
    return new ComponentRenderer<>(product -> new Text(product.getDisplayName()));
}

protected Collection<Product> getListBoxItems() {
    return List.of(
            new Product("TV set", 4),
            new Product("Keyboard", 13),
            new Product("Earphones", 0),
            new Product("Telephone", 23),
            new Product("Laptop", 0)
    );
}

In this example, itemEnabledProvider checks the status of each user. Only users with OnboardingStatus.COMPLETED will be displayed as enabled in listBox.

Rendering Items

LIVE DEMO

The framework provides flexibility in customizing the rendering of items. You can use either the setRenderer() method or the @Supply annotation to achieve this.

XML
<layout classNames="list-box-custom-renderer">
    <listBox id="listBox"/>
</layout>
Java
protected static final String PATH_PREFIX = "/META-INF/resources/icons/";

@ViewComponent
protected JmixListBox<Simpson> listBox;

@Autowired
protected UiComponents uiComponents;
@Autowired
protected Resources resources;

@Subscribe
protected void onInit(InitEvent event) {
    listBox.setItems(getListBoxItems());
}

@Supply(to = "listBox", subject = "renderer")
protected ComponentRenderer<HorizontalLayout, Simpson> listBoxRenderer() {
    return new ComponentRenderer<>(simpson -> {
        HorizontalLayout row = uiComponents.create(HorizontalLayout.class);
        row.setAlignItems(FlexComponent.Alignment.CENTER);

        Avatar avatar = uiComponents.create(Avatar.class);
        avatar.setImageHandler(getSimpsonImageHandler(simpson));

        Span name = new Span(simpson.name());
        Span shortName = new Span(simpson.shortName());
        shortName.addClassNames("short-name");

        VerticalLayout column = uiComponents.create(VerticalLayout.class);
        column.add(name, shortName);
        column.setPadding(false);
        column.setSpacing(false);

        row.add(avatar, column);
        row.addClassName("row");
        return row;
    });
}

protected List<Simpson> getListBoxItems() {
    return List.of(
            new Simpson("Homer Jay Simpson", "Homer", "homer-simpson.png"),
            new Simpson("Marjorie Jacqueline Simpson", "Marge", "marge-simpson.png"),
            new Simpson("Bartholomew Jojo Simpson", "Bart", "bart-simpson.png")
    );
}

protected DownloadHandler getSimpsonImageHandler(Simpson simpson) {
    String picture = simpson.picture();
    return DownloadHandler.forClassResource(getClass(), PATH_PREFIX + picture);
}

Alternatively, you can render items using a nested fragmentRenderer element. Refer to the Fragment Renderer section for more information.

Attributes

The following attributes are specific to listBox:

Name Description Default

itemsContainer

Sets the items container.

—

itemsEnum

Sets the items enum.

—

The following shared attributes are supported by listBox:

id - alignSelf - ariaLabel - ariaLabelledBy - classNames - colspan - css - enabled - height - maxHeight - maxWidth - minHeight - minWidth - readOnly - visible - width

Handlers

The following handlers are specific to listBox:

Name Description

itemEnabledProvider

Determines whether each item is enabled. See Disabled Items.

itemsLabelGenerator

Provides the text shown for each item.

renderer

Provides the component used to render each item. See Rendering Items.

The following shared handlers are supported by listBox:

AttachEvent - ComponentValueChangeEvent - DetachEvent

Elements

A listBox can include fragmentRenderer and tooltip as its nested elements.

See Also