Lists

Open in ChatGPT

info

This section describes common features of all list components, and isn't a class that can be instantiated or used directly.

There are three types of lists available for use within your apps: ListBox, ChoiceBox, and ComboBox. These components all display a list of key-value items, and provide methods to add, remove, select, and manage the items within the list.

This page outlines the shared features and behavior of all list components, while specific details for each are covered in their respective pages.

Using ListItem

List components are composed of ListItem objects, which represent individual items within a list. Each ListItem is associated with a unique key and display text. Important features of the ListItem class include:

• A ListItem encapsulates a unique key Object and a text String to display within the list component.
• You can construct a ListItem by providing a key and text, or by specifying only the text so that a random key is generated.

Managing ListItem objects with the API

The various List components offer several methods for managing the list of items and maintaining a consistent state between the list and the client. By using these methods, you can effectively manage the items within the list. The API allows you to interact with and manipulate the list to meet your app's requirements.

Adding items

• Adding an item:

  • To add a ListItem to the list, you can use the add(ListItem item) method.
  • You can also add a new ListItem by specifying the key and text using the add(Object key, String text) or add(String text) method.

• Inserting an item at a specific index:

  • To insert an item at a specific index, use the insert(int index, ListItem item) method.
  • You can insert an item with key and text using the insert(int index, Object key, String text) or insert(int index, String text) method.

• Inserting multiple items:

  • You can insert multiple items at a specified index using the insert(int index, List< ListItem > items) method.

tip

To optimize performance, instead of triggering a server-to-client message each time you use the add() method, it's more efficient to create a List of ListItem objects first. Once you have this list, you can add them all at once using the insert(int index, List<ListItem> items) method. This approach reduces server-client communication, enhancing overall efficiency. For detailed guidelines on this and other best practices in webforJ architecture, refer to Client/Server Interaction.

Removing items

• Removing an item:

  • To remove an item from the list, use the remove(int index) or remove(Object key) method.

• Removing all items:

  • You can remove all items from the list using removeAll().

Selecting items

All of the list types implement the SelectableList interface. This interface allows multiple different ways of selecting the current ListItem.

With a given ListItem

select(ListItem item) takes a ListItem as parameter to select.

List demoList = new List();
ListItem demoItem = new ListItem("demo","Demo Item");
demoList.add(demoItem);
demoList.select(demoItem);

With a given key of a ListItem

selectKey(Object key) takes a key to a ListItem as parameter to select.

List demoList = new List();
demoList.add("demo","Demo Item");
demoList.selectKey("demo");

With a given index of a ListItem

selectIndex(int index) takes an index to a ListItemas a parameter to select.

List demoList = new List();
demoList.add("demo","Demo Item");
demoList.selectKey(0);

Other list operations

• Accessing and updating items:

  • To access items by key or index, use getByKey(Object key) or getByIndex(int index).
  • You can update the text of an item using the setText(String text) method within the ListItem class.

• Retrieving information about the list:

  • You can get the size of the list using the size() method.
  • To check if the list is empty, use the isEmpty() method.

Iterating over lists

All List components implement the Java Iteratable interface, providing an efficient and intuitive way to iterate through a list's contents. With this interface, you can easily loop through every ListItem, making it simple to access, modify, or perform actions on each item with minimal effort. The Iterable interface is a standard pattern of the Java language, ensuring your code is familiar and maintainable for any Java developer.

The code snippet below demonstrates two easy ways to iterate through a list:

list.forEach(item -> {
   item.setText("Modified: " + item.getText());
});

for (ListItem item : list) {
   item.setText("Modified2: " + item.getText());
}

Shared list properties

Label

All List components can be assigned a label, which is a descriptive text or title associated with the component. Labels provide a brief explanation or prompt to help users understand the purpose or expected selection for that particular list. In addition to their importance for usability, list labels also play a crucial role in accessibility, enabling screen readers and assistive technologies to provide accurate information and facilitate keyboard navigation.

Helper text

Each List component can display helper text beneath the list using the setHelperText() method. This helper text offers additional context or explanations about the available options, ensuring users have the necessary information to make informed selections.

Horizontal alignment

All list components implement the HasHorizontalAlignment interface, giving you control over how text and content are aligned inside the component.

Use the setHorizontalAlignment() method to set alignment:

• HorizontalAlignment.LEFT (default)
• HorizontalAlignment.MIDDLE
• HorizontalAlignment.RIGHT

ListBox<String> listBox = new ListBox<>();
listBox.setHorizontalAlignment(HorizontalAlignment.LEFT);

To get the current alignment:

HorizontalAlignment alignment = listBox.getHorizontalAlignment();

Expanses

All list components in webforJ also implement the HasExpanse interface, allowing you to adjust the overall sizing and visual weight of the component. This is useful for adapting the component to various UI contexts, such as forms, dialogs, sidebars, etc.

Use the setExpanse() method to set the expanse level. Options include:

• Expanse.NONE
• Expanse.XSMALL
• Expanse.SMALL
• Expanse.MEDIUM (default)
• Expanse.LARGE
• Expanse.XLARGE

ListBox<String> listBox = new ListBox<>();
listBox.setExpanse(Expanse.LARGE);

You can retrieve the current setting using:

Expanse current = listBox.getExpanse();

Topics

📄️ ChoiceBox

The ChoiceBox component presents a dropdown list from which users select a single option. When a selection is made, the chosen value is displayed in the button. It's a good fit when users need to pick from a fixed set of predefined choices, and arrow keys can be used to navigate the list.

📄️ ComboBox

The ComboBox component combines a dropdown list with a text input, so users can either select from predefined options or type in a custom value. When custom entries need to be allowed alongside a set of suggested options, it fills the gap that ChoiceBox doesn't cover.

📄️ ListBox

The ListBox component displays a scrollable list of items that stays visible without needing to open a dropdown. It supports both single and multiple selection, and works well when users need to see all available options at once.