The WinComboBox class represents an extensible and themable multi-column combobox for Windows Forms. It supports both the Windows XP and classic Windows themes. The WinComboBox control can contain any of the Xceed editors as well as any other .NET control. 

Textbox area

The WinComboBox control is a container control which contains an inner textbox. All of the inner textbox's properties and events are accessed via the WinComboBox control's TextBoxArea. Any properties that are set directly on the WinComboBox control will also affect any embedded child controls. For example, if the ForeColor property of the WinComboBox control is set to Color.Green, then the foreground color of all the embedded controls, including the TextBoxArea, will be changed to green. If the ForeColor property of the TextBoxArea is set to Color.Green, then only the foreground color of the TextBoxArea will be changed to green.

Columns and items

The WinComboBox control is a multi-column combobox where each column is represented by a ColumnInfo object, and each item (line) is represented by a ComboBoxItem object. Columns are accessible via the Columns collection while items are accessible via the Items collection. The item that is currently selected in the combobox is represented by the SelectedItem/ SelectedIndex properties. 

The suggested method of adding items to a combobox is to first add the desired columns (specifying various characteristics) and then to add the items. The datatype of the values in the items that are added must match the datatype of the corresponding columns, and each item must contain the same number of values as there are columns in the combobox. If the number of values is greater than or less than the number of columns, or if their datatype is different than the corresponding column's, an exception will be thrown. 

Items can either be added either directly as ComboBoxItem's, or as comma separated values (as demonstrated below).

Dim combo As New WinComboBox()
combo.Columns.Add( New ColumnInfo( "Country", GetType( String ) ) )
combo.Columns.Add( New ColumnInfo( "Population", GetType( Integer ) ) )
combo.Columns.Add( New ColumnInfo( "City", GetType( String ) ) )
combo.Columns.Add( New ColumnInfo( "AverageTemp", GetType(   String   ) ) )
combo.Items.Add( "Canada", 31500000, "Ottawa", "12.2 ºc" )
combo.Items.Add( "Switzerland", 7300000, "Bern", "23.3 ºc" )
combo.Items.Add( "France", 59500000, "Paris", "27.3 ºc" )
combo.Items.Add( "USA", 278000000, "Washington", "14.1 ºc" )
combo.Items.Add( "UK", 59700000, "London", "23.7 ºc" )
combo.Items.Add( "Belgium", 10300000, "Brussels", "21.8 ºc" )
combo.Items.Add( "Italy", 57700000, "Rome", "29.6 ºc" )
combo.Items.Add( "Spain", 40000000, "Madrid", "31.8 ºc" )
combo.Items.Add( "Germany", 83000000, "Berlin", "25.1 ºc" )
combo.Items.Add( "Japan", 126800000, "Tokyo", "17.2 ºc" )
combo.Location = New Point( 10 , 10 )
Me.Controls.Add( combo )

WinComboBox combo = new WinComboBox();
combo.Columns.Add( new ColumnInfo( "Country", typeof( string ) ) );
combo.Columns.Add( new ColumnInfo( "Population", typeof( int ) ) );     
combo.Columns.Add( new ColumnInfo( "City", typeof( string ) ) );
combo.Columns.Add( new ColumnInfo( "AverageTemp", typeof(   string   ) ) );
combo.Items.Add( "Canada", 31500000, "Ottawa", "12.2 ºc" );
combo.Items.Add( "Switzerland", 7300000, "Bern", "23.3 ºc" );
combo.Items.Add( "France", 59500000, "Paris", "27.3 ºc" );
combo.Items.Add( "USA", 278000000, "Washington", "14.1 ºc" );
combo.Items.Add( "UK", 59700000, "London", "23.7 ºc" );
combo.Items.Add( "Belgium", 10300000, "Brussels", "21.8 ºc" );
combo.Items.Add( "Italy", 57700000, "Rome", "29.6 ºc" );
combo.Items.Add( "Spain", 40000000, "Madrid", "31.8 ºc" );
combo.Items.Add( "Germany", 83000000, "Berlin", "25.1 ºc" );
combo.Items.Add( "Japan", 126800000, "Tokyo", "17.2 ºc" );
combo.Location = new Point( 10 , 10 );
this.Controls.Add( combo );

The values of items that are added to the combobox using the suggested method (demonstrated above) can then be accessed using either their index or corresponding column name. For example, to retrieve the third value of the first item ("Ottawa"), either of the following examples could be used:

Dim cityName As String
cityName = CType( combo.Items( 0 )( "City" ), String )
' or
Dim cityName As String
cityName = CType( combo.Items( 0 )( 2 ), String )

string cityName = ( string )combo.Items[ 0 ][ "City" ];
// or
string cityName = ( string )combo.Items[ 0 ][ 2 ];

Although it is suggested that columns be added to the combobox prior to adding items (lines), it is not an obligation. Items can be added without first adding columns; however, the following rules apply:

The following example demonstrates how to add items to the WinComboBox without previously adding columns (ColumnInfo objects). Unlike the previous examples, items will be added as ComboBoxItems and not as comma separated values.

Dim combo As New WinComboBox()
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "Canada", 31500000, "Ottawa", "12.2 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "Switzerland", 7300000, "Bern", "23.3 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "France", 59500000, "Paris", "27.3 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "USA", 278000000, "Washington", "14.1 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "UK", 59700000, "London", "23.7 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "Belgium", 10300000, "Brussels", "21.8 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "Italy", 57700000, "Rome", "29.6 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "Spain", 40000000, "Madrid", "31.8 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "Germany", 83000000, "Berlin", "25.1 ºc" } ) )
combo.Items.Add( New ComboBoxItem( New Object( 3 ){ "Japan", 126800000, "Tokyo", "17.2 ºc" } ) )
combo.Location = New Point( 10 , 10 )
Me.Controls.Add( combo )

WinComboBox combo = new WinComboBox();
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "Canada", 31500000, "Ottawa", "12.2 ºc" } ) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "Switzerland", 7300000, "Bern", "23.3 ºc" } ) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "France", 59500000, "Paris", "27.3 ºc" } ) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "USA", 278000000, "Washington", "14.1 ºc" } ) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "UK", 59700000, "London", "23.7 ºc" } ) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "Belgium", 10300000, "Brussels", "21.8 ºc" }) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "Italy", 57700000, "Rome", "29.6 ºc" } ) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "Spain", 40000000, "Madrid", "31.8 ºc" } ) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "Germany", 83000000, "Berlin", "25.1 ºc" } ) );
combo.Items.Add( new ComboBoxItem( new object[ 4 ]{ "Japan", 126800000, "Tokyo", "17.2 ºc" } ) );
combo.Location = new Point( 10 , 10 );
this.Controls.Add( combo );

The items that are contained in the WinComboBox control can be sorted according to the values of one or more columns (ColumnInfo objects). Setting the SortDirection property of a ColumnInfo object to ColumnSortDirection.Ascending will sort the values of the column (and thus the items in the combobox) in ascending order. Setting the SortDirection property to ColumnSortDirection.Descending will sort the values in descending order. By default, the SortDirection property is set to ColumnSortDirection.None, indicating that the values of the column are not sorted. 

The SortIndex property can be used to determine the order in which the columns are sorted. For example, if both the "Country" and "City" columns are sorted and have a respective SortIndex of 0 and 1, then the items in the combobox will first be sorted according to the values of the "Country" column and then by the values of the "City" column. 

Once ColumnInfo objects have been added to the combobox, their SortIndex property cannot be modified; however, the ColumnInfo object has a constructor which allows you to specify both the SortIndex and SortDirection of a column. 

The following example demonstrates how to sort the items in a combobox according to the values of the "Country" column:

Dim combo As New WinComboBox()
combo.Columns.Add( New ColumnInfo( "Country", GetType( String ), 0, _
                                   ColumnSortDirection.Ascending ) )
combo.Columns.Add( New ColumnInfo( "Population", GetType( Integer ) ) )
combo.Columns.Add( New ColumnInfo( "City", GetType( String ) ) )
combo.Columns.Add( New ColumnInfo( "AverageTemp", GetType(   String   ) ) )
combo.Items.Add( "Canada", 31500000, "Ottawa", "12.2 ºc" )
combo.Items.Add( "Switzerland", 7300000, "Bern", "23.3 ºc" )
combo.Items.Add( "France", 59500000, "Paris", "27.3 ºc" )
combo.Items.Add( "USA", 278000000, "Washington", "14.1 ºc" )
combo.Items.Add( "UK", 59700000, "London", "23.7 ºc" )
combo.Items.Add( "Belgium", 10300000, "Brussels", "21.8 ºc" )
combo.Items.Add( "Italy", 57700000, "Rome", "29.6 ºc" )
combo.Items.Add( "Spain", 40000000, "Madrid", "31.8 ºc" )
combo.Items.Add( "Germany", 83000000, "Berlin", "25.1 ºc" )
combo.Items.Add( "Japan", 126800000, "Tokyo", "17.2 ºc" )
   
combo.Location = New Point( 10, 10 )
Me.Controls.Add( combo )

WinComboBox combo = new WinComboBox();
combo.Columns.Add( new ColumnInfo( "Country", typeof( string ), 0, _
                ColumnSortDirection.Ascending ) );
combo.Columns.Add( new ColumnInfo( "Population", typeof( int ) ) );     
combo.Columns.Add( new ColumnInfo( "City", typeof( string ) ) );
combo.Columns.Add( new ColumnInfo( "AverageTemp", typeof(   string   ) ) );
combo.Items.Add( "Canada", 31500000, "Ottawa", "12.2 ºc" );
combo.Items.Add( "Switzerland", 7300000, "Bern", "23.3 ºc" );
combo.Items.Add( "France", 59500000, "Paris", "27.3 ºc" );
combo.Items.Add( "USA", 278000000, "Washington", "14.1 ºc" );
combo.Items.Add( "UK", 59700000, "London", "23.7 ºc" );
combo.Items.Add( "Belgium", 10300000, "Brussels", "21.8 ºc" );
combo.Items.Add( "Italy", 57700000, "Rome", "29.6 ºc" );
combo.Items.Add( "Spain", 40000000, "Madrid", "31.8 ºc" );
combo.Items.Add( "Germany", 83000000, "Berlin", "25.1 ºc" );
combo.Items.Add( "Japan", 126800000, "Tokyo", "17.2 ºc" );
combo.Location = new Point( 10, 10 );
this.Controls.Add( combo );

SelectedValue and ValueMember

The ValueMember property will determine which of the SelectedItem's values is returned by the SelectedValue property. For example, if the combobox contains 3 columns whose names are "LastName", "FirstName", and "Age", setting the ValueMember property to "FirstName" will return the value contained in the selected item's "FirstName" field.

Displaying images

To display images in the WinComboBox, the ImageMember property must be set to the name of the field in the datasource from which to retrieve the value. The position, alignment, padding, size, and style of the images can be defined by the ImagePosition, ImageAlignment, ImagePadding, ImageSize, and ImageStyle properties respectively. For example:

Dim combo As New WinComboBox( dataSet11, "Employees", "EmployeeID", "Photo", _
                              ImagePosition.Left, new Size( 32, 32 ), "%FirstName% %LastName%" )
combo.SelectedIndex = 0
combo.Height = 36
Me.Controls.Add( combo )

WinComboBox combo = new WinComboBox( dataSet11, "Employees", "EmployeeID", "Photo",
                                     ImagePosition.Left, new Size( 32, 32 ),
                                     %FirstName% %LastName%" );      
combo.SelectedIndex = 0;
combo.Height = 36;
this.Controls.Add( combo );

Column width and item height

The width of the columns in the combobox is adjusted according to the value of the ColumnWidthAdjustment property. If set to FitToItems, the width of each column will be adjusted to the width of its largest (longest) value. If set to ExtendLastColumn (default), the width of the last column will be adjusted to fit the remainder of the space to its right, and the other columns will have a width of 100 pixels. If set to None, the Width property of each column (by default, 100 pixels) will decide the width. 

The size of the dropdown is determined by the DropDownSize property (by default, 296 x 250 pixels), while the height of each item is determined by the ItemHeight property (by default, 17 pixels). The maximum number of items that can be displayed in the dropdown is determined by the MaxDropDownItems property (by default -1: an unlimited number of items can be displayed). Setting the MaxDropDownItems property to a value of 1 or more will prevent the dropdown from resizing past the point where the specified number of items have been displayed. The remaining items can be accessed using the scrollbar. 

The IntegralHeight property indicates if the height of the control should be adjusted to completely display the last visible item in the dropdown (by default, true). The IntegralHeight property can also be considered as a "vertical resizing step ratio". For example, if set to true, when the dropdown is vertically resized, the step will be the height of the individual child items resulting in the last visible item always being completely displayed. If set to false, the height of the dropdown will be adjusted pixel by pixel thus allowing for the last visible item to be partially displayed.     

Note that the value of the MaxDropDownItems property will only be taken into consideration if IntegralHeight is set to true. 

Dropdown Style

The dropdown style of the WinCombBox control is determined by the AllowFreeText property. If AllowFreeText is set to true (default), any text can be written into the WinComboBox; however, pressing the Enter or TAB key will not select an item in the dropdown. This is the equivalent of setting the DropDownStyle property of the Windows Forms ComboBox control to DropDown. 

If AllowFreeText is set to false, only the first letter of the items located in the dropdown can be entered into the combobox. For example, pressing "S" will select the first item in the dropdown that has an uppercase "S" as its first letter. If no items begin with a uppercase "S", the current item will remain the selected item. If an item begins with a lowercase "s", it will not be selected if an uppercase "S" is entered. This is the equivalent of setting the DropDownStyle property of the Windows Forms ComboBox control to DropDownList.   

Searching for items

The SearchMode property indicates the mode to use when searching for items in the WinComboBox. Items are searched for according to their string representation which is determined by the WinComboBox control's DisplayFormat property. For example, let's assume that the WinComboBox has 3 columns and 3 items with the following values: 

Plante, Martin, 34
Drimonakos, Mathieu, 24
Ledoux, Pierre-Luc, 25 

If the DisplayFormat property is set to "%Column2% %Column1% %Column3%", the string representation of the items will be: 

Martin Plante 34
Mathieu Drimonakos 24
Pierre-Luc Ledoux 25 

Entering "p" in the WinComboBox control will select "Pierre-Luc Ledoux 25" rather than "Martin Plante 34" because the string representation of the items is used rather than the physical order of the values/colums. If the DisplayFormat had not been modified, "%Column1%, %Column2%, %Column3%", "Plante, Martin, 34" would have been selected and not "Ledoux, Pierre-Luc, 25". 

The value of the CompareType property can influence the search behavior. By default, the CompareType property is set to CompareType.ExactMatch, therefore cases and accents are respected. Setting the CompareType property to CaseInsensitive, AccentInsensitive, or CaseAndAccentInsensitive will change the way in which items are searched for. For example, if the CompareType property is set to AccentInsensitive, accents contained in the string representation of an item will be ignored, resulting in "ö" and "o" being considered as equal values. 

The Find method allows you to find a specific string or value within a specific column at (optionally) a start index. When searching for a string, an (optional) search pattern can be provided to search for strings that begin or end with the specified string, or that contain the string. If no search pattern is specified, Find will search for the exact string. Note that the Find method is case-sensitive! 

For example, in the code below, the Find method is used to assign the item whose "Country" column contains "Italy". Since a search pattern is not specified, the Find method will search for the first instance of "Italy" as an exact string.

Dim combo As New WinComboBox()
combo.Columns.Add( New ColumnInfo( "Country", GetType( String ) ) )
combo.Columns.Add( New ColumnInfo( "Population", GetType( Integer ) ) )      
combo.Columns.Add( New ColumnInfo( "City", GetType( String ) ) )
combo.Columns.Add( New ColumnInfo( "AverageTemp", GetType(   String ) ) )
combo.Items.Add( "Canada", 31500000, "Ottawa", "12.2 ºc" )
combo.Items.Add( "Switzerland", 7300000, "Bern", "23.3 ºc" )
combo.Items.Add( "France", 59500000, "Paris", "27.3 ºc" )
combo.Items.Add( "USA", 278000000, "Washington", "14.1 ºc" )
combo.Items.Add( "UK", 59700000, "London", "23.7 ºc" )
combo.Items.Add( "Belgium", 10300000, "Brussels", "21.8 ºc" )
combo.Items.Add( "Italy", 57700000, "Rome", "29.6 ºc" )
combo.Items.Add( "Spain", 40000000, "Madrid", "31.8 ºc" )
combo.Items.Add( "Germany", 83000000, "Berlin", "25.1 ºc" )
combo.Items.Add( "Japan", 126800000, "Tokyo", "17.2 ºc" )
combo.SelectedIndex = combo.Find( "Italy", "Country" )
      
combo.Location = New Point( 10, 10 )
Me.Controls.Add( combo )

WinComboBox combo = new WinComboBox();
combo.Columns.Add( new ColumnInfo( "Country", typeof( string ) ) );
combo.Columns.Add( new ColumnInfo( "Population", typeof( int ) ) );      
combo.Columns.Add( new ColumnInfo( "City", typeof( string ) ) );
combo.Columns.Add( new ColumnInfo( "AverageTemp", typeof(   string   ) ) );
combo.Items.Add( "Canada", 31500000, "Ottawa", "12.2 ºc" );
combo.Items.Add( "Switzerland", 7300000, "Bern", "23.3 ºc" );
combo.Items.Add( "France", 59500000, "Paris", "27.3 ºc" );
combo.Items.Add( "USA", 278000000, "Washington", "14.1 ºc" );
combo.Items.Add( "UK", 59700000, "London", "23.7 ºc" );
combo.Items.Add( "Belgium", 10300000, "Brussels", "21.8 ºc" );
combo.Items.Add( "Italy", 57700000, "Rome", "29.6 ºc" );
combo.Items.Add( "Spain", 40000000, "Madrid", "31.8 ºc" );
combo.Items.Add( "Germany", 83000000, "Berlin", "25.1 ºc" );
combo.Items.Add( "Japan", 126800000, "Tokyo", "17.2 ºc" );
combo.SelectedIndex = combo.Find( "Italy", "Country" );
      
combo.Location = new Point( 10 , 10 );
this.Controls.Add( combo );