How to: Set Images and Captions for Enumeration Values

• Dec 22, 2023
• 3 minutes to read

This topic describes how to associate custom SVG or raster images with enumeration values and specify captions for these values.

For information on how to add and override UI images, refer to the Add and Replace Icons topic.

Enumeration as a Property Type

Use the ImageNameAttribute to set an image that represents an enumeration value in UI. Apply this attribute to the enumeration values and specify the images:

C#

public enum SampleEnum {    
    [ImageName("BO_Person")]
    First,  
    [ImageName("BO_Position")]
    Second, 
    [ImageName("BO_Employee")]
    Third 
}

VB.NET

Public Enum SampleEnum
    <ImageName("BO_Person")> _
    First
    <ImageName("BO_Position")> _
    Second
    <ImageName("BO_Employee")> _
    Third
End Enum

ASP.NET Core Blazor

Windows Forms

Note

Use the same image format for all items in one collection: either SVG or raster. Otherwise, an enumeration property editor may not show certain images. If you observe such behavior in your application, make sure image files for all entries have the same format and check the application’s log file for any additional diagnostic message the enumeration property editor may have recorded.

Use the XafDisplayNameAttribute to set a caption that represents an enumeration value in UI. Apply this attribute to the enumeration values and specify the captions:

C#

public enum SampleEnum {    
    [XafDisplayName("John")]
    First,  
    [XafDisplayName("Sam")]
    Second, 
    [XafDisplayName("Bob")]
    Third 
}

VB.NET

Public Enum SampleEnum
    <XafDisplayName("John")> _
    First
    <XafDisplayName("Sam")> _
    Second
    <XafDisplayName("Bob")> _
    Third
End Enum

ASP.NET Core Blazor

Windows Forms

Enumeration as Option Source for a Single Choice Action

Enumeration values can represent items in a Single Choice Action’s drop-down menu. The following code demonstrates how to populate the ChoiceActionBase.Items collection with enumeration values and associate images with these items:

C#

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Actions;
using DevExpress.ExpressApp.Utils;
using DevExpress.Persistent.Base;
using YourSolutionName.Module.BusinessObjects;

namespace YourSolutionName.Module.Controllers {
    public partial class TaskActionsController : ViewController {
        public TaskActionsController() {
            var SetPriorityAction = new SingleChoiceAction(this, "myAction1", PredefinedCategory.Edit);
            SetPriorityAction.ImageName = "Task";
            SetPriorityAction.ItemType = SingleChoiceActionItemType.ItemIsOperation;
            foreach (SampleEnum current in Enum.GetValues(typeof(SampleEnum))) {
                EnumDescriptor ed = new EnumDescriptor(typeof(SampleEnum));
                ChoiceActionItem item = new ChoiceActionItem(ed.GetCaption(current), current);
                item.ImageName = ImageLoader.Instance.GetEnumValueImageName(current);
                SetPriorityAction.Items.Add(item);
            }
        }
    }
}

VB.NET

Imports DevExpress.ExpressApp.Utils
'...
Public Class SelectViewController
  Inherits DevExpress.ExpressApp.ViewController
    Public Sub New()
        MyBase.New()
        InitializeComponent()
        SetPriorityAction.Items.Clear()
        For Each current As Priority In System.Enum.GetValues(GetType(Priority))
            ' Create an EnumDescriptor to get the localized enumeration value
            Dim ed As EnumDescriptor = New EnumDescriptor(GetType(Priority))
            Dim item As ChoiceActionItem = _
            New ChoiceActionItem(ed.GetCaption(current), current)
            ' Set the image name         
            item.ImageName = ImageLoader.Instance.GetEnumValueImageName(current)
            SetPriorityAction.Items.Add(item)
      Next current
    End Sub
End Class

The following image displays the SetPriorityAction:

ASP.NET Core Blazor

Windows Forms