CheckedListBox

CheckedListBox presents several items in a list. Each item is checkable—the user can check a box. The CheckedListBox control in Windows Forms is a way to make longer, dynamic checkable lists.

CheckedListBox

Example

Steps

To start, please create a Windows Forms program in Visual Studio. We are using the C# language here. Next, please open the Toolbox and double-click on the CheckedListBox item. A new control is created.

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.

Event
Example that adds items 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);
	}
    }
}
Add

Adding items dynamically. You can add items to the CheckedListBox at design time. But you can also add items dynamically at runtime. You must use the checkedListBox1.Items property and the Add or AddRange methods on that.

And:The CheckedListBox will instantly detect the new items and display them. This makes programs responsive to user actions.

SelectedIndex

Lightning bolt

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.

Tip:You must check the SelectedIndex property for the value -1 to prevent an IndexOfOutRangeException.

IndexOutOfRangeException
Example that 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();
	    }
	}
    }
}
CheckedListBox

Items

It is also possible to edit the Items that are shown in the CheckedListBox at design time. In Visual Studio, select Properties and then Items on the CheckedListBox instance. You will get the String Collection Editor.

And:This functionality is the same in Visual Studio 2010 as well. Use a line break after each separate item.

CheckedListBox

CheckOnClick

Programming tip

One useful property 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

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.

Note:Please see the detailed article on IntegralHeight. This property may improve the design of your program.

IntegralHeight Property: Windows Forms

Enabled

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.

CheckedListBox

ThreeDCheckBoxes

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.

CheckedListBox

Background

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.

Note:Please see the specific article on BackColor and ForeColor for more details.

ForeColor, BackColor: Windows Forms

Summary

The C# programming language

CheckedListBox is useful for displaying a large or dynamic set of items that can be checked by the user. It has a wide assortment of properties that adjust appearance and behavior, as well as an Items collection that is dynamic.


C#: Windows