EnumItemsSourceBehavior

• Mar 13, 2021
• 5 minutes to read

The EnumItemsSourceBehavior class allows you to bind an enumeration to the ItemsSource property of any control.

• Getting Started with EnumItemsSourceBehavior
• Defining the EnumItemsSourceBehavior from the Visual Studio Designer
• Example

Getting Started with EnumItemsSourceBehavior

Assume that you need to represent the following UserRole enumeration in the ComboBoxEdit control.

C#

public enum UserRole {
    [Image("pack://application:,,,/Images/Admin.png"), Display(Name = "Admin", Description = "High level of access", Order = 1)]
    Administrator,
    [Image("pack://application:,,,/Images/Moderator.png"), Display(Name = "Moderator", Description = "Average level of access", Order = 2)]
    Moderator,
    [Image("pack://application:,,,/Images/User.png"), Display(Name = "User", Description = "Low level of access", Order = 3)]
    User
}

VB.NET

Public Enum UserRole
    <Image("pack://application:,,,/Images/Admin.png"), Display(Name := "Admin", Description := "High level of access", Order := 1)> _
    Administrator
    <Image("pack://application:,,,/Images/Moderator.png"), Display(Name := "Moderator", Description := "Average level of access", Order := 2)> _
    Moderator
    <Image("pack://application:,,,/Images/User.png"), Display(Name := "User", Description := "Low level of access", Order := 3)> _
    User
End Enum

There are several attributes defined for each enum member.

• Image is the DataAnnotation attribute that allows assigning an image to a corresponding member of the enumeration.
• Display is a standard Display attribute that provides a general-purpose attribute that allows you to specify localizable strings for types and members of entity partial classes.

To assign the UserRole enumeration to the LookUpEditBase.ItemsSource property of the ComboBoxEdit control, define the EnumItemsSourceBehavior as follows.

XAML

xmlns:dxe="http://schemas.devexpress.com/winfx/2008/xaml/editors"
xmlns:dxmvvm="http://schemas.devexpress.com/winfx/2008/xaml/mvvm"
...
<dxe:ComboBoxEdit>
    <dxmvvm:Interaction.Behaviors>
        <dxmvvm:EnumItemsSourceBehavior EnumType="{x:Type common:UserRole}"/>
    </dxmvvm:Interaction.Behaviors>
</dxe:ComboBoxEdit>

As a result, the combo-box will be automatically bound to the enum values.

If you wish, you can further customize the editor’s ItemTemplate, for instance:

XAML

<dxe:ComboBoxEdit Name="comboBoxEdit" IsTextEditable="False" ApplyItemTemplateToSelectedItem="True">
    <dxmvvm:Interaction.Behaviors>
        <dxmvvm:EnumItemsSourceBehavior EnumType="{x:Type common:UserRole}" SortMode="DisplayName"/>
    </dxmvvm:Interaction.Behaviors>
    <dxe:ComboBoxEdit.ItemTemplate>
        <DataTemplate>
            <Grid>
                <Grid.RowDefinitions>
                    <RowDefinition/>
                    <RowDefinition/>
                </Grid.RowDefinitions>
                <TextBlock Text="{Binding Name}"/>
                <TextBlock Text="{Binding Description}" Grid.Row="1" FontSize="9"/>
            </Grid>
        </DataTemplate>
    </dxe:ComboBoxEdit.ItemTemplate>
</dxe:ComboBoxEdit>

Here is the resulting combo-box:

Defining EnumItemsSourceBehavior from the Visual Studio Designer

SmartTag allows you to use the EnumItemsSourceBehavior from the Visual Studio designer. Below are step-by-step instructions that describe how to do this for the ComboBoxEdit control.

Open the ComboBoxEdit smart tag panel using the button at the top-right corner of the selected control.

Switch to the MVVM tab and add the EnumItemsSourceBehavior by clicking a corresponding item in the Add Behavior drop down menu. Then, specify the EnumItemsSourceBehavior’s properties as shown in the screenshot below.

Build and run the application to see the changes to the combo-box items at runtime.

Example

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-use-enumitemssourcebehavior-t196946.

MainViewModel.vb

Imports System.Collections.ObjectModel
Imports DevExpress.Mvvm.POCO
Imports EnumItemsSourceBehaviorExample.Common

Namespace EnumItemsSourceBehaviorExample.ViewModel
    Public Class MainViewModel
        Protected Sub New()
            Users = New ObservableCollection(Of User)() From {User.Create(0, "Jack", UserRole.Administrator), User.Create(1, "Ron", UserRole.User), User.Create(2, "John", UserRole.User), User.Create(3, "Antoni", UserRole.User), User.Create(4, "Paul", UserRole.Moderator)}
            SelectedRole = UserRole.User
        End Sub
        Public Shared Function Create() As MainViewModel
            Return ViewModelSource.Create(Function() New MainViewModel())
        End Function

        Public Overridable Property Users() As ObservableCollection(Of User)
        Public Overridable Property SelectedRole() As UserRole
    End Class
End Namespace

User.vb

Imports System
Imports System.Linq
Imports System.Collections.Generic
Imports DevExpress.Mvvm.POCO

Namespace EnumItemsSourceBehaviorExample.Common
    Public Class User
        Protected Sub New(ByVal name As String, ByVal iD As Integer, ByVal role As UserRole)
            Me.Name = name
            Me.ID = iD
            Me.Role = role
        End Sub
        Public Shared Function Create(ByVal id As Integer, ByVal name As String, ByVal role As UserRole) As User
            Return ViewModelSource.Create(Function() New User(name, id, role))
        End Function

        Public Property Name() As String
        Public Property ID() As Integer
        Public Property Role() As UserRole
    End Class
End Namespace

MainView.xaml

<UserControl  
    x:Class="EnumItemsSourceBehaviorExample.View.MainView" 
    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:dxe="http://schemas.devexpress.com/winfx/2008/xaml/editors"
    xmlns:dxg="http://schemas.devexpress.com/winfx/2008/xaml/grid" 
    xmlns:dxmvvm="http://schemas.devexpress.com/winfx/2008/xaml/mvvm"
    xmlns:vm="clr-namespace:EnumItemsSourceBehaviorExample.ViewModel"
    xmlns:common="clr-namespace:EnumItemsSourceBehaviorExample.Common"
    mc:Ignorable="d" d:DesignHeight="300" d:DesignWidth="300" 
    DataContext="{dxmvvm:ViewModelSource Type={x:Type vm:MainViewModel}}">
    <Grid Background="White">
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition/>
        </Grid.RowDefinitions> 
        <dxe:ComboBoxEdit Margin="10" EditValue="{Binding SelectedRole, UpdateSourceTrigger=PropertyChanged, Mode=TwoWay}" Name="comboBoxEdit" IsTextEditable="False" ApplyItemTemplateToSelectedItem="True">
            <dxmvvm:Interaction.Behaviors>
                <dxmvvm:EnumItemsSourceBehavior EnumType="{x:Type common:UserRole}" SortMode="DisplayName"/>
            </dxmvvm:Interaction.Behaviors>
            <dxe:ComboBoxEdit.ItemTemplate>
                <DataTemplate>
                    <Grid>
                        <Grid.RowDefinitions>
                            <RowDefinition/>
                            <RowDefinition/>
                        </Grid.RowDefinitions>
                        <TextBlock Text="{Binding Name}"/>
                        <TextBlock Text="{Binding Description}" Grid.Row="1" FontSize="9"/>
                    </Grid>
                </DataTemplate>
            </dxe:ComboBoxEdit.ItemTemplate>
        </dxe:ComboBoxEdit> 
        <Grid Grid.Row="1">
            <dxg:GridControl Margin="10" ItemsSource="{Binding Users}" AutoGenerateColumns="AddNew" FilterString="{Binding Path=SelectedRole, Converter={common:FilterStringConverter}, ConverterParameter=Role}">
                <dxg:GridControl.Columns>
                    <dxg:GridColumn FieldName="Name"/>
                    <dxg:GridColumn FieldName="ID"/>
                    <dxg:GridColumn FieldName="Role">
                        <dxg:GridColumn.CellTemplate>
                            <DataTemplate>
                                <dxe:ComboBoxEdit Name="PART_Editor" IsTextEditable="False" ApplyItemTemplateToSelectedItem="True">
                                    <dxmvvm:Interaction.Behaviors>
                                        <dxmvvm:EnumItemsSourceBehavior EnumType="{x:Type common:UserRole}" />
                                    </dxmvvm:Interaction.Behaviors>
                                </dxe:ComboBoxEdit>
                            </DataTemplate>
                        </dxg:GridColumn.CellTemplate>
                    </dxg:GridColumn>
                </dxg:GridControl.Columns>
                <dxg:GridControl.View>
                    <dxg:TableView AllowEditing="False" ShowFilterPanelMode="Never" ShowColumnHeaders="False" ShowGroupPanel="False" VerticalScrollbarVisibility="Auto" NavigationStyle="Row" FadeSelectionOnLostFocus="False"/>
                </dxg:GridControl.View>
            </dxg:GridControl>
        </Grid>
    </Grid>
</UserControl>

UserRole.vb

Imports DevExpress.Mvvm.DataAnnotations
Imports System.ComponentModel.DataAnnotations

Namespace EnumItemsSourceBehaviorExample.Common
    Public Enum UserRole
        <Image("pack://application:,,,/Images/Admin.png"), Display(Name := "Admin", Description := "High level of access")> _
        Administrator
        <Image("pack://application:,,,/Images/Moderator.png"), Display(Name := "Moderator", Description := "Average level of access")> _
        Moderator
        <Image("pack://application:,,,/Images/User.png"), Display(Name := "User", Description := "Low level of access")> _
        User
    End Enum
End Namespace

MainViewModel.cs

using System.Collections.ObjectModel;
using DevExpress.Mvvm.POCO;
using EnumItemsSourceBehaviorExample.Common;

namespace EnumItemsSourceBehaviorExample.ViewModel {
    public class MainViewModel {
        protected MainViewModel() {
            Users = new ObservableCollection<User>() {
                User.Create(0, "Jack", UserRole.Administrator),
                User.Create(1, "Ron", UserRole.User),
                User.Create(2, "John", UserRole.User),
                User.Create(3, "Antoni", UserRole.User),
                User.Create(4, "Paul", UserRole.Moderator),
            };
            SelectedRole = UserRole.User;
        }
        public static MainViewModel Create() {
            return ViewModelSource.Create(() => new MainViewModel());
        }

        public virtual ObservableCollection<User> Users { get; set; }
        public virtual UserRole SelectedRole { get; set; }
    }
}

User.cs

using System;
using System.Linq;
using System.Collections.Generic;
using DevExpress.Mvvm.POCO;

namespace EnumItemsSourceBehaviorExample.Common {
    public class User {
        protected User(string name, int iD, UserRole role) {
            Name = name;
            ID = iD;
            Role = role;
        }
        public static User Create(int id, string name, UserRole role) {
            return ViewModelSource.Create(() => new User(name, id, role));
        }

        public string Name { get; set; }
        public int ID { get; set; }
        public UserRole Role { get; set; }
    }
}

UserRole.cs

using DevExpress.Mvvm.DataAnnotations;
using System.ComponentModel.DataAnnotations;

namespace EnumItemsSourceBehaviorExample.Common {
    public enum UserRole {
        [Image("pack://application:,,,/Images/Admin.png"), Display(Name = "Admin", Description = "High level of access")]
        Administrator,
        [Image("pack://application:,,,/Images/Moderator.png"), Display(Name = "Moderator", Description = "Average level of access")]
        Moderator,
        [Image("pack://application:,,,/Images/User.png"), Display(Name = "User", Description = "Low level of access")]
        User
    }
}