This topic is dedicated to providing an overview of the xamMultiColumnComboEditor™ control. In the following examples, you will learn how to configure and work with the editor and see how it can help you improve the user experience of your applications.
This document contains the following sections:
The following table lists the prerequisites required for this topic:
The table below lists the main features of the xamMultiColumnComboEditor.
In order to populate the xamMultiColumnComboEditor control with data you must set its ItemsSource property to the given data source. You can use any IEnumerable collection of objects.
Note: The control doesn’t support adding items directly, so you must have an IEnumerable to bind it to.
The xamMultiColumnComboEditor control can automatically generate columns for every public property on the data object that is contained in the IEnumerable that is set on the control’s ItemsSource property. The control’s AutoGenerateColumns property (which defaults to True) controls this behavior. Alternatively you can set AutoGenerateColumns to False and manually specify which columns to display by creating and adding columns directly to the control’s Columns collection:
In XAML:
<ig:XamMultiColumnComboEditor
x:Name="xamMultiColumnComboEditor"
DisplayMemberPath="Company"
AutoGenerateColumns="False">
<ig:XamMultiColumnComboEditor.Columns>
<ig:ImageComboColumn
Key="ImagePath" MaximumWidth="60" ImageWidth="50"/>
<ig:TextComboColumn Key="ContactName"/>
<ig:TextComboColumn Key="Company"/>
</ig:XamMultiColumnComboEditor.Columns>
</ig:XamMultiColumnComboEditor>
The supported column types are:
CheckboxComboColumn – use to show Boolean values with a CheckBox control
DateComboColumn – use to show dates
TextComboColumn – use to display string information
ImageComboColumn – use to show images. You can load an Image either by binding the Key to a property containing the Uri to the image or binding to a property of type BitmapImage.
The xamMultiColumnComboEditor control provides great flexibility in programmatically controlling the dropdown.
When users start typing, the dropdown always opens in a direction chosen automatically by the control in order to show the entire dropdown.
You can use the control’s Footer property to specify arbitrary content that should appear in the Footer area of the dropdown. A FooterTemplate property is also available to let you control the layout of the Footer content.
To make selecting multiple items more convenient for users you can show a checkbox in each row by setting the CheckBoxVisibility property to Visible. When the AllowMultipleSelection property is set to True, users can select several items (by clicking on the rows or by marking their checkboxes) in single interaction and without having to hold down the CTRL key.
When the SelectedItemsResetButtonVisibility property is set to Visible, a button is displayed in the edit area of the control which can be clicked by the user to clear the current selection.
The xamMultiColumnComboEditor control exposes a FilterMode property that lets you control how the dropdown list is filtered as user type text into the control’s text area. The FilterMode enumeration contains 2 values:
FilterOnPrimaryColumnOnly – filters items in the dropdown list by including only the items which primary column* starts with the text typed in the control’s TextBox
FilterOnAllColumns - filters the items in the dropdown list by including only those items that contain the text typed in the control’s TextBox in any text column
* The ‘primary column’ is defined as the column specified via the control’s DisplayMemberPath property.
Note: The control automatically performs auto completion of user typed text when the FilterMode property is set to FilterOnPrimaryColumnOnly.
Custom filtering is also available with the xamMultiColumnComboBox control. In order to use custom filtering you should define the rules in an instance of the ItemsFilter class and set it to the control’s CustomItemsFilter property.
The following example demonstrates how to setup an item filter:
In Visual Basic:
Dim filter As New ItemsFilter()
filter.ObjectTypedInfo =
New CachedTypedInfo() With { _
.CachedType = GetType(Person)
}
filter.Conditions.LogicalOperator = LogicalOperator.[Or]
filter.Conditions.Add(New ComparisonCondition() With { _
.[Operator] = ComparisonOperator.EndsWith, _
.FilterValue = "" _
})
XamMultiColumnComboEditor.CustomItemsFilter = filter
In C#:
ItemsFilter filter = new ItemsFilter();
filter.ObjectTypedInfo = new CachedTypedInfo()
{
CachedType = typeof(Person)
};
filter.Conditions.LogicalOperator = LogicalOperator.Or;
filter.Conditions.Add(new ComparisonCondition()
{
Operator = ComparisonOperator.EndsWith,
FilterValue = ""
});
xamMultiColumnComboEditor.CustomItemsFilter = filter;
You can control the behavior of the control when users type in the text box of the control by configuring the CustomValueEnteredAction property. There are three values contained in CustomValueEnteredActions enumeration:
Ignore - prevents the user from typing in invalid data – the keystrokes are considered as a filter for the ComboBox thus no new value can be entered
Allow - allows items to be typed, but no items are selected and the underlying ItemsSource remain untouched
Add - adds the typed data to the underlying ItemsSource and the new addition becomes valid data for selection
You can configure the selection mode of the control by setting the AllowMultipleSelection property. When set to True users can choose multiple items that are displayed as comma separated strings by default. If you want to change the delimiter you can set the MultiSelectValueDelimiter property to the desired character. Therefore, when users select multiple items, the control displays the primary column (DisplayMemberPath) values of each selected item. Selected items are joined in the selection string with the MultiSelectValueDelimiter character.
The screenshot below shows a xamMultiColumnComboEditor with multiple items selected where the MultiSelectValueDelimiter is set to a semicolon.
When AllowMultipleSelection is set to True users can add new items to the selection by clicking on an item while holding the CTRL key. If you want to let the user choose multiple items using a pointing device exclusively you can set the CheckBoxVisibility property to Visible. The check boxes allow users to check multiple RowSelectionCheckbox items without requiring use of the keyboard.
Following are some other topics you may find useful.