CheckedListBox

You have several items in a list that you want to make checkable. The CheckedListBox control in Windows Forms presents a useful way to make longer, dynamic checkable lists.

This C# tutorial shows the CheckedListBox control. It provides example code.

Example code

To start, please create a Windows Forms program in Visual Studio, and then open the Toolbox and double-click on the CheckedListBox item. From here, you can right-click on the CheckedListBox and select Properties to adjust properties and also add event handlers. In this first example, you need to add the Form1_Load event handler by double-clicking on the form as well.

Example: adds items dynamically to CheckedListBox [C#]

using System;
using System.Windows.Forms;

namespace WindowsFormsApplication25
{
    public partial class Form1 : Form
    {
	public Form1()
	{
	    InitializeComponent();
	}

	private void Form1_Load(object sender, EventArgs e)
	{
	    var items = checkedListBox1.Items;
	    items.Add("Perls");
	    items.Add("Checked", true);
	}
    }
}

Adding items dynamically. Although you can add items to the CheckedListBox at design time, you can also add items dynamically at runtime, as shown above. You must use the checkedListBox1.Items property and the Add or AddRange methods on that. The CheckedListBox will instantly detect the new items and display them.

SelectedIndexChanged event handler

Another useful event handler on the CheckedListBox is the SelectedIndexChanged handler. You might use this event handler to display some useful text in the UI when an item is selected. You must check the SelectedIndex property for the value -1 to prevent an IndexOfOutRangeException.

Example: uses SelectedIndex property [C#]

using System;
using System.Windows.Forms;

namespace WindowsFormsApplication25
{
    public partial class Form1 : Form
    {
	public Form1()
	{
	    InitializeComponent();
	}

	private void checkedListBox1_SelectedIndexChanged(object sender, EventArgs e)
	{
	    // Get selected index, and then make sure it is valid.
	    int selected = checkedListBox1.SelectedIndex;
	    if (selected != -1)
	    {
		this.Text = checkedListBox1.Items[selected].ToString();
	    }
	}
    }
}

Items property

It is also possible to edit the Items that are shown in the CheckedListBox at design time, using Visual Studio. In Visual Studio 2008, select Properties and then Items on the CheckedListBox instance. You will get the String Collection Editor. This functionality is the same in Visual Studio 2010 as well. Use a line break after each separate item.

CheckOnClick property

One very useful property on the CheckedListBox is the CheckOnClick property. By default, this is set to False; when False, the user must click a second time after an item is selected to check the box. When True, the user must only click once to check a box.

IntegralHeight property

It is possible to use the IntegralHeight property on the CheckedListBox to ensure that no partial items are shown. Depending on the structure of your user interface, this may be desirable. Please see the detailed article on IntegralHeight.

Enabled property

In Windows Forms, controls have the Enabled property. When you set Enabled to False, the entire control is disabled. With the CheckedListBox, setting Enabled to False will gray out all the items in the control, and also make them unclickable and unselectable.

ThreeDCheckBoxes property

By default, the CheckedListBox has checkboxes that have a flat, single-pixel border. For some programs, a more three-dimensional appearance may be desirable. To solve this, you can set the ThreeDCheckBoxes property to true, yielding the appearance shown in this screenshot.

BackColor and ForeColor

Controls in Windows Forms also have the BackColor and ForeColor properties available. The BackColor property adjusts the background of the controls, while the ForeColor adjusts the text color. Please see the specific articles on BackColor and ForeColor for more details.

Summary

The CheckedListBox control is useful for displaying a large or dynamic set of items that can be checked by the user. With a wide assortment of properties that adjust appearance and behavior, as well as an Items collection that is dynamic, the CheckedListBox provides a useful range of functionality for developers.