How to: Set Images and Captions for Enumeration Values

• Jan 21, 2021
• 3 minutes to read

This topic describes how to associate custom SVG or raster images and display captions with enumeration values. Refer to the Add and Override Images help topic for information on how to add and override UI images.

Enumeration as a Property Type

You can use the ImageNameAttribute to set the image that represents an enumeration value in a UI. Apply this attribute to the required enumeration values and specify the images to be used:

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

Note

• Use either SVG or raster images for all items in one collection. When using SVG and raster images simultaneously, an enumeration property editor can fail to show certain images. In this case, make sure image files for all entries have the same format and check the application’s Log File for an additional diagnostic message the enumeration property editor recorded.
• Blazor applications do not show images for enumeration values.

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

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

Enumeration as Options Source for a SingleChoiceAction

Note

You can see the code demonstrated here in XAF‘s Main Demo.

Enumeration values can represent a Single Choice Action’s items. The following code demonstrates how to populate the ChoiceActionBase.Items collection with enumeration values, and set images for these items:

C#

using DevExpress.ExpressApp.Utils;
//...
public partial class TaskActionsController : ViewController {
    public SetPriorityController() {
        InitializeComponent();
        SetPriorityAction.Items.Clear();   
        foreach(Priority current in Enum.GetValues(typeof(Priority))) {
            // Create an EnumDescriptor to get the localized enumeration value
            EnumDescriptor ed = new EnumDescriptor(typeof(Priority));
            ChoiceActionItem item = new ChoiceActionItem(ed.GetCaption(current), current);
            // Set the image name
            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 shows the SetPriorityAction in the Windows Forms application: