Windows Forms: Working with CheckedListBox (VB.NET)

아티클
1/17/2024

This article provides core basics for working with a Windows Form control CheckedListBox from populating with string, setting the DataSource to a DataTable to a List along with getting/setting checked items, finding items, limiting checked items and more. There will be a discussion on creating a custom CheckedListBox control versus having a decent understanding of the CheckedListBox to decide if a custom CheckedListBox is needed or work with the standard CheckedListBox.

CheckedListBox overview

The CheckedListBox provides the capability to show text along with a Checkbox for each item within the control which allows a user to select one or more items. For example, presenting a options dialog for an application where each item presented in the CheckedListBox would allow the user to customize the user experience, another case would be to present items for building a product with options to the standard product.

Populating

There are various ways to populate a CheckedListBox

With string

For fixed items that will not change type in items at design time.

Or use a standard collection like month names.

Imports System.Globalization
 
Public Class  Form1
    Private Sub  Form1_Load(sender As  Object, e As EventArgs) Handles MyBase.Load
 
        MonthsCheckedListBox.Items.AddRange(
            (
               From month In  CultureInfo.CurrentCulture.DateTimeFormat.MonthNames
               Where Not  String.IsNullOrEmpty(month)).ToArray
            )
 
        MonthsCheckedListBox.SelectedIndex = Now.Month -1
 
    End Sub
End Class

With classes

A class may be used by setting the CheckedListBox.DataSource with a list of a concrete class. To display a specific property for the Text property set the DisplayMember or override the ToString method.

In the example below the class overrides ToString with ProductName so there is no need to set DisplayMember. If DisplayMember is not set and ToString is not overridden at runtime the object type is shown which does not good.

Namespace DataClasses
    Public Class  Product
        Public Property  ProductID As  Integer
        Public Property  ProductName As  String
        Public Property  SupplierID As  Integer?
        Public Property  CategoryID As  Integer?
        Public Property  QuantityPerUnit As  String
        Public Property  UnitPrice As  Decimal?
        Public Property  UnitsInStock As  Short?
        Public Property  UnitsOnOrder As  Short?
        Public Property  ReorderLevel As  Short?
        Public Property  Discontinued As  Boolean
        Public Property  DiscontinuedDate As  DateTime?
 
        Public Overrides  Function ToString() As String
            Return ProductName
        End Function
    End Class
End Namespace

Data is returned from a database table while other options range from reading items from a file or from a service.

Imports System.Data.SqlClient
Imports BaseConnectionLibrary
Namespace DataClasses
    Public Class  SqlServerOperations
        Inherits ConnectionClasses.SqlServerConnection
 
        Public Sub  New()
            DefaultCatalog = "NorthWindAzure1"
            DatabaseServer = "KARENS-PC"
        End Sub
        Public Function  ProductsByCategoryIdentifier(pCategoryIdentifier As Integer) As  List(Of Product)
            Dim productList As New  List(Of Product)
 
            Dim selectStatement =
                    <SQL>
                    SELECT ProductID
                          ,ProductName
                          ,SupplierID
                          ,QuantityPerUnit
                          ,UnitPrice
                          ,UnitsInStock
                          ,UnitsOnOrder
                          ,ReorderLevel
                          ,Discontinued
                          ,DiscontinuedDate
                      FROM NorthWindAzure1.dbo.Products
                      WHERE CategoryID = <%= pCategoryIdentifier %>
                    </SQL>.Value
 
 
            Using cn As  New SqlConnection With {.ConnectionString = ConnectionString}
                Using cmd As  New SqlCommand With {.Connection = cn, .CommandText = selectStatement}
 
                    Try
                        cn.Open()
 
                        Dim reader = cmd.ExecuteReader()
 
                        While reader.Read()
                            productList.Add(New Product() With
                               {
                                   .ProductID = reader.GetInt32(0),
                                   .ProductName = reader.GetString(1),
                                   .Discontinued = reader.GetBoolean(8)
                               })
                        End While
 
                    Catch ex As Exception
                        mHasException = True
                        mLastException = ex
                    End Try
                End Using
 
            End Using
 
            Return productList
 
        End Function
    End Class
End Namespace

In the form an import statement is used as the class above is in a different namespace than the form. The SqlServerOperations class is created as a private variable which means methods are always available in the form. a List of Product is returned and set as the DataSource for the CheckedListBox.

Imports CheckOnlyOneItem.DataClasses
Public Class  Form1
    Private operations As SqlServerOperations = New SqlServerOperations()
    Private Sub  Form1_Load(sender As  Object, e As EventArgs) Handles MyBase.Load
        Dim products = operations.ProductsByCategoryIdentifier(1)
        CheckedListBox1.DataSource = products
    End Sub

Presentation at runtime.

To select an item, in this case, the selected item, cast to Product as the DataSource is a List(Of Product). Some property is Nothing because they were never set.

To check an item use SetItemChecked which accepts the index of the item to check and the checked state of true or false.

CheckedListBox1.SetItemChecked(0, True)

Checking items

For CheckedListBox populated with string cast Items property to string and using a for next to find the item then use the indexer of the for as the index into the CheckedListBox to use SetItemChecked(foundIndex, true or false).

When dealing with a List or a DataTable the following extension methods keep code clean and perform similarly as with using string but with LINQ statements.

Imports FindAndCheckItem.DataClasses
 
Namespace Extensions
    Module ExtensionMethods
        ''' <summary>
        ''' Find a specific product by name and check or uncheck the item if found
        ''' </summary>
        ''' <param name="sender"></param>
        ''' <param name="pValueToLocate">Product name</param>
        ''' <param name="pChecked">True to check, False to uncheck</param>
        <Runtime.CompilerServices.Extension()>
        Public Sub  FindItemAndSetChecked(
            sender As  CheckedListBox,
            pValueToLocate As  String,
            Optional pChecked As Boolean  = True)
 
            Dim result =
                    (
                        From this In  sender.Items.Cast(Of Product)().Select(Function(item, index) New  With
                           {
                               .Item = item,
                               .Index = index
                           })
                        Where this.Item.ProductName = pValueToLocate
                    ).FirstOrDefault
 
            If result IsNot Nothing Then
                sender.SetItemChecked(result.Index, pChecked)
            End If
 
        End Sub
        ''' <summary>
        ''' Find a specific value by field name and value in a DataTable
        ''' </summary>
        ''' <param name="sender"></param>
        ''' <param name="pValueToLocate">Value to find</param>
        ''' <param name="pFieldName">Field to locate in</param>
        ''' <param name="pChecked">True to check, False to uncheck</param>
        <Runtime.CompilerServices.Extension()>
        Public Sub  FindItemAndSetChecked(
            sender As  CheckedListBox,
            pValueToLocate As  String,
            pFieldName As  String,
            Optional pChecked As Boolean  = True)
 
            Dim result =
                    (
                        From this In  sender.Items.Cast(Of DataRowView)().Select(Function(item, index) New  With
                            {.Item = item, .Index = index})
                        Where this.Item.Row.Field(Of String)(pFieldName).ToLower = pValueToLocate.ToLower
                    ).FirstOrDefault
 
            If result IsNot Nothing Then
                sender.SetItemChecked(result.Index, pChecked)
            End If
 
        End Sub
    End Module
End Namespace

To check in the List(Of Product) the following seeks two products and if found checks each product in the CheckedListBox.

Imports FindAndCheckItem.DataClasses
Imports FindAndCheckItem.Extensions
 
Public Class  Form1
    Private operations As SqlServerOperations = New SqlServerOperations()
    Private Sub  Form1_Load(sender As  Object, e As EventArgs) Handles MyBase.Load
 
        Dim products = operations.ProductsByCategoryIdentifier(1)
        CheckedListBox1.DataSource = products
 
        CheckedListBox1.FindItemAndSetChecked("Steeleye Stout")
        CheckedListBox1.FindItemAndSetChecked("Outback Lager")
 
    End Sub
End Class

Get checked items

Use GetItemChecked(desired index). In the following example, ItemCheck event is used to see if the current item is checked and if so append or remove from a multi-line TextBox.

Imports TrackingCheckedItems.DataClasses
 
Public Class  Form1
    Private operations As SqlServerOperations = New SqlServerOperations()
    Private Sub  Form1_Load(sender As  Object, e As EventArgs) Handles MyBase.Load
        Dim products = operations.ProductsByCategoryIdentifier()
        CheckedListBox1.DataSource = products
    End Sub
    ''' <summary>
    ''' Change Product.Selected dependent on the check state of the current item.
    ''' 
    ''' Show checked products in the TextBox, in a real application this might be
    ''' done in a button click for making a final selection for the current process.
    ''' 
    ''' </summary>
    ''' <param name="sender"></param>
    ''' <param name="e"></param>
    Private Sub  CheckedListBox1_ItemCheck(sender As Object, e As  ItemCheckEventArgs) Handles CheckedListBox1.ItemCheck
 
        CType(CheckedListBox1.Items(e.Index), Product).Selected = Not  CheckedListBox1.GetItemChecked(e.Index)
 
        TextBox1.Text = String.Join(Environment.NewLine, CType(CheckedListBox1.DataSource, List(Of Product)).
                                       Where(Function(product) product.Selected).
                                       Select(Function(product) product.DisplayData).ToArray())
    End Sub
End Class

Obtain checked item names the following extension method provides names.

<Runtime.CompilerServices.Extension()>
Public Function  CheckedItemsNamesList(sender As CheckedListBox) As List(Of String)
 
    Dim results As New  List(Of String)
 
    For index As Integer  = 0 To  (sender.Items.Count - 1)
        If sender.GetItemChecked(index) Then
            results.Add(sender.Items(index).ToString)
        End If
    Next
 
    Return results
End Function

Usage

Dim productItems = CheckedListBox1.CheckedItemsNamesList()
 
For Each  productItem As  String In  productItems
    Console.WriteLine(productItem)
Next

The above is works but means to gain access to each product a find operation must be performed on the CheckedListBox.DataSource casted as a List(Of Product), a better method are to get checked indexes of the CheckedListBox using the following language extension.

<Runtime.CompilerServices.Extension()>
Public Function  CheckedItemsIndexesList(sender As CheckedListBox) As List(Of Integer)
 
    Dim results As New  List(Of Integer)
 
    For index As Integer  = 0 To  (sender.Items.Count - 1)
        If sender.GetItemChecked(index) Then
            results.Add(index)
        End If
    Next
 
    Return results
 
End Function

The usage which gets each product using the index returned from the extension method above. In this case, the ProductName is shown as ToString has been overridden as shown above in the Product class.

For index As Integer  = 0 To  productItems.Count - 1
    Dim product = CType(CheckedListBox1.Items(index), Product)
    Console.WriteLine(product)
Next

Disabling items from being checked

Consider an application which allows users to purchase items using a CheckedListBox. They open the application on Monday and a product they want appears, they end up thinking about the product and not purchase but come back the next day and the product is not shown. The developer dynamically populated the CheckedListBox with available items and on the next day it’s out of stock and not shown. This may leave the customer frustrated. Consider checking specific items disallows other options in the CheckedListBox. There are several options, remove/add using business logic, presenting a message if the item is not available because other options are checked or disable the item(s).

Disabling items coupled with text on the form to indicate why one or more items are not available or use a tooltip. To disable item(s) a custom CheckedListBox which requires a fair amount of knowledge for coding may be used or write a few lines of code.

In this case for using a standard CheckedListBox against products that are discontinued. Products are loaded including the field which indicates if the product is discontinued (another option is to check stock level available).

Public Function  ProductsByCategoryIdentifier(pCategoryIdentifier As Integer) As  List(Of Product)
    Dim productList As New  List(Of Product)
 
    Dim selectStatement =
            <SQL>
            SELECT ProductID
                  ,ProductName
                  ,SupplierID
                  ,QuantityPerUnit
                  ,UnitPrice
                  ,UnitsInStock
                  ,UnitsOnOrder
                  ,ReorderLevel
                  ,Discontinued
                  ,DiscontinuedDate
              FROM NorthWindAzure1.dbo.Products
              WHERE CategoryID = <%= pCategoryIdentifier %>
            </SQL>.Value
 
 
    Using cn As  New SqlConnection With {.ConnectionString = ConnectionString}
        Using cmd As  New SqlCommand With {.Connection = cn, .CommandText = selectStatement}
 
            Try
                cn.Open()
 
                Dim reader = cmd.ExecuteReader()
 
                While reader.Read()
                    productList.Add(New Product() With
                                       {
                                           .ProductID = reader.GetInt32(0),
                                           .ProductName = reader.GetString(1),
                                           .Discontinued = reader.GetBoolean(8)
                                       })
                End While
 
            Catch ex As Exception
                mHasException = True
                mLastException = ex
            End Try
        End Using
 
    End Using
 
    Return productList
 
End Function

Products are loaded by a category identifier, in a real application there would be control, ComboBox or ListBox populated with a List(Of Category), upon selected item change cast the selected item to a Category and get the Category id.

Dim products = operations.ProductsByCategoryIdentifier(6)

In the form Load or Shown event add items to the CheckedListBox as follows marking discontinued products with an Indeterminate CheckState.

'
' Set state to Indeterminate then enforce the state in ItemCheck event
'
For Each  product As  Product In  products
    If product.Discontinued Then
        CheckedListBox1.Items.Add(product, CheckState.Indeterminate)
    Else
        CheckedListBox1.Items.Add(product)
    End If
Next

Subscribe to ItemCheck event of the CheckedListBox, if the CurrentValue is Indeterminate then reset it which keeps the item disabled.

Check one item

Although only permitting one checked item is not something normally done this question has been asked on the web several times. To only permit one checked item subscribe to the ItemCheck event and check the current item NewValue for CheckState.Checked, if so iterate all items and if a checked item is found other than the current item using SetItemChecked to false.

Imports CheckOnlyOneItem.DataClasses
Public Class  Form1
    Private operations As SqlServerOperations = New SqlServerOperations()
    Private Sub  Form1_Load(sender As  Object, e As EventArgs) Handles MyBase.Load
        Dim products = operations.ProductsByCategoryIdentifier(1)
        CheckedListBox1.DataSource = products
    End Sub
    Private Sub  CheckedListBox1_ItemCheck(sender As Object, e As  ItemCheckEventArgs) Handles CheckedListBox1.ItemCheck
        If e.NewValue = CheckState.Checked Then
            For index As Integer  = 0 To  CheckedListBox1.Items.Count - 1
                If index <> e.Index Then
                    CheckedListBox1.SetItemChecked(index, False)
                End If
            Next
        End If
    End Sub
End Class

Select all option

For providing the ability to check or uncheck all iterate all items in a button click event using SetItemChecked or use a custom CheckedListBox found here in the included source code.

Properties of interest

CheckOnClick

By default two clicks are required to check or uncheck items, to perform a check or uncheck with one click set the property CheckOnClick in the CheckedListBox property window of in code.

CheckedItems

A collection of checked items, when the DataSource is a List using Cast to cast the items to the specific type

Dim checkedProducts = CheckedListBox1.CheckedItems.Cast(Of Product)

CheckedIndices

This property provides a collection of checked indexes in the CheckedListBox.

Dim productIndexes = CheckedListBox1.CheckedIndices
 
For index As Integer  = 0 To  productIndexes.Count - 1
    Dim product = CType(CheckedListBox1.Items(index), Product)
    Console.WriteLine(product)
Next

Running sample code

Create a SQL-Server database and running the following script.
Each project with SqlServerOperation class change the server name and default catalog as per this sample.
Right click on solution explorer top node, select "Restore NuGet Packages"
Build the solution
Run each project.

Required NuGet package

BaseConnectionLibrary - source code project.

Summary

This article has shown how to utilize a CheckedListBox in common scenarios and several uncommon scenarios using classes as the data source for the CheckedListBox while use of DataTable may be used although using a DataTable has extra baggage not needed e.g. events, methods to change the state of data rows etc. Keep in mind when considering a CheckedListBox if this is the right option over conventional Checkbox controls.

Source code

Source code provided in the following GitHub repository.

다음을 통해 공유