Click here to Skip to main content
15,867,330 members
Articles / Programming Languages / C#
Article

Data Binding an Enum with Descriptions

Rate me:
Please Sign up or sign in to vote.
4.46/5 (67 votes)
30 Dec 2007CPOL4 min read 303.8K   2.6K   159   61
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:

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

You can bind it to a ComboBox like this:

C#
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.

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

   /// <summary>
   /// Gets the description stored in this attribute.
   /// </summary>
   /// <value>The description stored in the attribute.</value>
   public string Description
   {
      get
      {
         return this.description;
      }
   }

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

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

C#
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.

C#
/// <summary>
/// Provides a static utility object of methods and properties to interact
/// with enumerated types.
/// </summary>
public static class EnumHelper
{
   /// <summary>
   /// Gets the <see cref="DescriptionAttribute" /> of an <see cref="Enum" />
   /// type value.
   /// </summary>
   /// <param name="value">The <see cref="Enum" /> type value.</param>
   /// <returns>A string containing the text of the
   /// <see cref="DescriptionAttribute"/>.</returns>
   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;
   }

   /// <summary>
   /// Converts the <see cref="Enum" /> type to an <see cref="IList" /> 
   /// compatible object.
   /// </summary>
   /// <param name="type">The <see cref="Enum"/> type.</param>
   /// <returns>An <see cref="IList"/> containing the enumerated
   /// type value and description.</returns>
   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:

C#
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:

C#
/// <summary>
/// Provides a static utility object of methods and properties to interact
/// with enumerated types.
/// </summary>
public static class EnumHelper
{
   /// <summary>
   /// Gets the <see cref="DescriptionAttribute" /> of an <see cref="Enum" /> 
   /// type value.
   /// </summary>
   /// <param name="value">The <see cref="Enum" /> type value.</param>
   /// <returns>A string containing the text of the
   /// <see cref="DescriptionAttribute"/>.</returns>
   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;
   }

   /// <summary>
   /// Converts the <see cref="Enum" /> type to an <see cref="IList" /> 
   /// compatible object.
   /// </summary>
   /// <param name="type">The <see cref="Enum"/> type.</param>
   /// <returns>An <see cref="IList"/> containing the enumerated
   /// type value and description.</returns>
   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:

C#
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:

C#
// .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:

C#
// .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)


Written By
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.

Comments and Discussions

 
GeneralI like it!! Pin
stixoffire12-Jun-15 4:52
stixoffire12-Jun-15 4:52 
GeneralVery nice code Pin
Tim Callaghan17-Nov-09 19:01
Tim Callaghan17-Nov-09 19:01 
GeneralVB.NET Translation [modified] Pin
kelvin199728-Aug-09 23:11
kelvin199728-Aug-09 23:11 
GeneralA little different approach same result Pin
Rob241219-Jul-09 9:26
Rob241219-Jul-09 9:26 
GeneralFor those stuck with .NET 1.1 ... Pin
ketchupy17-May-09 12:32
ketchupy17-May-09 12:32 
GeneralElegant Pin
Ri Qen-Sin30-Dec-07 4:40
Ri Qen-Sin30-Dec-07 4:40 
GeneralRe: Elegant Pin
Scott Dorman30-Dec-07 5:37
professionalScott Dorman30-Dec-07 5:37 
QuestionSet the DataSource before Display/ValueMember Pin
Craig Darin Cote3-Nov-07 20:05
Craig Darin Cote3-Nov-07 20:05 
AnswerRe: Set the DataSource before Display/ValueMember Pin
Scott Dorman4-Nov-07 1:38
professionalScott Dorman4-Nov-07 1:38 
GeneralMinor simplification Pin
rendle2-Oct-07 2:01
rendle2-Oct-07 2:01 
GeneralRe: Minor simplification Pin
Scott Dorman2-Oct-07 2:51
professionalScott Dorman2-Oct-07 2:51 
GeneralCool idea indeed Pin
rochana_bg20-Sep-07 13:28
rochana_bg20-Sep-07 13:28 
GeneralRe: Cool idea indeed Pin
Scott Dorman20-Sep-07 18:17
professionalScott Dorman20-Sep-07 18:17 
GeneralCool Idea Pin
merlin9817-Sep-07 4:37
professionalmerlin9817-Sep-07 4:37 
GeneralRe: Cool Idea Pin
Scott Dorman23-Sep-07 8:53
professionalScott Dorman23-Sep-07 8:53 
QuestionLocalization? Pin
Urs Enzler6-Sep-07 23:14
Urs Enzler6-Sep-07 23:14 
AnswerRe: Localization? Pin
wout de zeeuw6-Sep-07 23:29
wout de zeeuw6-Sep-07 23:29 
GeneralRe: Localization? Pin
Urs Enzler6-Sep-07 23:34
Urs Enzler6-Sep-07 23:34 
Nothing, I'm already localising enum values with resource files and a helper class that takes the enum value and spits out a key to the resource file.

The problem is always that the last thing most developers think about is localisation.
Maybe here in Switzerland it's a bit different because we have 4 official languages in our small country Wink | ;)

-^-^-^-^-^-
no risk no funk ................... please vote ------>

GeneralRe: Localization? Pin
Scott Dorman7-Sep-07 2:49
professionalScott Dorman7-Sep-07 2:49 
AnswerRe: Localization? Pin
Scott Dorman7-Sep-07 2:46
professionalScott Dorman7-Sep-07 2:46 
GeneralRe: Localization? Pin
Urs Enzler7-Sep-07 2:53
Urs Enzler7-Sep-07 2:53 
GeneralRe: Localization? Pin
Scott Dorman7-Sep-07 3:12
professionalScott Dorman7-Sep-07 3:12 
QuestionKey integer value? Pin
George Fitch6-Sep-07 0:05
George Fitch6-Sep-07 0:05 
AnswerRe: Key integer value? Pin
Scott Dorman6-Sep-07 1:55
professionalScott Dorman6-Sep-07 1:55 
GeneralRe: Key integer value? [modified] Pin
George Fitch6-Sep-07 12:18
George Fitch6-Sep-07 12:18 

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

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