CheckedListBox Class (System.Windows.Forms)

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

CheckedListBox Class

Displays a ListBox in which a check box is displayed to the left of each item.

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in System.Windows.Forms.dll)

Syntax

Visual Basic (Declaration)

<ComVisibleAttribute(True)> _
<ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)> _
<LookupBindingPropertiesAttribute> _
Public Class CheckedListBox _
    Inherits ListBox

Visual Basic (Usage)

Dim instance As CheckedListBox

[ComVisibleAttribute(true)]
[ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)]
[LookupBindingPropertiesAttribute]
public class CheckedListBox : ListBox

Visual C++

[ComVisibleAttribute(true)]
[ClassInterfaceAttribute(ClassInterfaceType::AutoDispatch)]
[LookupBindingPropertiesAttribute]
public ref class CheckedListBox : public ListBox

JScript

public class CheckedListBox extends ListBox

Remarks

This control presents a list of items that the user can navigate by using the keyboard or the scrollbar on the right side of the control. The user can place a check mark by one or more items and the checked items can be navigated with the CheckedListBox..::.CheckedItemCollection and CheckedListBox..::.CheckedIndexCollection.

To add objects to the list at run time, assign an array of object references with the AddRange method. The list then displays the default string value for each object. You can add individual items to the list with the Add method.

The CheckedListBox object supports three states through the CheckState enumeration: Checked, Indeterminate, and Unchecked. You must set the state of Indeterminate in the code because the user interface for a CheckedListBox does not provide a mechanism to do so.

If UseTabStops is true, the CheckedListBox will recognize and expand tab characters in an item's text, creating columns. These tab stops are preset and cannot be changed. To use custom tab stops, set UseTabStops to false, set UseCustomTabOffsets to true, and add the custom values to the CustomTabOffsets collection.

Note:
If the UseCompatibleTextRendering property is false, the CustomTabOffsets property will be ignored and replaced with standard tab offsets.

The CheckedListBox class supports the following three indexed collections:

Collection	Encapsulating Class
All items contained in the CheckedListBox control.	CheckedListBox..::.ObjectCollection
Checked items (including items in an indeterminate state), which is a subset of the items contained in the CheckedListBox control.	CheckedListBox..::.CheckedItemCollection
Checked indexes, which is a subset of the indexes into the items collection. These indexes specify items in a checked or indeterminate state.	CheckedListBox..::.CheckedIndexCollection

The following three tables are examples of the three indexed collections that the CheckedListBox class supports.

The first table provides an example of the indexed collection of items in the control (all items contained in the control).

Index	Item	Check State
0	Object 1	Unchecked
1	Object 2	Checked
2	Object 3	Unchecked
3	Object 4	Indeterminate
4	Object 5	Checked

The second table provides an example of the indexed collection of the checked items.

Index	Item
0	Object 2
1	Object 4
2	Object 5

The third table provides an example of the indexed collection of indexes of checked items.

Index	Index of Item
0	1
1	3
2	4

Note You cannot bind data to a CheckedListBox. Use a ComboBox or a ListBox for this instead. For more information, see How to: Bind a Windows Forms ComboBox or ListBox Control to Data.

Examples

The following example illustrates how you can use the methods, properties, and collections of a CheckedListBox. This is a complete sample ready to run once you have copied it to your project. You can check and uncheck items, use the text box to add items and once you have clicked the save button, clear the checked items.

Visual Basic

Option Explicit
Option Strict

Imports System
Imports System.Drawing
Imports System.Collections
Imports System.ComponentModel
Imports System.Windows.Forms
Imports System.Data
Imports System.IO

Namespace WindowsApplication1
    Public Class Form1
        Inherits System.Windows.Forms.Form
        Private WithEvents checkedListBox1 As System.Windows.Forms.CheckedListBox
        Private WithEvents textBox1 As System.Windows.Forms.TextBox
        Private WithEvents button1 As System.Windows.Forms.Button
        Private WithEvents button2 As System.Windows.Forms.Button
        Private WithEvents listBox1 As System.Windows.Forms.ListBox
        Private WithEvents button3 As System.Windows.Forms.Button
        Private components As System.ComponentModel.Container


        Public Sub New()
            InitializeComponent()

            ' Sets up the initial objects in the CheckedListBox.
            Dim myFruit As String() =  {"Apples", "Oranges", "Tomato"}
            checkedListBox1.Items.AddRange(myFruit)

            ' Changes the selection mode from double-click to single click.
            checkedListBox1.CheckOnClick = True
        End Sub 'New


        Protected Overloads Overrides Sub Dispose(ByVal disposing As Boolean)
            If disposing Then
                If (components IsNot Nothing) Then
                    components.Dispose()
                End If
            End If
            MyBase.Dispose(disposing)
        End Sub

        Private Sub InitializeComponent()
            Me.components = New System.ComponentModel.Container()
            Me.textBox1 = New System.Windows.Forms.TextBox()
            Me.checkedListBox1 = New System.Windows.Forms.CheckedListBox()
            Me.listBox1 = New System.Windows.Forms.ListBox()
            Me.button1 = New System.Windows.Forms.Button()
            Me.button2 = New System.Windows.Forms.Button()
            Me.button3 = New System.Windows.Forms.Button()
            Me.textBox1.Location = New System.Drawing.Point(144, 64)
            Me.textBox1.Size = New System.Drawing.Size(128, 20)
            Me.textBox1.TabIndex = 1
            Me.checkedListBox1.Location = New System.Drawing.Point(16, 64)
            Me.checkedListBox1.Size = New System.Drawing.Size(120, 184)
            Me.checkedListBox1.TabIndex = 0
            Me.listBox1.Location = New System.Drawing.Point(408, 64)
            Me.listBox1.Size = New System.Drawing.Size(128, 186)
            Me.listBox1.TabIndex = 3
            Me.button1.Enabled = False
            Me.button1.Location = New System.Drawing.Point(144, 104)
            Me.button1.Size = New System.Drawing.Size(104, 32)
            Me.button1.TabIndex = 2
            Me.button1.Text = "Add Fruit"
            Me.button2.Enabled = False
            Me.button2.Location = New System.Drawing.Point(288, 64)
            Me.button2.Size = New System.Drawing.Size(104, 32)
            Me.button2.TabIndex = 2
            Me.button2.Text = "Show Order"
            Me.button3.Enabled = False
            Me.button3.Location = New System.Drawing.Point(288, 104)
            Me.button3.Size = New System.Drawing.Size(104, 32)
            Me.button3.TabIndex = 2
            Me.button3.Text = "Save Order"
            Me.ClientSize = New System.Drawing.Size(563, 273)
            Me.Controls.AddRange(New System.Windows.Forms.Control() {Me.listBox1, Me.button3, Me.button2, Me.button1, Me.textBox1, Me.checkedListBox1})
            Me.Text = "Fruit Order"
        End Sub 'InitializeComponent

        <STAThread()> _
        Public Shared Sub Main()
            Application.Run(New Form1())
        End Sub 'Main


        ' Adds the string if the text box has data in it.
        Private Sub button1_Click(sender As Object, _
                e As System.EventArgs) Handles button1.Click
            If textBox1.Text <> "" Then
                If checkedListBox1.CheckedItems.Contains(textBox1.Text) = False Then
                    checkedListBox1.Items.Add(textBox1.Text, CheckState.Checked)
                End If
                textBox1.Text = ""
            End If
        End Sub 'button1_Click

        ' Activates or deactivates the Add button.
        Private Sub textBox1_TextChanged(sender As Object, _
                e As System.EventArgs) Handles textBox1.TextChanged
            If textBox1.Text = "" Then
                button1.Enabled = False
            Else
                button1.Enabled = True
            End If
        End Sub 'textBox1_TextChanged


        ' Moves the checked items from the CheckedListBox to the listBox.
        Private Sub button2_Click(sender As Object, _
                e As System.EventArgs) Handles button2.Click
            listBox1.Items.Clear()
            button3.Enabled = False
            Dim i As Integer
            For i = 0 To checkedListBox1.CheckedItems.Count - 1
                listBox1.Items.Add(checkedListBox1.CheckedItems(i))
            Next i
            If listBox1.Items.Count > 0 Then
                button3.Enabled = True
            End If 
        End Sub 'button2_Click

        ' Activates the move button if there are checked items.
        Private Sub checkedListBox1_ItemCheck(sender As Object, _
                e As ItemCheckEventArgs) Handles checkedListBox1.ItemCheck
            If e.NewValue = CheckState.Unchecked Then
                If checkedListBox1.CheckedItems.Count = 1 Then
                    button2.Enabled = False
                End If
            Else
                button2.Enabled = True
            End If
        End Sub 'checkedListBox1_ItemCheck


        ' Saves the items to a file.
        Private Sub button3_Click(sender As Object, _
                e As System.EventArgs) Handles button3.Click
            ' Insert code to save a file.
            listBox1.Items.Clear()
            Dim myEnumerator As IEnumerator
            myEnumerator = checkedListBox1.CheckedIndices.GetEnumerator()
            Dim y As Integer
            While myEnumerator.MoveNext() <> False
                y = CInt(myEnumerator.Current)
                checkedListBox1.SetItemChecked(y, False)
            End While
            button3.Enabled = False
        End Sub 'button3_Click
    End Class 'Form1
End Namespace 'WindowsApplication1

namespace WindowsApplication1
{
   using System;
   using System.Drawing;
   using System.Collections;
   using System.ComponentModel;
   using System.Windows.Forms;
   using System.Data;
   using System.IO ;

   public class Form1 : System.Windows.Forms.Form
   {
      private System.Windows.Forms.CheckedListBox checkedListBox1;
      private System.Windows.Forms.TextBox textBox1;
      private System.Windows.Forms.Button button1;
      private System.Windows.Forms.Button button2;
      private System.Windows.Forms.ListBox listBox1;
      private System.Windows.Forms.Button button3;
        private System.ComponentModel.Container components;

      public Form1()
      {
            InitializeComponent();

         // Sets up the initial objects in the CheckedListBox.
            string[] myFruit = {"Apples", "Oranges","Tomato"};
         checkedListBox1.Items.AddRange(myFruit);

            // Changes the selection mode from double-click to single click.
         checkedListBox1.CheckOnClick = true;
      }

      protected override void Dispose( bool disposing )
      {
        if( disposing )
        {
            if (components != null) 
            {
              components.Dispose();
            }
        }
        base.Dispose( disposing );
      }

      private void InitializeComponent()
      {
         this.components = new System.ComponentModel.Container();
         this.textBox1 = new System.Windows.Forms.TextBox();
         this.checkedListBox1 = new System.Windows.Forms.CheckedListBox();
         this.listBox1 = new System.Windows.Forms.ListBox();
         this.button1 = new System.Windows.Forms.Button();
         this.button2 = new System.Windows.Forms.Button();
         this.button3 = new System.Windows.Forms.Button();
         this.textBox1.Location = new System.Drawing.Point(144, 64);
         this.textBox1.Size = new System.Drawing.Size(128, 20);
         this.textBox1.TabIndex = 1;
         this.textBox1.TextChanged += new System.EventHandler(this.textBox1_TextChanged);
         this.checkedListBox1.Location = new System.Drawing.Point(16, 64);
         this.checkedListBox1.Size = new System.Drawing.Size(120, 184);
         this.checkedListBox1.TabIndex = 0;
         this.checkedListBox1.ItemCheck += new System.Windows.Forms.ItemCheckEventHandler(this.checkedListBox1_ItemCheck);
         this.listBox1.Location = new System.Drawing.Point(408, 64);
         this.listBox1.Size = new System.Drawing.Size(128, 186);
         this.listBox1.TabIndex = 3;
         this.button1.Enabled = false;
         this.button1.Location = new System.Drawing.Point(144, 104);
         this.button1.Size = new System.Drawing.Size(104, 32);
         this.button1.TabIndex = 2;
         this.button1.Text = "Add Fruit";
         this.button1.Click += new System.EventHandler(this.button1_Click);
         this.button2.Enabled = false;
         this.button2.Location = new System.Drawing.Point(288, 64);
         this.button2.Size = new System.Drawing.Size(104, 32);
         this.button2.TabIndex = 2;
         this.button2.Text = "Show Order";
         this.button2.Click += new System.EventHandler(this.button2_Click);
         this.button3.Enabled = false;
         this.button3.Location = new System.Drawing.Point(288, 104);
         this.button3.Size = new System.Drawing.Size(104, 32);
         this.button3.TabIndex = 2;
         this.button3.Text = "Save Order";
         this.button3.Click += new System.EventHandler(this.button3_Click);
         this.ClientSize = new System.Drawing.Size(563, 273);
         this.Controls.AddRange(new System.Windows.Forms.Control[] {this.listBox1,
                                                        this.button3,
                                                        this.button2,
                                                        this.button1,
                                                        this.textBox1,
                                                        this.checkedListBox1});
         this.Text = "Fruit Order";
      }

      [STAThread]
      public static void Main(string[] args) 
      {
         Application.Run(new Form1());
      }

      // Adds the string if the text box has data in it.
      private void button1_Click(object sender, System.EventArgs e)
      {
         if(textBox1.Text != "")
         {
            if(checkedListBox1.CheckedItems.Contains(textBox1.Text)== false)
               checkedListBox1.Items.Add(textBox1.Text,CheckState.Checked);
            textBox1.Text = "";
         }

      }
      // Activates or deactivates the Add button.
      private void textBox1_TextChanged(object sender, System.EventArgs e)
      {
         if (textBox1.Text == "")
         {
            button1.Enabled = false;
         }
         else
         {
            button1.Enabled = true;
         }

        }

      // Moves the checked items from the CheckedListBox to the listBox.
      private void button2_Click(object sender, System.EventArgs e)
      {
         listBox1.Items.Clear();
         button3.Enabled=false;
         for (int i=0; i< checkedListBox1.CheckedItems.Count;i++)
         {
            listBox1.Items.Add(checkedListBox1.CheckedItems[i]);
         }
         if (listBox1.Items.Count>0)
            button3.Enabled=true;

      }
        // Activates the move button if there are checked items.
      private void checkedListBox1_ItemCheck(object sender, ItemCheckEventArgs e)
      {
         if(e.NewValue==CheckState.Unchecked)
         {
            if(checkedListBox1.CheckedItems.Count==1)
            {
               button2.Enabled = false;
            }
         }
         else
         {
            button2.Enabled = true;
         }
      }

        // Saves the items to a file.
      private void button3_Click(object sender, System.EventArgs e)
      {   
         // Insert code to save a file.
         listBox1.Items.Clear();
         IEnumerator myEnumerator;
         myEnumerator = checkedListBox1.CheckedIndices.GetEnumerator();
         int y;
         while (myEnumerator.MoveNext() != false)
         {
            y =(int) myEnumerator.Current;
            checkedListBox1.SetItemChecked(y, false);
         }
         button3.Enabled = false ;
      }        
    }
}

Visual C++

#using <System.Data.dll>
#using <System.Windows.Forms.dll>
#using <System.dll>
#using <System.Drawing.dll>

using namespace System;
using namespace System::Drawing;
using namespace System::Collections;
using namespace System::ComponentModel;
using namespace System::Windows::Forms;
using namespace System::Data;
using namespace System::IO;

public ref class Form1: public System::Windows::Forms::Form
{
private:
   System::Windows::Forms::CheckedListBox^ checkedListBox1;
   System::Windows::Forms::TextBox^ textBox1;
   System::Windows::Forms::Button^ button1;
   System::Windows::Forms::Button^ button2;
   System::Windows::Forms::ListBox^ listBox1;
   System::Windows::Forms::Button^ button3;
   System::ComponentModel::Container^ components;

public:
   Form1()
   {
      InitializeComponent();

      // Sets up the initial objects in the CheckedListBox.
      array<String^>^myFruit = {"Apples","Oranges","Tomato"};
      checkedListBox1->Items->AddRange( myFruit );

      // Changes the selection mode from double-click to single click.
      checkedListBox1->CheckOnClick = true;
   }

public:
   ~Form1()
   {
      if ( components != nullptr )
      {
         delete components;
      }
   }

private:
   void InitializeComponent()
   {
      this->components = gcnew System::ComponentModel::Container;
      this->textBox1 = gcnew System::Windows::Forms::TextBox;
      this->checkedListBox1 = gcnew System::Windows::Forms::CheckedListBox;
      this->listBox1 = gcnew System::Windows::Forms::ListBox;
      this->button1 = gcnew System::Windows::Forms::Button;
      this->button2 = gcnew System::Windows::Forms::Button;
      this->button3 = gcnew System::Windows::Forms::Button;
      this->textBox1->Location = System::Drawing::Point( 144, 64 );
      this->textBox1->Size = System::Drawing::Size( 128, 20 );
      this->textBox1->TabIndex = 1;
      this->textBox1->TextChanged += gcnew System::EventHandler( this, &Form1::textBox1_TextChanged );
      this->checkedListBox1->Location = System::Drawing::Point( 16, 64 );
      this->checkedListBox1->Size = System::Drawing::Size( 120, 184 );
      this->checkedListBox1->TabIndex = 0;
      this->checkedListBox1->ItemCheck += gcnew System::Windows::Forms::ItemCheckEventHandler( this, &Form1::checkedListBox1_ItemCheck );
      this->listBox1->Location = System::Drawing::Point( 408, 64 );
      this->listBox1->Size = System::Drawing::Size( 128, 186 );
      this->listBox1->TabIndex = 3;
      this->button1->Enabled = false;
      this->button1->Location = System::Drawing::Point( 144, 104 );
      this->button1->Size = System::Drawing::Size( 104, 32 );
      this->button1->TabIndex = 2;
      this->button1->Text = "Add Fruit";
      this->button1->Click += gcnew System::EventHandler( this, &Form1::button1_Click );
      this->button2->Enabled = false;
      this->button2->Location = System::Drawing::Point( 288, 64 );
      this->button2->Size = System::Drawing::Size( 104, 32 );
      this->button2->TabIndex = 2;
      this->button2->Text = "Show Order";
      this->button2->Click += gcnew System::EventHandler( this, &Form1::button2_Click );
      this->button3->Enabled = false;
      this->button3->Location = System::Drawing::Point( 288, 104 );
      this->button3->Size = System::Drawing::Size( 104, 32 );
      this->button3->TabIndex = 2;
      this->button3->Text = "Save Order";
      this->button3->Click += gcnew System::EventHandler( this, &Form1::button3_Click );
      this->ClientSize = System::Drawing::Size( 563, 273 );
      array<System::Windows::Forms::Control^>^temp0 = {this->listBox1,this->button3,this->button2,this->button1,this->textBox1,this->checkedListBox1};
      this->Controls->AddRange( temp0 );
      this->Text = "Fruit Order";
   }

   // Adds the string if the text box has data in it.
   void button1_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {
      if (  !textBox1->Text->Equals( "" ) )
      {
         if ( checkedListBox1->CheckedItems->Contains( textBox1->Text ) == false )
                  checkedListBox1->Items->Add( textBox1->Text, CheckState::Checked );
         textBox1->Text = "";
      }
   }

   // Activates or deactivates the Add button.
   void textBox1_TextChanged( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {
      if ( textBox1->Text->Equals( "" ) )
      {
         button1->Enabled = false;
      }
      else
      {
         button1->Enabled = true;
      }
   }

   // Moves the checked items from the CheckedListBox to the listBox.
   void button2_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {
      listBox1->Items->Clear();
      button3->Enabled = false;
      for ( int i = 0; i < checkedListBox1->CheckedItems->Count; i++ )
      {
         listBox1->Items->Add( checkedListBox1->CheckedItems[ i ] );

      }
      if ( listBox1->Items->Count > 0 )
            button3->Enabled = true;
   }

   // Activates the move button if there are checked items.
   void checkedListBox1_ItemCheck( Object^ /*sender*/, ItemCheckEventArgs^ e )
   {
      if ( e->NewValue == CheckState::Unchecked )
      {
         if ( checkedListBox1->CheckedItems->Count == 1 )
         {
            button2->Enabled = false;
         }
      }
      else
      {
         button2->Enabled = true;
      }
   }

   // Saves the items to a file.
   void button3_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {
      // Insert code to save a file.
      listBox1->Items->Clear();
      IEnumerator^ myEnumerator;
      myEnumerator = checkedListBox1->CheckedIndices->GetEnumerator();
      int y;
      while ( myEnumerator->MoveNext() != false )
      {
         y = safe_cast<Int32>(myEnumerator->Current);
         checkedListBox1->SetItemChecked( y, false );
      }

      button3->Enabled = false;
   }
};

[STAThread]
int main()
{
   Application::Run( gcnew Form1 );
}

Inheritance Hierarchy

System..::.Object
  System..::.MarshalByRefObject
    System.ComponentModel..::.Component
      System.Windows.Forms..::.Control
        System.Windows.Forms..::.ListControl
          System.Windows.Forms..::.ListBox
            System.Windows.Forms..::.CheckedListBox

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

Reference

CheckedListBox Members

System.Windows.Forms Namespace

ListBox

Other Resources

CheckedListBox Control (Windows Forms)