CheckedListBox Control

The CheckedListBox control derives from class ListBox and includes a CheckBox next to each item. As in ListBoxes, items can be added via methods Add and AddRange or through the String Collection Editor. CheckedListBoxes imply that multiple items can be selected, and the only possible values for the SelectionMode property are None and One. One allows multiple selection, because CheckBoxes imply that there are no logical restrictions on the itemsthe user can select as many items as required. Thus, the only choice is whether to give the user multiple selection or no selection at all. This keeps the CheckedListBox's behavior consistent with that of CheckBoxes. Common properties, events and methods of CheckedListBoxes appear in Fig. 14.19.

Figure 14.19. CheckedListBox properties, methods and events.

(This item is displayed on page 672 in the print version)

CheckedListBox properties, methods and events	Description
Common Properties	(All the ListBox properties, methods and events are inherited by CheckedListBox.)
CheckedItems	Contains the collection of items that are checked. This is distinct from the selected item, which is highlighted (but not necessarily checked). [Note: There can be at most one selected item at any given time.]
CheckedIndices	Returns indices for all checked items.
SelectionMode	Determines how many items can be checked. The only possible values are One (allows multiple checks to be placed) or None (does not allow any checks to be placed).
Common Method
GetItemChecked	Takes an index and returns true if the corresponding item is checked.
Common Event (Event arguments ItemCheckEventArgs)
ItemCheck	Generated when an item is checked or unchecked.
ItemCheckEventArgs Properties
CurrentValue	Indicates whether the current item is checked or unchecked. Possible values are Checked, Unchecked and Indeterminate.
Index	Returns the zero-based index of the item that changed.
NewValue	Specifies the new state of the item.

Common Programming Error 14 1

The IDE displays an error message if you attempt to set the SelectionMode property to MultiSimple or MultiExtended in the Properties window of a CheckedListBox. If this value is set programmatically, a runtime error occurs.

Event ItemCheck occurs whenever a user checks or unchecks a CheckedListBox item. Event argument properties CurrentValue and NewValue return CheckState values for the current and new state of the item, respectively. A comparison of these values allows you to determine whether the CheckedListBox item was checked or unchecked. The CheckedListBox control retains the SelectedItems and SelectedIndices properties (it inherits them from class ListBox). However, it also includes properties CheckedItems and CheckedIndices, which return information about the checked items and indices.

In Fig. 14.20, class CheckedListBoxTestForm uses a CheckedListBox and a ListBox to display a user's selection of books. The CheckedListBox allows the user to select multiple titles. In the String Collection Editor, items were added for some Deitel books: C++, Java™, Visual Basic, Internet & WWW, Perl, Python, Wireless Internet and Advanced Java (the acronym HTP stands for "How to Program"). The ListBox (named displayListBox) displays the user's selection. In the screenshots accompanying this example, the CheckedListBox appears to the left, the ListBox on the right.

Figure 14.20. CheckedListBox and ListBox used in a program to display a user selection.

 1 // Fig. 14.20: CheckedListBoxTestForm.cs
 2 // Using the checked ListBox to add items to a display ListBox
 3 using System;
 4 using System.Windows.Forms;
 5
 6 // Form uses a checked ListBox to add items to a display ListBox
 7 public partial class CheckedListBoxTestForm : Form
 8 {
 9 // default constructor
10 public CheckedListBoxTestForm()
11 {
12 InitializeComponent();
13 } // end constructor
14
15 // item about to change
16 // add or remove from display ListBox
17 private void inputCheckedListBox_ItemCheck(
18 object sender, ItemCheckEventArgs e )
19 {
20 // obtain reference of selected item
21 string item = inputCheckedListBox.SelectedItem.ToString();
22
23 // if item checked add to ListBox
24 // otherwise remove from ListBox
25 if ( e.NewValue == CheckState.Checked )
26 displayListBox.Items.Add( item );
27 else
28 displayListBox.Items.Remove( item );
29 } // end method inputCheckedListBox_ItemCheck
30 } // end class CheckedListBoxTestForm

 

(a)

(b)

(c)

(d)

When the user checks or unchecks an item in inputCheckedListBox, an ItemCheck event occurs and event handler inputCheckedListBox_ItemCheck (lines 1729) executes. An if...else statement (lines 2528) determines whether the user checked or unchecked an item in the CheckedListBox. Line 25 uses the NewValue property to determine whether the item is being checked (CheckState.Checked). If the user checks an item, line 26 adds the checked entry to the ListBox displayListBox. If the user unchecks an item, line 28 removes the corresponding item from displayListBox. This event handler was created by selecting the CheckedListBox in Design mode, viewing the control's events in the Properties window and double clicking the ItemCheck event.