15.7 CheckedListBox Control

The CheckedListBox control derives from ListBox and displays a CheckBox with each item. Items can be added via methods Add and AddRange or through the String Collection Editor. CheckedListBoxes allow multiple items to be checked, but item selection is more restrictive. The only values for the SelectionMode property are None and One. One allows a single selection, whereas None allows no selections. Because an item must be selected to be checked, you must set the SelectionMode to be One if you wish to allow users to check items. Thus, toggling property SelectionMode between One and None effectively switches between enabling and disabling the user’s ability to check list items. Common properties, a method and an event of CheckedListBoxes appear in Fig. 15.19.

Common Programming Error 15.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 Checked-ListBox 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.

Fig. 15.19 CheckedListBox properties, a method and an event.

CheckedListBox properties, a method and an event Description
Common Properties (All the ListBox properties, methods and events are inherited by CheckedListBox.)
CheckedItems Accessible only at runtime. Returns the collection of items that are checked as a CheckedListBox.CheckedItemCollection. 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 Accessible only at runtime. Returns indices for all checked items as a CheckedListBox.CheckedIndexCollection.
CheckOnClick When true and the user clicks an item, the item is both selected and checked or unchecked. By default, this property is false, which means that the user must select an item, then click it again to check or uncheck it.
SelectionMode Determines whether items can be selected and checked. The possible values are One (the default; 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.

In Fig. 15.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, C++, Java, Internet & WWW, Visual Basic, Visual C++ and Visual C# (the abbreviation 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.

Fig. 15.20 Using a CheckedListBox to add items to a display ListBox.

Alternate View 

  1    // Fig. 15.20: CheckedListBoxTestForm.cs
  2    // Using a CheckedListBox to add items to a display ListBox
  3
  4    using System.Windows.Forms;
  5
  6    namespace CheckedListBoxTest
  7    {
  8       // Form uses a checked ListBox to add items to a display ListBox
  9       public partial class CheckedListBoxTestForm : Form
 10       {
 11           // constructor
 12           public CheckedListBoxTestForm()
 13           {
 14              InitializeComponent();
 15           }
 16
 17           // item checked or unchecked
 18           // add or remove from display ListBox
 19           private void itemCheckedListBox_ItemCheck(
 20              object sender, ItemCheckEventArgs e)
 21           {
 22              // obtain reference of selected item
 23              string item = itemCheckedListBox.SelectedItem.ToString();
 24
 25              // if item checked, add to ListBox
 26              // otherwise remove from ListBox
 27              if (e.NewValue == CheckState.Checked)
 28              {
 29                 displayListBox.Items.Add(item);
 30              }
 31              else
 32              {
 33                 displayListBox.Items.Remove(item);
 34              }
 35            }
 36         }
 37     }

When the user checks or unchecks an item in itemCheckedListBox, an ItemCheck event occurs and event handler itemCheckedListBox_ItemCheck (lines 19–35) executes. An if …else statement (lines 27–34) determines whether the user checked or unchecked an item in the CheckedListBox. Line 27 uses the NewValue property to determine whether the item is being checked (CheckState.Checked). If the user checks an item, line 29 adds the checked entry to the ListBox displayListBox. If the user unchecks an item, line 33 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. The default event for a Checked-ListBox is a SelectedIndexChanged event.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset