Click here to Skip to main content
Click here to Skip to main content

Data Binding an Enum with Descriptions

, 30 Dec 2007 CPOL
Rate this:
Please Sign up or sign in to vote.
A simple solution for binding an enum to a UI control using data binding.

Introduction

Every once in a while I need to bind an enumerated type to a Windows Forms control, usually a ComboBox. There are lots of articles here on The CodeProject that present various ways to do this, each with their own pros and cons. However, they are generally more complicated than necessary, and in some cases, require a lot of work on either the developer implementing the enum, the developer using it, or both.

The Simple Way

The simplest is to use the Enum.GetValues() method, setting its result to the DataSource property of the ComboBox. If you have the following enum:

public enum SimpleEnum
{
    Today,
    Last7
    Last14,
    Last30,
    All
}

You can bind it to a ComboBox like this:

ComboBox combo = new ComboBox();
combo.DataSource = Enum.GetValues(typeof(SimpleEnum));

While this does work, there are a couple of problems:

  1. There is no support for localization.
  2. There is no support for more readable descriptions.

Binding with Descriptions

Fortunately, there is a relatively easy way to meet these requirements using a little bit of Reflection and decorating the enum values with an attribute. You don't need a lot of generic classes, custom classes, or custom type descriptors...just two static methods that are both less than 10 lines of code.

The first step is to add a description attribute to your enum. For simplicity, you can use the System.ComponentModel.DescriptionAttribute class, but I would recommend deriving your own EnumDescriptionAttribute.

/// <span class="code-SummaryComment"><summary></span>
/// Provides a description for an enumerated type.
/// <span class="code-SummaryComment"></summary></span>
[AttributeUsage(AttributeTargets.Enum | AttributeTargets.Field, 
 AllowMultiple = false)]
public sealed class EnumDescriptionAttribute :  Attribute
{
   private string description;

   /// <span class="code-SummaryComment"><summary></span>
   /// Gets the description stored in this attribute.
   /// <span class="code-SummaryComment"></summary></span>
   /// <span class="code-SummaryComment"><value>The description stored in the attribute.</value></span>
   public string Description
   {
      get
      {
         return this.description;
      }
   }

   /// <span class="code-SummaryComment"><summary></span>
   /// Initializes a new instance of the
   /// <span class="code-SummaryComment"><see cref="EnumDescriptionAttribute"/> class.</span>
   /// <span class="code-SummaryComment"></summary></span>
   /// <span class="code-SummaryComment"><param name="description">The description to store in this attribute.</span>
   /// <span class="code-SummaryComment"></param></span>
   public EnumDescriptionAttribute(string description)
       : base()
   {
       this.description = description;
   }
}

Now that we have our description attribute, we need to decorate the enum with it:

public enum SimpleEnum
{
   [EnumDescription("Today")]
   Today,

   [EnumDescription("Last 7 days")]
   Last7,

   [EnumDescription("Last 14 days")]
   Last14,

   [EnumDescription("Last 30 days")]
   Last30,

   [EnumDescription("All")]
   All
}

Using a custom attribute allows you to keep the human readable description in the code where the enum is defined. It also allows you to retrieve localized versions of the description. In order to do that, you simply need to change the way the attribute works to lookup the appropriate string in the string resources.

The next part is what actually does all of the work. As I mentioned, both of these functions are less than 10 lines of code. The easiest way to work with these functions is to create a static (or sealed, if you aren't using .NET 2.0 or later) class that holds these two static functions.

/// <span class="code-SummaryComment"><summary></span>
/// Provides a static utility object of methods and properties to interact
/// with enumerated types.
/// <span class="code-SummaryComment"></summary></span>
public static class EnumHelper
{
   /// <span class="code-SummaryComment"><summary></span>
   /// Gets the <span class="code-SummaryComment"><see cref="DescriptionAttribute" /> of an <see cref="Enum" /></span>
   /// type value.
   /// <span class="code-SummaryComment"></summary></span>
   /// <span class="code-SummaryComment"><param name="value">The <see cref="Enum" /> type value.</param></span>
   /// <span class="code-SummaryComment"><returns>A string containing the text of the</span>
   /// <span class="code-SummaryComment"><see cref="DescriptionAttribute"/>.</returns></span>
   public static string GetDescription(Enum value)
   {
      if (value == null)
      {
         throw new ArgumentNullException("value");
      }

      string description = value.ToString();
      FieldInfo fieldInfo = value.GetType().GetField(description);
      EnumDescriptionAttribute[] attributes =
         (EnumDescriptionAttribute[])
       fieldInfo.GetCustomAttributes(typeof(EnumDescriptionAttribute), false);

      if (attributes != null && attributes.Length > 0)
      {
         description = attributes[0].Description;
      }
      return description;
   }

   /// <span class="code-SummaryComment"><summary></span>
   /// Converts the <span class="code-SummaryComment"><see cref="Enum" /> type to an <see cref="IList" /> </span>
   /// compatible object.
   /// <span class="code-SummaryComment"></summary></span>
   /// <span class="code-SummaryComment"><param name="type">The <see cref="Enum"/> type.</param></span>
   /// <span class="code-SummaryComment"><returns>An <see cref="IList"/> containing the enumerated</span>
   /// type value and description.<span class="code-SummaryComment"></returns></span>
   public static IList ToList(Type type)
   {
      if (type == null)
      {
         throw new ArgumentNullException("type");
      }

      ArrayList list = new ArrayList();
      Array enumValues = Enum.GetValues(type);

      foreach (Enum value in enumValues)
      {
         list.Add(new KeyValuePair<Enum, string>(value, GetDescription(value)));
      }

      return list;
   }
}

As you can see, the GetDescription method uses a little bit of Reflection to retrieve the EnumDescription attribute on the specified enum value. If it doesn't find the attribute, it simply uses the value name. The ToList method returns an IList of KeyValuePair<Enum, string> instances that hold the enum value (the key) and the description (the value). If you aren't using .NET 2.0 or later, you will need to use DictionaryEntry instead of KeyValuePair<TKey, TValue>.

In order to bind the ComboBox, you now need to do the following:

ComboBox combo = new ComboBox();
combo.DataSource = EnumHelper.ToList(typeof(SimpleEnum));
combo.DisplayMember = "Value";
combo.ValueMember = "Key";

.NET 3.5 Extension Methods

As was pointed out in the article comments[^], it is very easy to convert the methods in EnumHelper to be extension methods in .NET 3.5. In order to do this, you will need to have either the ..NET Framework 3.5 Beta 2[^] or Visual Studio 2008[^] installed.

To make the change to extension methods, you add the this keyword to the first parameter in ToList and GetDescription. The update class should look like:

/// <span class="code-SummaryComment"><summary></span>
/// Provides a static utility object of methods and properties to interact
/// with enumerated types.
/// <span class="code-SummaryComment"></summary></span>
public static class EnumHelper
{
   /// <span class="code-SummaryComment"><summary></span>
   /// Gets the <span class="code-SummaryComment"><see cref="DescriptionAttribute" /> of an <see cref="Enum" /> </span>
   /// type value.
   /// <span class="code-SummaryComment"></summary></span>
   /// <span class="code-SummaryComment"><param name="value">The <see cref="Enum" /> type value.</param></span>
   /// <span class="code-SummaryComment"><returns>A string containing the text of the</span>
   /// <span class="code-SummaryComment"><see cref="DescriptionAttribute"/>.</returns></span>
   public static string GetDescription(this Enum value)
   {
      if (value == null)
      {
         throw new ArgumentNullException("value");
      }

      string description = value.ToString();
      FieldInfo fieldInfo = value.GetType().GetField(description);
      EnumDescriptionAttribute[] attributes =
         (EnumDescriptionAttribute[])
       fieldInfo.GetCustomAttributes(typeof(EnumDescriptionAttribute), false);

      if (attributes != null && attributes.Length > 0)
      {
         description = attributes[0].Description;
      }
      return description;
   }

   /// <span class="code-SummaryComment"><summary></span>
   /// Converts the <span class="code-SummaryComment"><see cref="Enum" /> type to an <see cref="IList" /> </span>
   /// compatible object.
   /// <span class="code-SummaryComment"></summary></span>
   /// <span class="code-SummaryComment"><param name="type">The <see cref="Enum"/> type.</param></span>
   /// <span class="code-SummaryComment"><returns>An <see cref="IList"/> containing the enumerated</span>
   /// type value and description.<span class="code-SummaryComment"></returns></span>
   public static IList ToList(this Type type)
   {
      if (type == null)
      {
         throw new ArgumentNullException("type");
      }

      ArrayList list = new ArrayList();
      Array enumValues = Enum.GetValues(type);

      foreach (Enum value in enumValues)
      {
         list.Add(new KeyValuePair<Enum, string>(value, GetDescription(value)));
      }

      return list;
   }
}

In order to bind the ComboBox, you simply change the way you set the DataSource property to do the following:

combo.DataSource = typeof(SimpleEnum).ToList();

Advanced Uses

To support additional advanced cases where the underlying numeric value is needed, you can use a generic version of the ToList method. This method requires that the type argument be explicitly specified, like this:

// .NET 2.0, 3.0
combo.DataSource = EnumHelper.ToList<int>(typeof(SimpleEnum));

// .NET 3.5
combo.DataSource = typeof(SimpleEnum).ToList<int>();

In addition, by using the ToExtendedList<T> method, you can retrieve an IList of KeyValueTriplet<Enum, T, string> instances that hold the enum value (the key), the numeric value, and the description (the value). This allows the most flexibility in deciding what data type will be bound to the ValueMember property. You can use the ToExtendedList<T> in the following ways:

// .NET 2.0, 3.0
combo.DataSource = EnumHelper.ToExtendedList<int>(typeof(SimpleEnum));
combo.DisplayMember = "Value";
combo.ValueMember = "Key";

// OR

combo.DataSource = EnumHelper.ToExtendedList<int>(typeof(SimpleEnum));
combo.DisplayMember = "Value";
combo.ValueMember = "NumericKey";

// .NET 3.5
combo.DataSource = typeof(SimpleEnum).ToExtendedList<int>();
combo.DisplayMember = "Value";
combo.ValueMember = "Key";

// OR

combo.DataSource = typeof(SimpleEnum).ToExtendedList<int>();
combo.DisplayMember = "Value";
combo.ValueMember = "NumericKey";

Conclusion

You now have a ComboBox whose values are your enum type values and whose display are the string specified in the EnumDescription attribute. This works with any control that supports data binding, including the ToolStripComboBox, although you will need to cast the ToolStripComboBox.Control property to a ComboBox to get to the DataSource property. (In that case, you will also want to perform the same cast when you are referencing the selected value to work with it as your enum type.)

Revision History

6-September-2007:

  • Added additional error handling to ToList.
  • Created a generic ToList method that allows the numeric value of the enum to be used as the key.
  • Added a KeyValueTriplet struct that allows the enum value, numeric value, and description to be returned.
  • Added a generic ToExtendedList method that allows the enum value, numeric value, and description to be returned using a KeyValueTriplet.
  • Cleaned up the project structure to remove duplicate files.

26-August-2007:

  • Added information about using the EnumHelper methods as extension methods in .NET 3.5.
  • Added a new download for .NET 3.5
  • Added a tester application to the download for .NET 2.0

12-August-2007:

  • Original article.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Scott Dorman
Software Developer (Senior)
United States United States
I am a Microsoft C# MVP, author, speaker, blogger, and software developer. I also created the WP Requests and WinStore Requests sites for Windows Phone and Windows Sotre apps as well as several open source projects.
 
I've been involved with computers in one way or another for as long as I can remember, but started professionally in 1993. Although my primary focus right now is commercial software applications, I prefer building infrastructure components, reusable shared libraries and helping companies define, develop and automate process and code standards and guidelines.
Follow on   Twitter   LinkedIn

Comments and Discussions

 
GeneralVery nice code PinmemberTim Callaghan17-Nov-09 20:01 
This is exactly what I needed and, more importantly, is a very clean and elegant way of doing it. You got my 5. Thanks Smile | :)
GeneralVB.NET Translation [modified] Pinmemberkelvin199729-Aug-09 0:11 
GeneralA little different approach same result PinmemberRob241219-Jul-09 10:26 
GeneralFor those stuck with .NET 1.1 ... Pinmemberketchupy17-May-09 13:32 
GeneralElegant PinmemberRi Qen-Sin30-Dec-07 5:40 
GeneralRe: Elegant PinmemberScott Dorman30-Dec-07 6:37 
QuestionSet the DataSource before Display/ValueMember PinmemberCraig Darin Cote3-Nov-07 21:05 
AnswerRe: Set the DataSource before Display/ValueMember PinmemberScott Dorman4-Nov-07 2:38 
GeneralMinor simplification Pinmemberrendle2-Oct-07 3:01 
GeneralRe: Minor simplification PinmemberScott Dorman2-Oct-07 3:51 
GeneralCool idea indeed Pinmemberrochana_bg20-Sep-07 14:28 
GeneralRe: Cool idea indeed PinmemberScott Dorman20-Sep-07 19:17 
GeneralCool Idea Pinmembermerlin9817-Sep-07 5:37 
GeneralRe: Cool Idea PinmemberScott Dorman23-Sep-07 9:53 
QuestionLocalization? PinmemberUrs Enzler7-Sep-07 0:14 
AnswerRe: Localization? Pinmemberwout de zeeuw7-Sep-07 0:29 
GeneralRe: Localization? PinmemberUrs Enzler7-Sep-07 0:34 
GeneralRe: Localization? PinmemberScott Dorman7-Sep-07 3:49 
AnswerRe: Localization? PinmemberScott Dorman7-Sep-07 3:46 
GeneralRe: Localization? PinmemberUrs Enzler7-Sep-07 3:53 
GeneralRe: Localization? PinmemberScott Dorman7-Sep-07 4:12 
QuestionKey integer value? PinmemberGeorge Fitch6-Sep-07 1:05 
AnswerRe: Key integer value? PinmemberScott Dorman6-Sep-07 2:55 
GeneralRe: Key integer value? [modified] PinmemberGeorge Fitch6-Sep-07 13:18 
GeneralRe: Key integer value? PinmemberScott Dorman6-Sep-07 15:07 
GeneralRe: Key integer value? PinmemberGeorge Fitch6-Sep-07 15:59 
GeneralRe: Key integer value? PinmemberScott Dorman6-Sep-07 16:59 
GeneralRe: Key integer value? PinmemberScott Dorman6-Sep-07 17:32 
QuestionFormatting PinmemberBen Daniel26-Aug-07 13:54 
AnswerRe: Formatting PinmemberScott Dorman26-Aug-07 14:43 
GeneralRe: Formatting PinmemberBen Daniel26-Aug-07 15:22 
GeneralRe: Formatting PinmemberJupiterP526-Aug-07 15:34 
GeneralRe: Formatting PinmemberScott Dorman26-Aug-07 15:48 
GeneralRe: Formatting PinmemberScott Dorman26-Aug-07 15:48 
GeneralRe: Formatting PinmemberBen Daniel26-Aug-07 18:10 
GeneralRe: Formatting PinmemberScott Dorman26-Aug-07 18:32 
General.Net 3.5 Extension Goodness Pinmemberbmiller25-Aug-07 8:26 
GeneralRe: .Net 3.5 Extension Goodness PinmemberScott Dorman25-Aug-07 11:16 
GeneralRe: .Net 3.5 Extension Goodness PinmemberScott Dorman26-Aug-07 7:08 
GeneralBrilliant PinmemberUlliDK16-Aug-07 1:02 
GeneralRe: Brilliant PinmemberScott Dorman16-Aug-07 4:57 
GeneralI have a problem PinmemberBaconbutty13-Aug-07 6:01 
GeneralRe: I have a problem PinmemberScott Dorman13-Aug-07 6:46 
GeneralRe: I have a problem PinmemberBaconbutty14-Aug-07 0:04 
GeneralRe: I have a problem PinmemberScott Dorman15-Aug-07 5:58 
GeneralVery Nice, simple. PinmemberMike DiRenzo13-Aug-07 4:49 
GeneralRe: Very Nice, simple. PinmemberScott Dorman13-Aug-07 5:30 
GeneralNice one. PinmemberPete O'Hanlon12-Aug-07 22:55 
GeneralRe: Nice one. PinmemberScott Dorman13-Aug-07 4:43 
GeneralThere is DescriptionAttribute PinmemberMuhahahahahahahahahahahaha12-Aug-07 20:59 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web03 | 2.8.141220.1 | Last Updated 30 Dec 2007
Article Copyright 2007 by Scott Dorman
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid