Lists

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

This section will list the commonalities within each of the aforementioned components, with the specific behaviors belonging to each outlined in their own sections.

info

This section describes common functionality amongst all of the list components, and is not itself a class that can be instantiated and used.

Using ListItem

The

ListItem

class represents individual items within a list. Each

ListItem

is associated with a key and a display text. Here are the key points regarding the

ListItem

class:

• A
  ListItem
  encapsulates a unique key Object, and a text String for display within the component. List components are composed of
  ListItem
  objects.
• You can construct a
  ListItem
  by providing a key and text, or simply by specifying the text, where a random key is generated.

Managing ListItem Objects with the API

The various List classes offer various methods for managing the list of items and maintaining a consistent state between the list and the client.

By using these methods provided in the classes, you can effectively manage the items within the list component. The API allows you to interact with and manipulate the list to meet your application's requirements.

1. Adding an Item:

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

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

3. 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 in applications, instead of triggering a server-to-client message each time you use the add method, it's more efficient to compile 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, consult the documentation. :::

4. Removing an Item:

   • To remove an item from the list, use the
     remove(int index)
     or
     remove(Object key)
     method.
   • You can also remove all items from the list using
     removeAll()
     .

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

6. Selecting an Item: To select an item within the list, you can use methods such as

   select(ListItem item)
   or
   selectKey(Object key)
   .

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

Shared List Properties

Label

The various List components can be assigned a label, which is a descriptive text or title that is associated with the component. It provides a brief explanation or prompt to help users understand the purpose or expected selection for that particular list. List labels are not only important for usability but also play a crucial role in accessibility, as they enable screen readers and assistive technologies to provide accurate information and facilitate keyboard navigation.