Noting some confusion in the Greater Google on the subject of the CheckedListBox, I want to make it clear that this article is about the WINFORMS CheckedListBox class (System.Windows.Forms.CheckedListBox), NOT the WebForms CheckBoxList class (System.Web.UI.WebControls.CheckBoxList). So back to your Postbacks all you WebForms freaks.
Generating CheckedListBox Text
The CheckedListBox is a ListBox which includes a CheckBox to the left of the display text. The display text is computed using the ToString method of the object in the Items collection of the CheckedListBox.
It is also possible, however, to generate the text in each CheckedListBox entry by associating the CheckedListBox with a DataSource and setting the DisplayMember field of the CheckedListBox.
Microsoft do not encourage the use of CheckedListBox DataSource. None of the DataSource, DisplayMember or ValueMember members of CheckedListBox appear in the Intellisense for the control or in the Designer Properties Window because Microsoft has added the Browsable=false attribute to these properties. In the MSDN example, programmers are referred directly to the Items collection as the means of wiring up the control:
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.
Microsoft MSDN advises users not to use the DataSource member of CheckedListBox because this control is not intended to be DataBound and unpredictable results can ensue if you use the control in a DataBound way. However the DataSource, ValueMember and DisplayMember members can be used as I discovered from Moz2 in this MSDN social forum thread
Why Would You Bother ?
It’s a fair question. For me, I needed to produce a Windows Form with identical look and feel to an existing form which utilised a CheckedListBox, but for processing efficiency also required a SelectedValue member. That led me into a fruitful Googling session which I am now sharing with you.
Setting CheckedListBox DataSource
You can set the DataSource to any Collection. But you must set DataSource after DisplayMember is set. Here’s some VB.NET for your reading pleasure:
'Event Handler for WebSiteType dropdown selected index changed
'Update Listed Domains in CheckBox List clbWebDomain based on selected WebSiteType
Private Sub cboWebSiteType_SelectedIndexChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles cboWebSiteType.SelectedIndexChanged
Me.clbWebDomain.DataSource = Nothing
Me.clbWebDomain.Items.Clear()
...Update Me.WebDomainMappingList...
Me.clbWebDomain.ValueMember = "DomainCode"
Me.clbWebDomain.DisplayMember = "URL"
Me.clbWebDomain.DataSource = Me.WebDomainMappingList
...Code to initialise clbWebDomain.Items.....
End Sub
WebDomainMappingList is a GenericList of my Custom Class WebDomainMapping.
Since that WebDomainMapping Class is only used for temporary processing, I actually implemented it as a Structure. I didn’t put in a ToString implementation as I wanted it clear via the DisplayMember that I wanted to display the URL property…and that leads me to my next point, the DisplayMember and ValueMember members must refer to Properties of the Objects/Structures in the Items collection of your CheckedListBox. They cannot be mere fields otherwise your CheckedListBox will fill up with garbage.
Therefore, the following will NOT work:
Friend Structure WebDomainMapping
Dim URL As String
Dim DomainCode As Integer
End Structure
Putting an Object/Structure like this into the Items collection of a CheckedListBox and then using the URL property as a DisplayMember will cause the following output to your CheckedListBox for all the entries. This is actually the default ToString() representation of the object in your CheckedListBox Items Collection
Namespace.frmReport+WebDomainMapping
Namespace.frmReport+WebDomainMapping
etc.
An Object/Structure definition like this will work. It wlll allow URL to be used as the DisplayMember of the CheckedListBox.
Friend Structure WebDomainMapping
Private _URL As String
Public Property URL() As String
Get
Return _URL
End Get
Set (ByVal value As String)
_URL = value
End Set
End Property
Private _DomainCode As Integer
...Property Declaration for DomainCode....
End Structure
Directly Initialise The Items Collection Too
It is not enough merely to initialise the DataSource member of CheckedListBox. You must also directly initialise the Items Collection if you don’t do this you will not get anything at all displayed in the CheckedListBox.
Naturally, the Items collection must contain EXACTLY the same Objects as the DataSource.
Remember, true DataBinding as represented by DataSource, DisplayMember and ValueMember is not officially supported for this control, so utilising these members may not provide the functionality you would expect or may not work at all. For example, here the Items Collection is not automatically populated by assigning the DataSource. What you can do, as I have done, is patch together an implementation or approximation of DataBinding for CheckedListBox. The functionality, or at least most of it, is there because it is inherited from Base Controls.
Final Caveats
The partial implementation of DataBinding in CheckedListBox and hence its flaky functionality is recognised by Microsoft as a bug (see preceeding links), but there is no guarantee this will be fixed to support full DataBinding. Microsoft may decide to chop DataSource from CheckedListBox entirely. I used the above workaround in version 2.0 of the Framework. Who knows, it might be gone or not work at all in later versions.
Why DataBinding Can Only Be To Properties and not Fields
Nikhail Koltari who is a Software Architect at Microsoft, explains some of the reasons why here.
(In this case the Visual Studio Repair.