Introduction
The purpose of this article is to discuss the construction of a couple of simple custom controls that extend both the Combobox and the Listbox controls to allow them to be associated with both a text and a value property for each item in the control's list. Both controls will normally allow the developer to assign a value property and a text property to each item in the list but only if the control is bound to a data source. If the control is not bound, the option to immediately assign a value to an item in the list is not available.
If one requires that both text and a value be assigned to each item in the list, it is easy enough define a class containing a text and value property of some type and to then create a collection of objects of that type and bind that collection to the control. In this approach, the developer may need also to need to write handlers to get the value associated with a selected item, to remove items form the list, and to add items to the list (along with a value). If there are a large number controls, writing these additional functions to handle each specific control can be somewhat tedious.
There are a number of reasons why it could be beneficial to supply both a text and value property to an unbound list based control item. In general, if it is not productive, expedient, or even possible to bind a list based control to a data source and the value property is meaningless to the user but essential to the application, having the means to supply the value property along with the user friendly text can be pretty handy.
This demo includes a
project with two extended, list based controls capable of holding both a text
and a value property without binding, and it contains a demonstration project in
which the two controls are used.
Figure 1: Demo Project with Extended
Combobox and Listbox in Use.
The demo application shown if figure 1 uses both the extended Combobox and Listbox controls; the extended Listbox contains the alphabet in phonetic format; the text property contains the phonetic alphabet whilst the value property contains a not to user friendly pipe delimited string of dots and dashes used to define the Morse code equivalent for the letter. I picked on the Morse code to supply the value because whilst most people would easily recognize that Alpha stands for 'A' and Bravo stands for 'B'; they would not so easily recognize that |...|---|...| means "SOS" or that |...|-.-.|.|-|-| represents "Scott" in Morse code.
Just for fun, when the user selects one of the options from the extended Listbox, the application displays both the phonetic (text) property and Morse code (value) property in the two textboxes below the extended Combobox. Also, when an item is selected, the application will decipher the Morse code (value) and play it aloud so the user can hear the Morse code whilst seeing the phonetic alphabet character and string representation of the Morse code. The two buttons located adjacent to each text box are used to retrieve the value property from the text property or the text property from the value property. The only purpose of either is to demonstrate that it can be done.
The extended Combobox control is used in a manner similar to the extended Listbox but it does not play any Morse code through the speakers. It displays the names of different truck manufacturers along with a number used to identify that manufacturer. As with the Listbox, the Combobox contains two text boxes beneath it which are used to display the text and value properties for the selected item. It also uses two button controls to either pull up the value from the text or the text from the value.
Getting Started
The solution contains
two projects; one is a class library project containing two custom controls and
the other is a demonstration Windows application that contains a single
form. The two controls contained in the class library project are an extended
version of each the ComboBox and the ListBox control. The form in the
demonstration application contains both types of custom control along with some
additional controls used to exercise the custom controls.
Figure 2: Solution Explorer.
Project: Extended List Controls
The extended list controls project is a class library project that contains two custom controls: ExComboBox.cs and ExListBox.cs. The controls are extended versions of the standard toolbox controls; the purpose of the extension of each control was to add in a collection (a SortedList) and to provide the additional code necessary to give access to the collection and to display the members of the collections is the control's standard list. Since both controls are essentially the same except for the type of control extended, I will only describe one of the two control's code; the code for the ExComboBox.cs control is as follows:
The class contains the following references, namespace and class declaration; note the addition of System.Collections and System.Windows.Forms:
Imports System.Windows.Forms
Imports System.Runtime.InteropServices
Imports System.Collections
Public Class ExComboBox
Inherits System.Windows.Forms.ComboBox
The class declaration shows that the class is based upon and extends the standard Combobox control. By inheriting the combobox control, we pick up all of the functionality associated with that control. Following the class declaration, a sorted list is declared, and in the constructor, a new instance of the sorted list is created:
''' <summary>
''' sorted list used to retain
''' text and value pairs for the unbound
''' extended combobox control
''' </summary>
''' <remarks></remarks>
Private mListCollection As SortedList
''' <summary>
''' Constructor
''' </summary>
''' <remarks></remarks>
Public Sub New()
'Instance the collection in
'the constructor
mListCollection = New SortedList()
End Sub
The sorted list, "mListCollection" will be used to contain the text and value pairs assigned to each item in the control's list. Following the constructor, the first method is defined:
''' <summary>
''' Provides public method to both add items to private
''' collection of text-value pairs and to reload the
''' combobox list with the items from the key side of the
''' sortedlist items
''' </summary>
''' <param name="sText"></param>
''' <param name="sValue"></param>
''' <remarks></remarks>
Public Sub AddListItem(ByVal sText As String, ByVal sValue As String)
Try
mListCollection.Add(sText, sValue)
Catch
Return
End Try
Me.Items.Clear()
Dim de As DictionaryEntry
For Each de In mListCollection
Me.Items.Add(de.Key.ToString())
Next
End Sub
The AddListItem method defined above is used to add key-value pairs to the sorted list. The attempt to add an item is wrapped in a try catch block; this will prevent attempts to load duplicate keys from interfering with the application; if the user does attempt to enter duplicate keys, the attempt will fail the application will return from the method call without changing the sorted list.One could rig this method to return Boolean value indicating the success of the operation. After the item has been added to the sorted list, the combobox is cleared of all items and each item from the newly updated sorted list is then added back into the list.
The next method defined is used to remove an item from the sorted list; this method works very much the same as the code used to add an item:
''' <summary>
''' Remove the key item from the private sortedlist if
''' the item matches the text passed into this
''' public subroutine
''' </summary>
''' <param name="sText"></param>
''' <remarks></remarks>
Public Sub RemoveListItem(ByVal sText As String)
Try
mListCollection.Remove(sText)
Catch
Return
End Try
Me.Items.Clear()
Dim de As DictionaryEntry
For Each de In mListCollection
Me.Items.Add(de.Key.ToString())
Next
End Sub
The next bit of code in the control is used to get the value associated with an item contained in the list. Selection of the returned item is based upon the current selected index value from the control's standard list:
''' <summary>
''' Get the value associated with a control list item
''' based upon the selected index value
''' </summary>
''' <returns></returns>
''' <remarks></remarks>
Public Function GetValue() As String
Try
Return Convert.ToString(mListCollection.GetByIndex
_(Me.SelectedIndex))
Catch
Return String.Empty
End Try
End Function
If the item is not found in the list, the method returns an empty string.
The next method in the class is used to return the value associated with a list item's text. The value is obtained by examining the contents of the list until the value text is found and then, per the found text, the value is obtained and returned as a string. If the value is not located, an empty string is returned:
''' <summary>
''' A public method to return the value associated with the
''' text (key) from the private sorted list based upon a
''' match of the string passed to this method against the
''' key values in the sorted list; if nothing matches, an
''' emptry string will be returned.
''' </summary>
''' <param name="sText"></param>
''' <returns></returns>
''' <remarks></remarks>
Public Function GetValueByText(ByVal sText As String) As String
Dim tmp As String = String.Empty
Try
Dim de As DictionaryEntry
For Each de In mListCollection
If de.Key.ToString = sText Then
tmp = de.Value.ToString()
End If
Next
Return tmp
Catch
Return tmp
End Try
End Function
The last method in the control's code is used to obtain the text for a list item based upon its value:
''' <summary>
''' Return the text of an item based upon its value; if the
''' items is not found, return an empty string.
''' </summary>
''' <param name="sValue"></param>
''' <returns></returns>
''' <remarks></remarks>
Public Function GetTextByValue(ByVal sValue As String) As String
Dim tmp As String = String.Empty
Try
Dim de As DictionaryEntry
For Each de In mListCollection
If de.Value.ToString = sValue Then
tmp = de.Key.ToString()
End If
Next
Return tmp
Catch
Return tmp
End Try
End Function
Note that since only the text side is guaranteed to be unique, if the collection contained multiple values of the same content, this method will return the first item found that meets the criteria. The important method is therefore one that retrieves the value associated with the unique key (text) property. The value of this last function will be limited unless the user of the control limits the list to items unque as both text and value.
That wraps up the code in the custom control. As mention previously, the extended ListBox control works in exactly the same manner with the same methods and properties available.
Project: Test Collection Controls (Demonstration Project)
This project contains a single form and one of each of the two custom controls (along with some other controls used in conjunction with those custom controls.
The form contains two group boxes; in the top box is an extended ListBox control along with two text boxes and two buttons. When a user makes a selection from the custom control, the event handler for that control will be used to place the related text and value properties into each of the two text boxes. The two buttons are used along with text boxes to pull up the value from the text or the text from the value. In this case, the custom control is populated with all of the letters defined in the phonetic alphabet on the text side and the Morse code representation of the letter in the value side. Morse code values are displayed in the form of a pipe delimited string made up of dots and dashes. Further, when the item is selected, the value is sent to a method that deciphers the Morse code and plays it aloud through the speakers.
The second group box contains an extended ComboBox control; this control is populated with a list comprised of the names of truck manufacturers along with an arbitrary six digit identifier. This group box also contains two text boxes and two buttons that are also used to display the value and text properties associated with items contained in the control's sorted list. The buttons here are used to display the value associated with the selected text and the text associated with selected value.
The form class code starts out with the following references, namespace, and class declaration:
Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Text
Imports System.Windows.Forms
Imports System.Runtime.InteropServices
''' <summary>
''' Demo application used to test the extended listbox
''' and combobox controls
''' </summary>
''' <remarks></remarks>
Join the conversation! Your thoughts help the community grow.