Lists

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 applications: 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().

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.

• Selecting an item:

  • To select an item within the list, you can use methods such as select(ListItem item) or selectKey(Object key).

• 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.

Topics

📄️ ChoiceBox

The ChoiceBox component is a user interface element designed to present users with a list of options or choices. Users can select a single option from this list, typically by clicking the ChoiceBox, which triggers the display of a dropdown list containing available choices. Users can also interact with the ChoiceBox with the arrow keys. When a user makes a selection, the chosen option is then displayed in the ChoiceBox button.

📄️ ComboBox

The ComboBox component is a user interface element designed to present users with a list of options or choices, as well as a field for entering their own custom values. Users can select a single option from this list, typically by clicking the ComboBox, which triggers the display of a dropdown list containing available choices, or type in a custom value. Users can also interact with the ComboBox with the arrow keys. When a user makes a selection, the chosen option is then displayed in the ComboBox.

📄️ ListBox

The ListBox component is a user interface element designed to display a scrollable list of objects and allows users to select single or multiple items from the list. Users can also interact with the ListBox with the arrow keys.