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.
|
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. |
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.