Skip to main content

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

class represents individual items within a list. Each is associated with a key and a display text. Here are the key points regarding the class:

  • A encapsulates a unique key Object, and a text String for display within the component. List components are composed of objects.
  • You can construct a 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:

  2. Inserting an Item at a Specific Index:

  3. Inserting Multiple Items: You can insert multiple items at a specified index using the

    method.

    tip

    Using the add method triggers a server-to-client message each time it is used. For more efficient usage, create a list of

    objects, and put them in the list using the insert(int index, List<ListItem> items) method outlined below. For more information, you can refer to the documentation on architecture.

  4. Removing an Item:

    • To remove an item from the list, use the or method.
    • You can also remove all items from the list using .
  5. Accessing and Updating Items:

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

    or .

  7. Retrieving Information about the List:

    • You can get the size of the list using the method.
    • To check if the list is empty, use the 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.

Shared Events

info

All List components share the following events

EventsDescription
An event that is triggered when a component loses focus.
An event that is triggered when a component gains focus, opposite of a blur event.
An event that is triggered when the mouse cursor enters the boundaries of a component.
An event that is triggered when the mouse cursor exits the boundaries of a component.
An event that is triggered when the user presses the right mouse button while the cursor is over a component.
An event which is fired when the user selects an item from a list.