WidgetList

The WidgetList widget enables users to select an item from a list of options. The list of options can be defined by the user and can contain up to 255 items.

Using the WidgetList widget, you can create menu items that present numbers, text, or other settings as selectable options to users.

The WidgetList accepts any type of data as the list items, as long as it can be converted to a string.

WidgetList has the following properties:

  • values: The list of values to choose from (now uses std::vector instead of static arrays).

  • activePosition: The index of the currently selected item (default: 0).

  • format: The format string used to display the selected item (default: “%s”).

  • cursorOffset: The offset of the cursor from the end of the widget when the widget is focused (default: 0).

  • cycle: Whether the selection should cycle back to the beginning when the end of the list is reached (default: false).

  • callback: A callback function that will be called when an item is selected (default: nullptr). The callback is not required if you have multiple widgets in a WidgetItem and you want to handle the selection in the WidgetItem callback.

The following are examples of how to create WidgetList widgets:

Simple list

std::vector<const char*> listItems = { "Item 1", "Item 2", "Item 3", "Item 4" };

WIDGET_LIST(listItems, 0, "%s", 0, false, [](const char* item) {
    // Callback function to handle item selection
})

In the above example, the WidgetList allows the user to select an item from “Item 1”, “Item 2”, “Item 3”, or “Item 4”.

Number picker

std::vector<uint8_t> listItems = { 7, 2, 9, 4 };

WIDGET_LIST(listItems, 0, "%d", 0, false)

In the above example, the WidgetList allows the user to select an item from 7, 2, 9, or 4 only. This is useful when you want to limit the user to a specific set of values.

Day picker

std::vector<const char*> days = {"Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"};

WIDGET_LIST(days, 0, " on %s", 0, true)

In the above example, the WidgetList allows the user to select a day of the week. The selected day will be displayed as “ on Mon”, “ on Tue”, “ on Wed”, etc.

Month picker (with reference value)

uint8_t selectedMonth = 0;

std::vector<const char*> months = {"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"};

WIDGET_LIST_REF(months, selectedMonth, "%s", 0, true)

In the above example, the WidgetList allows the user to select a month. The selected month value can be updated by changing the value of the selectedMonth variable. After the value is updated, the WidgetList will automatically update the selected item on the next polling cycle (if polling is enabled) or immediately if you call the refresh function.

Note

The referenced variable (selectedMonth) must remain valid for the widget’s lifetime to ensure proper and predictable updates. Invalidating the referenced variable (e.g., by going out of scope or being deleted) can lead to undefined behavior. Ensure that the variable’s lifetime exceeds or matches the widget’s lifetime to avoid such issues.

For a complete example of using WIDGET_LIST_REF, see the use by ref example.

Changes in v5.10.0

  • Adoption of `std::vector`: The WidgetList now uses std::vector instead of static arrays for defining the list of values. This change improves flexibility and modernizes the codebase.

  • Simplified `WIDGET_LIST` Macro: The size parameter for WIDGET_LIST has been removed, reducing boilerplate code and simplifying widget definitions.