CheckedListBox

A CheckedListBox control displays a series of items with check boxes in a list format. This enables the user to pick and choose similar items from a list of choices. You can also use a ListBox to allow the user to select items in a list, but there are some differences between the two controls’ behaviors.

First, in a CheckedListBox, previously checked items remain checked when the user clicks on another item. If the user clicks an item in a ListBox, the control deselects any previously selected items, although you can use the Shift and Ctrl keys to modify this behavior.

Second, the user must click each CheckedListBox item individually to select it. You can make a ListBox allow simple or extended selections. That means, for example, the user could Shift+click to select all of the items in a range. If the user is likely to want that type of selection, consider using a ListBox instead of a CheckedListBox.

If a CheckedListBox isn’t big enough to display all of its items at once, it displays a vertical scroll bar to let the user see all the items. If some of the items are too wide to fit, set the control’s HorizontalScrollBar property to True to display a horizontal scroll bar.

If you set the MultiColumn property to True, the control displays items in multiple columns.

By default, the user must click an item and then click its box to check the item. To allow the user to select an item with a single click, set the control’s CheckOnClick property to True.

If the control’s IntegralHeight property is True, the control will not display a partial item. For example, if the control is tall enough to display 10.7 items, it will make itself slightly shorter so that it can only display 10 items.

Set the control’s Sorted property to True to make the control display its items in sorted order.

Use the control’s Items.Add method to add an item to the list. This method has three overloaded versions. All three take a generic Object as the first parameter. The control uses this object’s ToString method to generate the text that it displays to the user. The first overloaded version takes no extra parameters. The second version takes a Boolean parameter indicating whether the new item should be checked. The last version takes a parameter that indicates whether the new item should be checked, unchecked, or indeterminate.

For example, suppose that a program defines the following Employee class. The important part here is the ToString method, which tells the CheckedListBox how to display an Employee object, as shown in the following code:

  Public Class Employee     Public FirstName As String     Public LastName As String     Public Sub New(ByVal first_name As String, ByVal last_name As String)         FirstName = first_name         LastName = last_name     End Sub     Public Overrides Function ToString() As String         Return FirstName & " " & LastName     End Function End Class 

The following code shows how the program might add three items to the CheckedListbox named clbEmployees. It makes the first item checked, the second unchecked, and the third indeterminate.

  Private Sub Form1_Load(ByVal sender As System.Object, _  ByVal e As System.EventArgs) Handles MyBase.Load     clbEmployees.Items.Add(New Employee("Alicia", "Anderson"), True)     clbEmployees.Items.Add(New Employee("Brutus", "Bentley"), False)     clbEmployees.Items.Add(New Employee("Cynthia", "Colefield"), _         CheckState.Indeterminate) End Sub 

The CheckedListBox item’s CheckedItems property returns a collection containing the objects that are checked, including those that are in the indeterminate state. The following code fragment displays the text values of the selected objects in the Output window:

  Dim checked_items As CheckedListBox.CheckedItemCollection = _     clbEmployees.CheckedItems     For Each item As Object In checked_items         Debug.WriteLine(item.ToString)     Next item 

The control’s CheckedIndices property returns a collection of integers representing the items that are selected or indeterminate (numbered starting with zero).