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 associate both a text and a value property with 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 and to then create a collection of objects of that type and then 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 useful.
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 Combobox contains the alphabet in phonetic format; the text property contains the phonetic alphabet while 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 Combobox, 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 extended Listbox control is used in a manner similar to the extended Combobox but it does not play any Morse code through the speakers. It displays the names of different truck manufacturers along with an number used to identify that manufacturer. As with the Combobox, the Listbox 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 contains two custom controls: CollectionComboBox.cs and CollectionListBox.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 CollectionComboBox.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:
using System;
using System.Collections;
using System.ComponentModel;
using System.Text;
using System.Windows.Forms;
namespace ExtendedListControls
{
/// <summary>
/// The class ties the combobox list to the contents of a
/// sortedlist; the sortedlist is used to maintain a
/// key and value pair for use primarily with unbound
/// versions of the control (where text and value columns
/// from a data source would normally be used to set
/// each list item's text and value property.
/// </summary>
public class CollectionComboBox : 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, and sorted list is declared, and in the constructor, a new instance of the sorted list is created:
/// <summary>
/// Declare a local sortedlist to maintain
/// text and value properties for the unbound
/// combobox
/// </summary>
private SortedList mListCollection;
// constructor
public CollectionComboBox()
{
// create new instance of
// the sortedlist
mListCollection = new SortedList();
}
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>
/// Add text and value items to the sorted list
/// directly
/// </summary>
/// <param name="sText"></param>
/// <param name="sValue"></param>
public void AddListItem(string sText, string sValue)
{
try
{
mListCollection.Add(sText, sValue);
}
catch { return; }
// reload the control with the current list
this.Items.Clear();
foreach (DictionaryEntry de in mListCollection)
{
this.Items.Add(de.Key.ToString());
}
}
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 an item from the control
/// </summary>
/// <param name="sText"></param>
/// <returns></returns>
public void RemoveListItem(string sText)
{
try
{
mListCollection.Remove(sText);
}
catch { return; }
// reload the control with the current list
this.Items.Clear();
foreach (DictionaryEntry de in mListCollection)
{
this.Items.Add(de.Key.ToString());
}
}
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>
/// Return the value of an item from its selected index
/// value
/// </summary>
/// <returns></returns>
public string GetValue()
{
try
{
Return Convert.ToString(mListCollection.GetByIndex(this.SelectedIndex));
}
catch
{
return string.Empty;
}
}
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>
/// Return the value of an item based upon its text; if the
/// item is not found, return an empty string
/// </summary>
/// <param name="sText"></param>
/// <returns></returns>
public string GetValueByText(string sText)
{
string tmp = string.Empty;
try
{
foreach (DictionaryEntry de in mListCollection)
{
if (de.Key.ToString() == sText)
{
tmp = de.Value.ToString();
}
}
return tmp;
}
catch
{
return tmp;
}
}
The last method in the control's code is used to obtain the text for a list item based upon its key:
/// <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>
public string GetTextByValue(string sValue)
{
string tmp = string.Empty;
try
{
foreach (DictionaryEntry de in mListCollection)
{
if (de.Value.ToString() == sValue)
{
return de.Key.ToString();
}
}
return tmp;
}
catch
{
return tmp;
}
}
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 ComboBox control along with two text boxes and two buttons. When a user makes a selection from the extended ComboBox, 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 ListBox 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:
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;
using System.Runtime.InteropServices;
namespace TestCollectionControls
{
/// <summary>
/// A test application demonstrating the use of the
/// extended combobox and listbox controls
/// </summary>
public partial class Form1 : Form
{
Note the addition of a reference to System.Runtime.InteropServices; this is used to support the DLL Import of the Beep method which is used to play the Morse code sounds.
After the class declaration, the following code is inserted to import the beep method from the kernal32 DLL:
/// <summary>
/// Use the beep function to play the Morse code
/// character equivalents
/// </summary>
/// <param name="frequency"></param>
/// <param name="duration"></param>
/// <returns></returns>
[DllImport("kernel32.dll")]
private static extern bool Beep(int frequency, int duration);
The next bit of code is used to manage the constructor and the form load event; the constructor is in the default configuration while in the form load event, the custom controls are manually populated with text and values using each control's public "AddListItem" method; this method accepts two arguments, the key and the value, which are loaded into the control's internal sorted list. When the sorted list is updated, the contents of the controls visible list is updated to display text added through the method:
public Form1()
{
InitializeComponent();
}
/// <summary>
/// On load, adds a set of key-value pairs to a
/// custom combobox control
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void Form1_Load(object sender, EventArgs e)
{
// manually populate the list with the key and
// value pairs - This loads the extended
// combobox with the phonetic alphabet and
// the Morse code equivalent represented
// by a pipe delimited string containing
// dots and dashes
this.ccb1.AddListItem("Alpha", "|.|-|");
this.ccb1.AddListItem("Bravo", "|-|.|.|.|");
this.ccb1.AddListItem("Charlie", "|-|.|-|.|");
this.ccb1.AddListItem("Delta", "|-|.|.|");
this.ccb1.AddListItem("Echo", "|.|");
this.ccb1.AddListItem("Foxtrot", "|.|.|-|.|");
this.ccb1.AddListItem("Golf", "|-|-|.|");
this.ccb1.AddListItem("Hotel", "|.|.|.|.|");
this.ccb1.AddListItem("India", "|.|.|");
this.ccb1.AddListItem("Juliette", "|.|-|-|-|");
this.ccb1.AddListItem("Kilo", "|-|.|-|");
this.ccb1.AddListItem("Lima", "|.|-|.|.|");
this.ccb1.AddListItem("Mike", "|-|-|");
this.ccb1.AddListItem("November", "|-|.|");
this.ccb1.AddListItem("Oscar", "|-|-|-|");
this.ccb1.AddListItem("Papa", "|.|-|-|.|");
this.ccb1.AddListItem("Quebec", "|-|-|.|-|");
this.ccb1.AddListItem("Romeo", "|.|-|.|");
this.ccb1.AddListItem("Sierra", "|.|.|.|");
this.ccb1.AddListItem("Tango", "|-|");
this.ccb1.AddListItem("Uniform", "|.|.|-|");
this.ccb1.AddListItem("Victor", "|.|.|.|-|");
this.ccb1.AddListItem("Whiskey", "|.|-|-|");
this.ccb1.AddListItem("Xray", "|-|.|.|-|");
this.ccb1.AddListItem("Yankee", "|-|.|-|-|");
this.ccb1.AddListItem("Zulu", "|-|-|.|.|");
// Populate the extended listbox control with
// the names of some trucks along with some otherwise
// meaningless values
this.clb1.AddListItem("Mack", "012393");
this.clb1.AddListItem("Peterbuilt", "234234");
this.clb1.AddListItem("International Harvester", "345432");
this.clb1.AddListItem("White Freightliner", "213453");
this.clb1.AddListItem("Kenworth", "856745");
this.clb1.AddListItem("GMC General", "234865");
this.clb1.AddListItem("Ford", "328975");
this.clb1.AddListItem("Ivenco", "675474");
this.clb1.AddListItem("Magirus", "666873");
this.clb1.AddListItem("Isuzu", "343445");
this.clb1.AddListItem("Volvo", "648857");
this.clb1.AddListItem("Dodge", "111349");
}
The next item up in the form code is the selected index changed event handler for the custom ComboBox control; this handler sets the text showing the selected text and the associatd value for the selected item. It further sends the value to a separate method that is used to play the Morse code version of the selected item.
/// <summary>
/// Using the custom combobox control to retrieve
/// text-value pairs
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void ccb1_SelectedIndexChanged(object sender, EventArgs e)
{
// do something with the key and the value
this.txtSelectText.Text = ccb1.SelectedItem.ToString();
this.txtSelectValue.Text = ccb1.GetValue();
this.Refresh();
PlayMorseCode(txtSelectValue.ToString());
}
The two button handlers for the custom ComboBox control are next, the first is used to get the value associated with the text contained in the text box while the second does the opposite and gets the text associated with the value. Both are displayed in a message box once they have been retrieved from the custom control's internal sorted list through the appropriate method call.
/// <summary>
/// Get the value associated with the key
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void btnGetValue_Click(object sender, EventArgs e)
{
string tmp = string.Empty;
if (txtSelectText.Text != string.Empty)
tmp = ccb1.GetValueByText(txtSelectText.Text.ToString());
MessageBox.Show("'" + tmp + "' is the matching value.","Get Value from Text");
}
/// <summary>
/// Get the key associated with the value - Extended Combobox
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void btnGetKey_Click(object sender, EventArgs e)
{
string tmp = string.Empty;
if (txtSelectValue.Text != string.Empty)
tmp = ccb1.GetTextByValue(txtSelectValue.Text.ToString());
MessageBox.Show("'" + tmp + "' is the matching Text.","Get Text from Value");
}
The next item up is the selected index changed event handler for the custom ListBox control.
/// <summary>
/// Using the custom listbox control to retrieve
/// text-value pairs - Extended Listbox control
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void clb1_SelectedIndexChanged(object sender, EventArgs e)
{
// put the text and value properties into the
// two textboxes used to show them
this.txtSelectText2.Text = clb1.SelectedItem.ToString();
this.txtSelectValue2.Text = clb1.GetValue();
}
After that, the next two items handle the button click events for the two buttons used with the custom ListBox control and its associated text boxes.
/// <summary>
/// Retrieve the value from the key - Extended Listbox control
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void btnGetValue2_Click(object sender, EventArgs e)
{
string tmp = string.Empty;
if (txtSelectText2.Text != string.Empty)
tmp = clb1.GetValueByText(txtSelectText2.Text.ToString());
MessageBox.Show("'" + tmp + "' is the matching value.","Get Value from Text");
}
/// <summary>
/// Retrieve the key from the value - Extended Listbox control
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void btnGetKey2_Click(object sender, EventArgs e)
{
string tmp = string.Empty;
if (txtSelectValue2.Text != string.Empty)
tmp = clb1.GetTextByValue(txtSelectValue2.Text.ToString());
MessageBox.Show("'" + tmp + "' is the matching Text.","Get Text from Value");
}
After the event handlers, the next bit of code is a method used to play the Morse code equivalent of letter selected from the alphabet. The method parses the contents of the Morse code string passed to it and plays the appropriate sequence of dits an and da's aloud.
/// <summary>
/// Use the passed in value string containing the dots and
/// dashes defining the Morse code representation of the
/// character and play the Morse code version of the letter
/// aloud through the speakers.
/// </summary>
/// <param name="sMorseCode"></param>
private void PlayMorseCode(string sMorseCode)
{
string[] ditAndDa = sMorseCode.Split('|');
foreach(string s in ditAndDa)
{
switch (s)
{
case ".":
// play dit
Beep(900, 100);
// create a small dwell between sounds
System.Threading.Thread.Sleep(50);
break;
case "-":
// play da
Beep(900, 300);
// create a small dwell between sounds
System.Threading.Thread.Sleep(50);
break;
default:
break;
}
}
}
The last in the form class is merely used to handle the exit button click event.
/// <summary>
/// Exit the application
/// </summary>
/// <param name="sender"></param>
/// <param name="e"></param>
private void btnExit_Click(object sender, EventArgs e)
{
Application.Exit();
}
Summary.
This article was intended to demonstrate one approach to building a custom control that would permit the user to associate a value property with the items contained in the list of an unbound list based control such as ComboBox or ListBox. The method demonstrated consisted of constructing a simple custom control that maintains a sorted list associated with the control's standard list. The custom control also provides a nominal number of methods used to obtain the value or text associated with an item selected from the list. Since the standard list based controls do not support a value property for the control unless the control is bound, the approach demonstrated offers a simple work around that can be used if it is considered desirable to apply a value to each list item contained in an unbound control.
The control presented is quite simple and could be improved upon greatly; for example if one were to modify the control to permit the user of the control to edit the collection through a collection editor at design time that may be more appealing to some than manually keying in the collection.