The ListBox and CheckedListBox Controls

List boxes are used to show a list of strings from which one or more can be selected at a time. Just like check boxes and radio buttons, the list box provides a means of asking users to make one or more selections. You should use a list box when at design time you don't know the actual number of values the user can choose from (an example could be a list of coworkers). Even if you know all the possible values at design time, you should consider using a list box if there are a great number of values.

The ListBox class is derived from the ListControl class, which provides the basic functionality for list-type controls that ship with the .NET Framework.

Another kind of list box available is called CheckedListBox and is derived from the ListBox class. It provides a list just like the ListBox, but in addition to the text strings it provides a check for each item in the list.

ListBox Properties

In the following table, all the properties exist in both the ListBox class and CheckedListBox class unless explicitly stated.

Name	Description
SelectedIndex	This value indicates the zero-based index of the selected item in the list box. If the list box can contain multiple selections at the same time, this property holds the index of the first item in the selected list.
ColumnWidth	In a list box with multiple columns, this property specifies the width of the columns.
Items	The Items collection contains all of the items in the list box. You use the properties of this collection to add and remove items.
MultiColumn	A list box can have more than one column. Use this property to get or set if values should be displayed in columns.
SelectedIndices	This property is a collection, which holds all of the zero-based indices of the selected items in the list box.
SelectedItem	In a list box where only one item can be selected, this property contains the selected item, if any. In a list box where more than one selection can be made, it will contain the first of the selected items.
SelectedItems	This property is a collection that contains all currently selected items.
SelectionMode	You can choose between four different modes of selection from the ListSelectionMode enumeration in a list box: None: No items can be selected. One: Only one item can be selected at any time. MultiSimple: Multiple items can be selected. With this style, when you click an item in the list it becomes selected and stays selected even if you click another item until you click it again. MultiExtended: Multiple items can be selected. You use the Ctrl, Shift, and arrows keys to make selections. Unlike MultiSimple, if you simply click an item and then another item afterwards, only the second item clicked will be selected.
Sorted	Setting this property to true will cause the ListBox to alphabetically sort the items it contains.
Text	You saw Text properties on a number of controls, but this one works differently from any you've seen so far. If you set the Text property of the list box control, it searches for an item that matches the text, and selects it. If you get the Text property, the value returned is the first selected item in the list. This property cannot be used if the SelectionMode is None.
CheckedIndices	(CheckedListBox only) This property is a collection which contains indexes of all the items in the CheckedListBox that have a checked or indeterminate state.
CheckedItems	(CheckedListBox only) This is a collection of all the items in a CheckedListBox that are in a checked or indeterminate state.
CheckOnClick	(CheckedListBox only) If this property is true, an item will change its state whenever the user clicks it.
ThreeDCheckBoxes	(CheckedListBox only) You can choose between CheckBoxes that are flat or normal by setting this property.

ListBox Methods

In order to work efficiently with a list box, you should know a number of methods that can be called. The following table lists the most common methods. Unless indicated, the methods belong to both the ListBox and CheckedListBox classes.

Name	Description
ClearSelected()	Clears all selections in the ListBox.
FindString()	Finds the first string in the ListBox beginning with a string you specify (for example, FindString("a") will find the first string in the ListBox beginning with a.
FindStringExact()	Like FindString, but the entire string must be matched.
GetSelected()	Returns a value that indicates whether an item is selected.
SetSelected()	Sets or clears the selection of an item.
ToString()	Returns the currently selected item.
GetItemChecked()	(CheckedListBox only) Returns a value indicating if an item is checked or not.
GetItemCheckState()	(CheckedListBox only) Returns a value indicating the check state of an item.
SetItemChecked()	(CheckedListBox only) Sets the item specified to a checked state.
SetItemCheckState()	(CheckedListBox only) Sets the check state of an item.

ListBox Events

Normally, the events you will want to be aware of when working with a ListBox or CheckedListBox are those that have to do with the selections that are being made by the user.

Name	Description
ItemCheck	(CheckedListBox only) Occurs when the check state of one of the list items changes.
SelectedIndexChanged	Occurs when the index of the selected item changes.

In the following Try It Out, you create a small example with both a ListBox and a CheckedListBox. Users can check items in the CheckedListBox and then click a button which moves the checked items to the normal ListBox.

Try It Out – ListBox Example

You create the dialog as follows:

1. Create a new Windows application called Lists in directory C:\BegVCSharp\Chapter14.

2. Add a ListBox, a CheckedListBox, and a button to the form and change the names as shown in Figure 14-16.

   
   Figure 14-16

3. Change the Text property of the button to Move.

4. Change the CheckOnClick property of the CheckedListBox to true.

Adding the Event Handlers

Now, you are ready to add some code. When the user clicks the Move button, you want to find the items that are checked, and copy those into the right-hand list box.

Double-click the button and enter this code:

private void buttonMove_Click(object sender, EventArgs e) { // Check if there are any checked items in the CheckedListBox. if (this.checkedListBoxPossibleValue.CheckedItems.Count > 0) { // Clear the ListBox we'll move the  this.listBoxSelected.Items.Clear(); // Loop through the CheckedItems collection of the CheckedListBox // and add the items in the Selected ListBox foreach (string item in this.checkedListBoxPossibleValue.CheckedItems) { this.listBoxSelected.Items.Add(item.ToString()); } // Clear all the checks in the CheckedListBox for (int i = 0; i < this.checkedListBoxPossibleValue.Items.Count; i++) this.checkedListBoxPossibleValue.SetItemChecked(i, false); } }

How It Works

You start by checking the Count property of the CheckedItems collection. This will be greater than zero if any items in the collection are checked. You then clear all items in the listBoxSelected list box, and loop through the CheckedItems collection, adding each item to the listBoxSelected list box. Finally, you remove all the checks in the CheckedListBox.

Now, you just need something in the CheckedListBox to move. You can add the items while in design mode, by selecting the Items property in the Properties window and adding the items as shown in Figure 14-17:

Figure 14-17

Also you can add items in code, for example in the constructor of your form:

public Form1() {    //    // Required for Windows Form designer support.    //    InitializeComponent();     // Add a tenth element to the CheckedListBox. this.checkedListBoxPossibleValue.Items.Add("Ten"); }

Here you add a tenth element to the CheckedListBox, since you already have entered nine from the designer.

This concludes the list box example, and if you run it now, you will see something like Figure 14-18. Two, Four, and Six was selected and the Move button pressed to produce the image.

Figure 14-18