ListBox

Introduction

The ListBox is a scrollable view which displays multiple ListBoxItem instances. When one ListBoxItem is selected, the previously-selected ListBoxItem becomes deselected.

Layout Requirements

The ListBox control requires:

  • An object named VerticalScrollBarInstance which implements ScrollBarBehavior (is a ScrollBar)
  • An object named InnerPanelInstance of any type (typically a Container)
  • An object named ClipContainerInstance of any type (typically a Container with ClipsChildren set to true)

The requirements for the ListBox are identical to the requirements for the ScrollViewer control. For more information on requirements, see the ScrollViewer page:

http://flatredball.com/documentation/tutorials/flatredball-forms/forms-layout-in-gum/scrollviewer/

InnerPanelInstance and Children Layout

The ListBox control typically handles the creation and positioning of ListBoxItem instances. The InnerPanelInstance in the list box Gum component will typically use a Children Layout value of TopToBottomStack.

Alternatively the InnerPanelInstance can use a Children Layout value of LeftToWriteStack with the Wraps Children value set to true.

Items

Items represents the data that the ListBox is managing. Items can either contain regular types (such as strings, ints, or classes representing data in your game like data for a car in a racing game), or instances of ListBoxItems. Whenever an object is added to the Items collection the list box will automatically update its visuals to display the newly-added object. If the newly-added object is a regular type, then the ListBox will internally construct a new ListBoxItem. If the newly-added object is already a ListBoxItem, then the ListBox will display the ListboxItem as-is. This allows games to conveniently add non-ListBoxItems or to construct ListBoxItems for full control.

Items.Add with ListBoxItemGumType

Any object type can be added to a ListBox.  The following code shows how to add strings to the Items property, resulting in the list box displaying a single entry for each item.

By default Glue will generate code for a default ListBoxItemGumType, so the line above is optional. If you would like the list box to have a custom ListBoxItem type, you can specify it as shown in the code above.

If specified, the ListBoxItemGumType should be a Gum runtime type which has the ListBoxItem behavior.

Items.Add with Manual ListBoxItem Construction

ListBoxItem instances can be manually instantiated and added to a list box, as opposed to relying on the default or explicitly specified ListBoxItemGumType. The following code shows how to manually create and add ListBoxItems. Note that the same Items list is used when adding ListBoxItem instances.

Mixing ListBoxItem Types

A single ListBox can contain multiple types of ListBoxItems. Multiple types can be used by explicitly instantiating ListBoxItems using different Gum runtime types, or by setting the ListBoxItem property multiple times.

The following code shows how to instantiate ListBoxItems using different Gum runtimes:

Icons in screenshot obtained from http://game-icons.net/ .

The same could be achieved by setting the ListBoxItemGumType before calling AddItem, as shown in the following code:

Note that using ListBoxItemGumType does require less code, and may be sufficient for many scenarios requiring different ListBoxItem runtimes.

ListBoxItemFormsType

The ListBox control also allows specifying the Forms control to create, which can customize behavior and display logic. For information on creating and using custom ListBoxItem types, see the ListBoxItem page.

Selection

The selected item can be controlled using a number of properties.

SelectedItem

The SelectedItem property gets and sets the selected item. Setting this value will select the first matching instance found in the Items property.

The following code example adds three strings, then selects the second one:

SelectedIndex

The SelectedIndex property gets and sets the index of the currently selected item. A value of -1 indicates no selection. The following code example shows how to deselect the selected item in a ListBox:

SelectionChanged Event

The SelectionChanged event is raised whenever a selection changes due to a mouse click or code change of the SelectedItem or SelectedIndex. The event provides a list of newly-selected items and deselected items.

Note that at the time of this writing only a single item can be selected at a time, but future versions of FlatRedBall.Forms may add multi-selection support.

The following code example shows how to react to the selection changing on a ListBox:

The event handling the selection changing can also use the SelectedItem  property, as shown in the following code: