ListBox Control

The ListBox control allows the user to view and select from multiple items in a list. ListBoxes are static GUI entities, which means that items must be added to the list programmatically. The user can be provided with TextBoxes and Buttons with which to specify items to be added to the list, but the actual additions must be performed in code. 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	Description
Common Properties
Items	The collection of items in the ListBox.
MultiColumn	Indicates whether the ListBox can break a list into multiple columns. Multiple columns eliminate vertical scrollbars from the display.
SelectedIndex	Returns the index of the selected item. If no items have been selected, the property returns -1. 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 for 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. Values 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 every item.
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. This is the default event when the control is double clicked in the designer.

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 27. 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 return 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 different 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.

Figure 14.17. String Collection Editor.

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

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

(This item is displayed on pages 670 - 671 in the print version)

 1 // Fig. 14.18: ListBoxTestForm.cs
 2 // Program to add, remove and clear ListBox items
 3 using System;
 4 using System.Windows.Forms;
 5
 6 // Form uses a TextBox and Buttons to add,
 7 // remove, and clear ListBox items
 8 public partial class ListBoxTestForm : Form
 9 {
10 // default constructor
11 public ListBoxTestForm()
12 {
13 InitializeComponent();
14 } // end constructor
15
16 // add new item to ListBox (text from input TextBox)
17 // and clear input TextBox
18 private void addButton_Click( object sender, EventArgs e )
19 {
20 displayListBox.Items.Add( inputTextBox.Text );
21 inputTextBox.Clear();
22 } // end method addButton_Click
23
24 // remove item if one is selected
25 private void removeButton_Click( object sender, EventArgs e )
26 {
27 // check if item is selected, remove if selected
28 if ( displayListBox.SelectedIndex != -1 ) 
29  displayListBox.Items.RemoveAt( displayListBox.SelectedIndex );
30 } // end method removeButton_Click
31
32 // clear all items in ListBox
33 private void clearButton_Click( object sender, EventArgs e )
34 {
35 displayListBox.Items.Clear();
36 } // end method clearButton_Click
37
38 // exit application
39 private void exitButton_Click( object sender, EventArgs e )
40 {
41  Application.Exit();
42 } // end method exitButton_Click
43 } // end class ListBoxTestForm

 

(a)

(b)

(c)

(d)

The addButton_Click event handler (lines 1822) calls method Add of the Items collection in the ListBox. This method takes a string as the item to add to displayListBox. In this case, the string used is the user-input text, or inputTextBox.Text (line 20). After the item is added, inputTextBox.Text is cleared (line 21).

The removeButton_Click event handler (lines 2530) uses method RemoveAt to remove an item from the ListBox. Event handler removeButton_Click first uses property SelectedIndex to determine which index is selected. If SelectedIndex is not 1 (i.e., an item is selected) line 29 removes the item that corresponds to the selected index.

The clearButton_Click event handler (lines 3336) calls method Clear of the Items collection (line 35). This removes all the entries in displayListBox. Finally, event handler exitButton_Click (lines 3942) terminates the application by calling method Application.Exit (line 41).