Section 14.7. CheckedListBox Control

14.7. 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. Figure 14.19 lists some common properties, a common method and a common event of class CheckedListBox.

Figure 14.19. CheckedListBox properties, a method and an event.

CheckedListBox properties, methods and an event	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). 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 when 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 inherits the SelectedItems and SelectedIndices properties from class ListBox. It also includes properties CheckedItems and CheckedIndices, which return information about the checked items and indices.

In Fig. 14.20, class FrmCheckedListBoxTest uses a CheckedListBox and a ListBox to display a user's book selections. The CheckedListBox allows the user to select multiple titles. In the String Collection Editor, we added items for some Deitel booksC++, Java, Visual Basic, Internet & WWW, Perl, Python, Wireless Internet and Advanced Java (the acronym HTP stands for "How to Program"). The ListBox (named lstDisplay) displays the user's selections.

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

  1  ' Fig. 14.20: FrmCheckedListBoxTest.vb  2  ' Using the checked ListBox to add items to a display ListBox  3  Public Class FrmCheckedListBoxTest  4     ' add an item to or remove an item from lstDisplay  5     Private Sub chklstItem_ItemCheck( _  6        ByVal sender As System.Object, _  7        ByVal e As System.Windows.Forms.ItemCheckEventArgs) _  8        Handles chklstItem.ItemCheck  9 10        ' obtain selected item 11        Dim item As String = chklstItem.SelectedItem.ToString() 12 13        ' if the selected item is checked add it to lstDisplay; 14        ' otherwise, remove it from lstDisplay 15        If e.NewValue = CheckState.Checked Then 16           lstDisplay.Items.Add(item)           17        Else                                    18           lstDisplay.Items.Remove(item)        19        End If                                  20     End Sub ' chklstItem_ItemCheck 21  End Class ' FrmCheckedListBoxTest 

(a)

(b)

(c)

(d)

When the user checks or unchecks an item in chklstInput, an ItemCheck event occurs and event handler chklstItem_ItemCheck (lines 520) executes. An If...Else statement (lines 1519) determines whether the user checked or unchecked an item in the CheckedListBox. Line 15 uses the ItemCheckEventArgs property NewValue to determine whether the item is being checked (CheckState.Checked). If the user checks an item, line 16 adds the checked entry to lstDisplay. If the user unchecks an item, line 18 removes the corresponding item from lstDisplay. 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.