Using the CheckedListBox Class
The CheckedListBox class creates a list box control that includes a check box to the left of each list box item, as shown in Figure 12-5.
Figure 12-5.
The CheckedListBox class is derived from ListBox, adding functionality that enables you to interact with the check boxes in the list box.
The CheckedListBox class is similar to the ListBox class, and any code that targets a ListBox object should work with an instance of CheckedListBox. Because the CheckedListBox class is derived from ListBox, all of the properties, collections, events, and methods associated with the ListBox class described earlier in this chapter are exposed and available to you through the CheckedListBox class.
The appearance of the check boxes associated with each item in a checked list box is controlled by the ThreeDCheckBoxes property. By default, this property is set to false, which results in a check box that has a flat appearance. If the ThreeDCheckBoxes property is set to true, as shown in the following code, the check box is given a chiseled, three-dimensional look.
listBox.ThreeDCheckBoxes = true;
By default, the user must click once to select an item and then click again to toggle the status of the check box, effectively requiring two clicks to check an item. The CheckOnClick property can be used to alter this behavior. The following code enables the check box status for an item in the control to be toggled each time the user selects an item with the first click:
listBox.CheckOnClick = true;
The CheckedListBox class maintains collections that can be used to interact with the checked items in the control, as follows:
-
CheckedListBox.CheckedItemCollection Stores references to all items that have a checked or an indeterminate state
-
CheckedListBox.CheckedIndexCollection Stores the indexes of all items that have a checked or an indeterminate state
To retrieve a reference to CheckedItemCollection, use the CheckedItems property, as shown here:
CheckedListBox.CheckedItemCollection ci = checkedListBox.CheckedItems;
The CheckedIndices property is used to retrieve a reference to CheckedIndexCollection, as shown here:
CheckedListBox.CheckedIndexCollection ci = null; ci = checkedListBox.CheckedIndices;
To determine whether a particular item is checked, use the GetItemChecked property, as shown here:
bool isChecked = checkedListBox.GetItemChecked(index);
The GetItemChecked property returns the value true or false. If an item’s check box is checked or in the indeterminate state, the property returns true. Because all items in a checked list box can reflect three states, you can use the GetItemCheckState property to return a high-fidelity view of the check box state, as shown here:
CheckState chkState = checkedListBox.GetItemCheckState(index);
The GetItemCheckState property returns a value from the CheckState enumeration, shown earlier in this chapter, in Table 12-3.
In addition to the commonly handled events discussed earlier for the list box control, a checked list box will raise an ItemCheck event when the state of an item’s check box changes. A handler for the ItemCheck event receives an ItemCheckEventArgs object as a parameter. Derived from EventArgs, this class has three properties related to the event, as follows:
-
Index The index of the item that raised the event
-
CurrentValue The CheckState value representing the current state of the check box
-
NewValue The CheckState value representing the new state of the check box
These properties can be used as shown in the following code when handling the ItemCheck event:
private void OnItemCheck(object sender,
System.Windows.Forms.ItemCheckEventArgs e)
{
int index = e.Index;
if(e.NewValue == CheckState.Checked)
{
Sailboat boat = (Sailboat)checkedListBox.Items[index];
string msg = string.Format("Add {0} to the list of sold boats?",
boat.Name);
DialogResult result = MessageBox.Show(msg,
"Confirm",
MessageBoxButtons.YesNo,
MessageBoxIcon.Question);
if(result == DialogResult.Yes)
{
// Sell the boat.
listBox.Items.Add(boat);
}
}
}
In this example, the ItemCheckEventArgs object, e, is passed with information about the object that’s been checked in the list box. The OnItemCheck event handler extracts the index and new CheckState value for the clicked item. After the object has been extracted from the list box, the user is asked to confirm by clicking the check box control. If the user confirms by clicking the message box’s Yes button, the item is added to a second list box.
