Sdl.MultiSelectComboBox (WPF Custom Control)

Overview

The multi selection combo box is a WPF custom control with multiple item selection capabilities, along with customizable features to group, sort and filter items in the collection.

Components and Features

Selected Items Panel

The selected items are displayed like tags with a remove button They can be added or removed from the selected items collection, by selecting them from the items present in the Dropdown Menu list. Additionally, items can also be removed by interacting with them directly from the Selected Items Panel, as follows:

Visual States

The control has two visual states, Readonly and EditMode, which is identified by the IsEditMode property. When the control is in readonly mode, the items cannot be edited from the view. To switch to edit mode, select the control in the view or hit (F2) when the control has focus. Once the control is in edit mode, the items can be filtered, selected or removed. To switch back to readonly, move focus away from the control by selecting any other control in the view or by deactivating the parent window.

Visual state	Description	Example
Readonly	The Dropdown Menu is collapsed and items present in the Selected Items Panel cannot be edited.
EditMode	The Dropdown Menu can be expanded or collapsed when the button is clicked and items present in the Selected Items Panel can be edited.

Filter Criteria

When you type a character in the text area, the control applies a filter on the collection and suggests a list of items matching that criteria in the Dropdown Menu list. The developer can override the default filter service, based on their own business logic requirements, that implements IFilterService.

Depending on whether or not the ClearFilterOnDropdownClosing property is set to true and Dropdown Menu list as keyboard focus, the Filter Criteria is cleared automatically as the Dropdown Menu is closing.

Dropdown Menu

Presents a list of suggestions that can be selected by the user. If no Filter Criteria is applied, then all items in the collection are displayed

Visibility

The Dropdown Menu can be expanded only when the control is in EditMode.

Item Group

The items in the collection can be grouped by implementing IItemGroupAware. In addition to the header name, this interface exposes a property to manage the order in which the group headers are displayed.

Item Sorting

The sort order is based on the order of the items in the collection that was received when the ItemsSource is set.

Item Selection

Items can be added or removed from the selected items collection, by selecting them from the items present in the Dropdown Menu list.

Disabled Item

Implement IItemEnabledAware to identify whether or not the items are enabled. When an item is not enabled, then it will not be selectable from the Dropdown Menu list and removed from the Selected Items Panel automatically.

Selected Item

Items in the Dropdown Menu list can be selected/unselected via the Mouse or Keyboard. When the item is selected, the style is updated to reflect a selected state.

Example Project

The example project demonstrates how to implement the Sdl.MultiSelectComboBox custom control to your project, and provides good examples in understanding the controls behaviours.

Examples

The following example creates an Sdl.MultiSelectComboBox. The example populates the control by binding the ItemsSource property to a collection of type object, that implements IItemEnabledAware and IItemGroupAware. The example also binds the SelectedItemsChangedBehaviour to a command to receive a notification of SelectedItemsChangedEventArgs whenever the selected items collection changes and then display those results in a TextBlock on the view. Additionally, both the selected and dropdown list item templates are customized to display an image along with the item name.

Example.xaml

<Window x:Class="MultiSelectComboBoxExample.Example"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:sdl="http://schemas.sdl.com/xaml"
        xmlns:models="clr-namespace:MultiSelectComboBoxExample.Models"
        d:DataContext="{d:DesignInstance {x:Type models:LanguageItems}}"
        mc:Ignorable="d"
        Title="Example" Height="250" Width="400">
    <Window.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <ResourceDictionary Source="Resources/MultiSelectComboBox.Resources.xaml"/>              
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Window.Resources>
    <Grid>
        <StackPanel Orientation="Vertical">
            <sdl:MultiSelectComboBox Height="100"
                ItemsSource="{Binding Items}"
                IsEditable="true"
                SelectionMode="Multiple"
                SelectedItemTemplate="{StaticResource MultiSelectComboBox.SelectedItems.ItemTemplate}"
                DropdownItemTemplate="{StaticResource MultiSelectComboBox.Dropdown.ListBox.ItemTemplate}"
                sdl:SelectedItemsChangedBehaviour.SelectedItemsChanged="{Binding SelectedItemsChangedCommand}"/>
            <TextBlock Text="{Binding Path=EventLog}" Height="100"/>
        </StackPanel>
    </Grid>
</Window>

DataTemplate: MultiSelectComboBox.Dropdown.ListBox.ItemTemplate

<DataTemplate x:Key="MultiSelectComboBox.Dropdown.ListBox.ItemTemplate" DataType="models:LanguageItem">
    <Grid>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="Auto"/>
            <ColumnDefinition Width="*"/>
            <ColumnDefinition Width="30"/>
        </Grid.ColumnDefinitions>

        <Image Grid.Column="0" Style="{StaticResource MultiSelectComboBox.Image.Style}"/>
        <TextBlock Grid.Column="1" Text="{Binding Path=Name}" Style="{StaticResource MultiSelectComboBox.DefaultTextBlock.Style}"/>
        <TextBlock Grid.Column="2" Text="{Binding Path=SelectedOrder}" Margin="5,0"
                Foreground="{StaticResource MultiSelectComboBox.DropDown.ListBoxItem.SelectedOrder.Foreground}"
                VerticalAlignment="Center" HorizontalAlignment="Center">
            <TextBlock.Style>
                <Style TargetType="TextBlock">
                    <Style.Triggers>
                        <DataTrigger Binding="{Binding Path=SelectedOrder}" Value="-1">
                            <Setter Property="Visibility" Value="Hidden" />
                        </DataTrigger>
                    </Style.Triggers>
                </Style>
            </TextBlock.Style>
        </TextBlock>
    </Grid>
</DataTemplate>

DataTemplate: MultiSelectComboBox.SelectedItems.ItemTemplate

<DataTemplate x:Key="MultiSelectComboBox.SelectedItems.ItemTemplate" DataType="models:LanguageItem">
    <StackPanel Orientation="Horizontal" Margin="0,-4">
        <Image Style="{StaticResource MultiSelectComboBox.Image.Style}" Margin="2,0,4,-1"/>
        <TextBlock Text="{Binding Path=Name}" Style="{DynamicResource MultiSelectComboBox.DefaultTextBlock.Style}" Margin="2,0" />
    </StackPanel>
</DataTemplate>

Style: MultiSelectComboBox.Image.Style

<Style x:Key="MultiSelectComboBox.Image.Style" TargetType="Image">
    <Setter Property="Stretch" Value="Fill"/>
    <Setter Property="Source" Value="{Binding Path=Image}"/>
    <Setter Property="RenderOptions.BitmapScalingMode" Value="NearestNeighbor"/>
    <Setter Property="VerticalAlignment" Value="Center"/>
    <Setter Property="RenderOptions.EdgeMode" Value="Aliased"/>
    <Setter Property="Margin" Value="0,0,4,0"/>
    <Setter Property="Width" Value="{Binding Path=ImageSize.Width}"/>
    <Setter Property="Height" Value="{Binding Path=ImageSize.Height}"/>
</Style>

Style: MultiSelectComboBox.DefaultTextBlock.Style

<Style x:Key="MultiSelectComboBox.DefaultTextBlock.Style" TargetType="TextBlock">
    <Setter Property="FontFamily" Value="{StaticResource MultiSelectComboBox.Text.FontFamily}"/>
    <Setter Property="FontSize" Value="11"/>
    <Setter Property="HorizontalAlignment" Value="Stretch"/>
    <Setter Property="VerticalAlignment" Value="Center"/>
    <Setter Property="Control.VerticalContentAlignment" Value="Center"/>
    <Setter Property="TextWrapping" Value="NoWrap"/>
    <Setter Property="TextTrimming" Value="CharacterEllipsis"/>
    <Setter Property="Padding" Value="1"/>
    <Setter Property="Margin" Value="1"/>
    <Setter Property="Foreground" Value="{StaticResource MultiSelectComboBox.Text.Foreground}"/>
    <Setter Property="TextAlignment" Value="Left"/>
    <Style.Triggers>
        <DataTrigger Binding="{Binding IsEnabled, RelativeSource={RelativeSource AncestorType={x:Type ToggleButton}}}" Value="False">
            <Setter Property="Foreground" Value="{StaticResource MultiSelectComboBox.Text.Disabled.Foreground}" />
        </DataTrigger>
    </Style.Triggers>
</Style>

The following example defines the data context (i.e. models:LanguageItems) that the Sdl.MultiSelectComboBox binds to from the previous example.

LanguageItems : INotifyPropertyChanged

public class LanguageItems : INotifyPropertyChanged
{
    private List<LanguageItem> _items;   

    public LanguageItems()
    {
        SelectedItemsChangedCommand = new SelectedItemsChangedCommand(UpdateEventLog, UpdateSelectedItems);

        var group = new LanguageItemGroup(0, "All Items");
        Items = new List<LanguageItem>
        {
            new LanguageItem
            {
                Id = "en-US",
                Name= "English (United States)",
                Group = group
            },
            new LanguageItem
            {
                Id = "it-IT",
                Name= "Italian (Italy)",
                Group = group
            },
            new LanguageItem
            {
                Id = "de-DE",
                Name= "German (Germany)",
                Group = group
            }
        };
    }

    public ICommand SelectedItemsChangedCommand { get; }

    public List<LanguageItem> Items
    {
        get => _items ?? (_items = new List<LanguageItem>());
        set => _items = value;
    }

    public string EventLog { get; set; }

    private void UpdateEventLog(string action, string text)
    {
        EventLog += action + " => " + text + "\r\n";
        OnPropertyChanged(nameof(EventLog));
    }

    private void UpdateSelectedItemsCount(int count)
    {
        SelectedItemsCount = count;
        OnPropertyChanged(nameof(SelectedItemsCount));
    }

    private void UpdateSelectedItems(ICollection selected)
    {           
        foreach (var item in _items)
        {
            var selectedItemIndex = selected.Cast<LanguageItem>().ToList().IndexOf(item);
            item.SelectedOrder = selectedItemIndex > -1 ? selectedItemIndex + 1 : -1;
        }

        UpdateSelectedItemsCount(selected.Count);
    }

    public event PropertyChangedEventHandler PropertyChanged;

    protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }       
 }

LanguageItem : IItemEnabledAware, IItemGroupAware, INotifyPropertyChanged

public class LanguageItem : IItemEnabledAware, IItemGroupAware, INotifyPropertyChanged
{
    private string _id;
    private string _name;
    private bool _isEnabled;
    private int _selectedOrder;
    private IItemGroup _group;
    private BitmapImage _image;
    private Size _imageSize;

    public LanguageItem()
    {
        _isEnabled = true;
        _selectedOrder = -1;
    }

    /// <summary>
    /// Unique id in the collection
    /// </summary>
    public string Id
    {
        get => _id;
        set
        {
            if (_id != null && string.Compare(_id, value, StringComparison.InvariantCulture) == 0)
            {
                return;
            }

            _id = value;
            OnPropertyChanged(nameof(Id));
        }
    }

    /// <summary>
    /// The item name.
    ///
    /// The filter criteria is applied on this property when using the default filter service.
    /// </summary>
    public string Name
    {
        get => _name;
        set
        {
            if (_name != null && string.Compare(_name, value, StringComparison.InvariantCulture) == 0)
            {
                return;
            }

            _name = value;
            OnPropertyChanged(nameof(Name));
        }
    }

    /// <summary>
    /// Identifies whether the item is enabled or not.
    ///
    /// When the item is not enabled, then it will not be selectable from the dropdown list and removed
    /// from the selected items automatically.
    /// </summary>
    public bool IsEnabled
    {
        get => _isEnabled;
        set
        {
            if (_isEnabled.Equals(value))
            {
                return;
            }

            _isEnabled = value;
            OnPropertyChanged(nameof(IsEnabled));
        }
    }

    /// <summary>
    /// The order in which the items are added to the selected collection. 
    /// 
    /// This order is independent to the group and sort order of the items in the collection. This selected
    /// order is visible in each of the selected items from the dropdown list and visually represented by
    /// the order of the items in the Selected Items Panel.
    /// </summary>
    public int SelectedOrder
    {
        get => _selectedOrder;
        set
        {
            if (_selectedOrder.Equals(value))
            {
                return;
            }

            _selectedOrder = value;
            OnPropertyChanged(nameof(SelectedOrder));
        }
    }

    /// <summary>
    /// Identifies the name and order of the group header
    /// </summary>
    public IItemGroup Group
    {
        get => _group;
        set
        {
            if (_group != null && _group.Equals(value))
            {
                return;
            }

            _group = value;
            OnPropertyChanged(nameof(Group));
        }
    }

    /// <summary>
    /// The item Image.
    ///
    /// Use the ImageSize to identify the space required to display the image in the view.
    /// </summary>
    public BitmapImage Image
    {
        get => _image;
        set
        {
            _image = value;
            OnPropertyChanged(nameof(Image));
        }
    }

    /// <summary>
    /// The image size.
    ///
    /// Measures the width and height that is required to display the image.
    /// </summary>
    public Size ImageSize
    {
        get => _imageSize;
        set
        {
            if (_imageSize.Equals(value))
            {
                return;
            }

            _imageSize = value;
            OnPropertyChanged(nameof(ImageSize));
        }
    }

    public CultureInfo CultureInfo { get; set; }

    public override string ToString()
    {
        return Name;
    }

    public event PropertyChangedEventHandler PropertyChanged;

    protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

SelectedItemsChangedCommand : ICommand

public class SelectedItemsChangedCommand : ICommand
{
    private readonly Action<string, string> _updateEventLog;
    private readonly Action<ICollection> _updateSelectedItems;

    public SelectedItemsChangedCommand(Action<string, string> updateEventLog, Action<ICollection>)
    {
        _updateEventLog = updateEventLog;
        _updateSelectedItems = updateSelectedItems;
    }

    public bool CanExecute(object parameter)
    {
        return parameter is SelectedItemsChangedEventArgs && _updateEventLog != null;
    }

    public void Execute(object parameter)
    {
        if (parameter is SelectedItemsChangedEventArgs args)
        {
            _updateSelectedItems?.Invoke(args.Selected);

            var addedItems = GetAggregatedText(args.Added);
            var removedItems = GetAggregatedText(args.Removed);
            var selectedItems = GetAggregatedText(args.Selected);

            var report = "Added - " + args.Added?.Count + (!string.IsNullOrEmpty(addedItems) ? " (" + TrimToLength(addedItems, 100) + ") " : string.Empty)
                + ", Removed - " + args.Removed?.Count + (!string.IsNullOrEmpty(removedItems) ? " (" + TrimToLength(removedItems, 100) + ") " : string.Empty)
                + ", Selected - " + args.Selected?.Count + (!string.IsNullOrEmpty(selectedItems) ? " (" + TrimToLength(selectedItems, 100) + ") " : string.Empty);

            _updateEventLog?.Invoke("Selected Changed", report);
        }
    }

    public event EventHandler CanExecuteChanged;

    private string TrimToLength(string text, int length)
    {
        if (text?.Length > length)
        {
            text = text.Substring(0, length) + "...";
        }

        return text;
    }

    private static string GetAggregatedText(ICollection items)
    {
        var itemsText = string.Empty;
        return items?.Cast<LanguageItem>().Aggregate(itemsText, (current, item) => current + ((!string.IsNullOrEmpty(current) ? ", " : string.Empty) + item.Id));
    }
 }

LanguageItemGroup : IItemGroup

public class LanguageItemGroup : IItemGroup
{
    public int Order { get; set; }
    public string Name { get; }

    public LanguageItemGroup(int index, string name)
    {
        Order = index;
        Name = name;
    }

    public override string ToString()
    {
        return Name;
    }
}

Remarks

The Sdl.MultiSelectComboBox allows the user to select an item from a Dropdown Menu list and optionally apply a filter on the list by typing text in the text box of the Selected Items Panel. The SelectionMode and IsEditable properties specify how the Item Selection behaves, especially when the user is interacting with items from the Selected Items Panel, as follows:

Customizing the Style and template

You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a controls style and template, see Customizing the Appearance of an Existing Control by Creating a ControlTemplate and Styling controls. The default style, template, and resources that define the look of the control are included in the generic.xaml file.

This table shows the resources used by the Sdl.MultiSelectComboBox control.

The sample project includes an example of a customized version of control template style for the Sdl.MultiSelectComboBox control, where the item selection styles are modified and a popup control is displayed with the CultureInfo properties when hovering over the language items in the Selected Items Panel. Make reference to the following.

API

interface IFilterService

/// <summary>
/// The filter service that is used to apply a custom filter on the items that are displayed
/// from the collection.
/// </summary>
public interface IFilterService
{
    /// <summary>
    /// The filter criteria should be set before applying the Filter
    /// </summary>
    /// <param name="criteria">The filter criteria that is applied</param>
    void SetFilter(string criteria);

    /// <summary>
    /// Gets or sets a callback used to determine if an item is suitable for inclusion in the view.
    /// </summary>
    Predicate<object> Filter { get; set; }
}

interface IItemEnabledAware

/// <summary>
/// IEnabledAware - Identifies whether the item is enabled or not.
/// </summary>
public interface IItemEnabledAware
{
    /// <summary>
    /// Identifies whether the item is enabled or not.
    /// 
    /// When the item is not enabled, then it will not be selectable from the dropdown list and removed
    /// from the selected items automatically.
    /// </summary>
    bool IsEnabled { get; set; }
}

interface IItemGroup

/// <summary>
/// Identifies the name and order of the group header
/// </summary>
public interface IItemGroup
{
    /// <summary>
    /// The group name.
    /// </summary>
    string Name { get; }

    /// <summary>
    /// The display order of the group headers.
    /// </summary>
    int Order { get; set; }
}

interface IItemGroupAware

/// <summary>
/// IGroupAware - provides support for grouping the items
/// </summary>
public interface IItemGroupAware
{
    /// <summary>
    /// Used to identify the name and order of the group header
    /// </summary>
    IItemGroup Group { get; set; }
}

EventArgs

FilterTextChangedEventArgs : RoutedEventArgs

/// <summary>
/// Raised when the filter criteria has changed
/// </summary>
public class FilterTextChangedEventArgs : RoutedEventArgs
{    
    /// <summary>
    /// The filter critera applied on the collection of items
    /// </summary>
    public string Text { get; }

    /// <summary>
    /// The filtered list of items
    /// </summary>
    public ICollection Items { get; }        
}

SelectedItemsChangedEventArgs : RoutedEventArgs

/// <summary>
/// Raised when the selected items collection is modified
/// </summary>
public class SelectedItemsChangedEventArgs : RoutedEventArgs
{        
    /// <summary>
    /// Items added to the collection
    /// </summary>
    public ICollection Added { get; }

    /// <summary>
    /// Items removed from the collection
    /// </summary>
    public ICollection Removed { get; }

    /// <summary>
    /// The selected items
    /// </summary>
    public ICollection Selected { get; }        
}

Fields

Properties

Events

Event Behaviours

We have introduced the following event behaviors to accommodate binding events to a command. This way, the bound command is invoked like an event handler when the event is raised.