CheckedListBox Class
Displays a ListBox in which a check box is displayed to the left of each item.
Assembly: System.Windows.Forms (in System.Windows.Forms.dll)
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. | |
Checked items (including items in an indeterminate state), which is a subset of the items contained in the CheckedListBox control. | |
Checked indexes, which is a subset of the indexes into the items collection. These indexes specify items in a checked or indeterminate state. |
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 | |
1 | Object 2 | |
2 | Object 3 | |
3 | Object 4 | |
4 | Object 5 |
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 |
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.
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
System.MarshalByRefObject
System.ComponentModel.Component
System.Windows.Forms.Control
System.Windows.Forms.ListControl
System.Windows.Forms.ListBox
System.Windows.Forms.CheckedListBox
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.
Note: