Section 14.6. ListBox Control

14.6. ListBox Control

The ListBox control allows the user to view and select from multiple items in a list. The CheckedListBox control (Section 14.7) extends a ListBox by including CheckBoxes next to each item in the list. This allows users to place checks on multiple items at once, as is possible with CheckBox controls. (Users also can select multiple items from a ListBox by setting the ListBox's SelectionMode property, which is discussed shortly.) Figure 14.15 displays a ListBox and a CheckedListBox. In both controls, scrollbars appear if the number of items exceeds the ListBox's viewable area.

Figure 14.15. ListBox and CheckedListBox on a Form.

Figure 14.16 lists common ListBox properties and methods, and a common event. The SelectionMode property determines the number of items that can be selected. This property has the possible values None, One, MultiSimple and MultiExtended (from the SelectionMode enumeration)the differences among these settings are explained in Fig. 14.16. The SelectedIndexChanged event occurs when the user selects a new item.

Figure 14.16. ListBox properties, methods and an event.

ListBox properties, methods and an event	Descripion
Common Properties
Items	The collection of items in the ListBox.
MultiColumn	Indicates whether the ListBox can break a list into multiple columns, which eliminates vertcail scrollbars from the display.
SelectedIndex	Returns the index of the selected item, or -1 if no items have been selected. If the user selects multiple items, this property returns only one of the selected indices. For this reason, if multiple items are selected, you should use property SelectedIndices.
SelectedIndices	Returns a collection containing the indices of all selected items.
SelectedItem	Returns a reference to the selected item. If multiple items are selected, it returns the item with the lowest index number.
SelectedItems	Returns a collection of the selected item(s).
SelectionMode	Determines the number of items that can be selected and the means through which multiple items can be selected. Vaules None, One, MultiSimple (multiple selection allowed) or MultiExtended (multiple selection allowed using a combination of arrow keys or mouse clicks and Shift and Ctrl keys).
Sorted	Indicates whether items are sorted alphabetically. Setting this property's value to TRue sorts the items. The default value is False.
Common Methods
ClearSelected	Deselects all items in the ListBox.
GetSelected	Takes an index as an argument, and returns true if the corresponding item is selected.
Common Event
SelectedIndexChanged	Generated when the selected index changes.

Both the ListBox and CheckedListBox have properties Items, SelectedItem and SelectedIndex. Property Items returns all the list items as a collection. Collections are a common way of managing lists of Objects in the .NET framework. Many .NET GUI components (e.g., ListBoxes) use collections to expose lists of internal objects (e.g., items contained within a ListBox). We discuss collections further in Chapter 26. The collection returned by property Items is represented as an object of type ObjectCollection. Property SelectedItem returns the ListBox's currently selected item. If the user can select multiple items, use collection SelectedItems to obtain all the selected items as a collection.

Property SelectedIndex returns the index of the selected itemif there could be more than one, use property SelectedIndices. If no items are selected, property SelectedIndex returns -1. Method GetSelected takes an index and returns true if the corresponding item is selected.

To add items to a ListBox or to a CheckedListBox, we must add objects to its Items collection. This can be accomplished by calling method Add to add a String to the ListBox's or CheckedListBox's Items collection. For example, we could write

 myListBox.Items.Add( myListItem ) 

to add String myListItem to ListBox myListBox. To add multiple objects, you can either call method Add multiple times or call method AddRange to add an array of objects. Classes ListBox and CheckedListBox each call the submitted object's ToString method to determine the Label for the corresponding object's entry in the list. This allows you to add non-String objects to a ListBox or a CheckedListBox that later can be returned through properties SelectedItem and SelectedItems.

Alternatively, you can add items to ListBoxes and CheckedListBoxes visually by examining the Items property in the Properties window. Clicking the ellipsis button opens the String Collection Editor, which contains a text area for adding items; each item appears on a separate line (Fig. 14.17). Visual Studio then writes code to add these Strings to the Items collection inside method InitializeComponent in the Form's Designer.vb file.

Figure 14.17. String collection Editor.

Figure 14.18 uses class FrmListBoxTest to add, remove and clear items from ListBox lstDisplay. Class FrmListBoxTest uses TextBox txtInput to allow the user to enter new items. When the user clicks the Add Button, the new item appears in lstDisplay. Similarly, if the user selects an item and clicks Remove, the item is deleted. When clicked, Clear deletes all entries in lstDisplay. The user terminates the application by clicking Exit.

Figure 14.18. Program that adds, removes and clears ListBox items.

  1  ' Fig. 14.18: FrmListBoxTest.vb  2  ' Program to add, remove and clear ListBox items  3  Public Class FrmListBoxTest  4     ' add to lstDisplay the item the user enters in txtInput,  5     ' then clear txtInput  6     Private Sub btnAdd_Click(ByVal sender As System.Object, _  7        ByVal e As System.EventArgs) Handles btnAdd.Click  8  9        lstDisplay.Items.Add(txtInput.Text) 10        txtInput.Clear() 11     End Sub ' btnAdd_Click 12 13     ' remove an item from lstDisplay if one is selected 14     Private Sub btnRemove_Click(ByVal sender As System.Object, _ 15        ByVal e As System.EventArgs) Handles btnRemove.Click 16 17        ' if an item is selected, remove that item 18        If lstDisplay.SelectedIndex <> -1 Then                 19           lstDisplay.Items.RemoveAt(lstDisplay.SelectedIndex) 20        End If                                                 21     End Sub ' btnRemove_Click 22 23     ' clear all the items in lstDisplay 24     Private Sub btnClear_Click(ByVal sender As System.Object, _ 25        ByVal e As System.EventArgs) Handles btnClear.Click 26 27        lstDisplay.Items.Clear() 28     End Sub ' btnClear_Click 29 30     ' terminate the application 31     Private Sub btnExit_Click(ByVal sender As System.Object, _ 32        ByVal e As System.EventArgs) Handles btnExit.Click 33 34        Application.Exit() 35     End Sub ' btnExit_Click 36  End Class ' FrmListBoxTest 

(a)

(b)

(c)

(d)

The btnAdd_Click event handler (lines 611) calls method Add of the ListBox's Items collection. This method takes an Object as the item to add to lstDisplay. In this case, the Object used is the text entered by the usertxtInput.Text (line 9). After the item is added, txtInput.Text is cleared (line 10).

The btnRemove_Click event handler (lines 1421) uses method RemoveAt to remove an item from the ListBox. Lines 1820 first use property SelectedIndex to determine which index is selected. If SelectedIndex is not 1 (i.e., an item is selected) line 19 removes the item that corresponds to the selected index.

The btnClear_Click event handler (lines 2428) calls method Clear of the Items collection (line 27) to remove all the entries in lstDisplay. Finally, event handler btnExit_Click (lines 3135) terminates the application by calling method Application.Exit (line 34).