ListBox

Introduction

The ListBox control allows displaying a list of items, each with some text and an icon. The area size for displaying the items can be limited by configuration. In the case that there are more items than fit into the predefined area, the ListBox provides a scroll bar. Users can select one or several items in one step (keyboard support available).

Examples

Selection

This first example shows a straight forward use case of the ListBox. The box contains the four seasons, and you can select your favorite one. Instead of choosing a season, you can flag the MultiSelection check box. For multiple choice, use the shift or ctrl modifier keys. Whenever the selection is modified, the text of the TextView is updated with the currently selected item(s).



Visible Items, Scrolling, Selection

In the case of a large number of list box items, you would have the need to restrict the space regarding the number of displayed items at the same time. Using the visibleItems property you can limit the number of displayed items. A scrollbar appears in the list box, and you can scroll through the items.

Sometimes you have the requirement to make a specific item visible in the ListBox that might occur - without doing further settings - at the end of the item list. For this purpose you use the scrollToIndex method. Its first argument is an integer that specifies the item that shall become visible. The second, optional argument bLazy is a boolean flag that checks whether the specified item shall appear at the top of the list (value false). It is also possible to make the setting that way that an item becomes visible with minimal scrolling effort (value true).

The following example shows a larger list of items. Five items are always visible at the same time. Whenever the Random button is pressed, an item is chosen randomly; it is selected and made visible using the scrollToIndex method. Play around a little bit and modify the value of the bLazy parameter to see its effect.



Icons, Height, and Item Height Calculation

List items can contain icons, and by this the heights of the single item entries in the list might differ. There are several ways to handle the height of the whole list box.

No Height

When the properties height and visibleItems are not set, the ListBox occupies the necessary space to display all items. The browser calculates this height and if, as a result, the page becomes higher than the current window, the window gets a scroll bar.

Height in Items

When only the visibleItems property is set, but no height, the ListBox control determines the height of the first item (or of a dummy item if there are currently no items available), multiplies it with the number of visible items, and uses the result as the height of its content area. So, if your items all have the same size, the resulting height will exactly match the height of visibleItems items. If the items have different sizes, the number of visible items varies.

Fixed Height

Using the height property, a fixed height can be specified.

Note: The height of individual items cannot be configured; their height is always determined from their content.

Following you see the different ways to deal with the height of a ListBox. For the ListBox representing the "Height in Items" variant, the value for visibleItems is set to "5". But the items have differing heights, and therefore the resulting height does not exactly match the number of visible items.




API Documentation

See ListBox API Documentation
See ListItem API documentation