diff --git a/docs/maui/converters/enum-description-converter.md b/docs/maui/converters/enum-description-converter.md new file mode 100644 index 00000000..70f23076 --- /dev/null +++ b/docs/maui/converters/enum-description-converter.md @@ -0,0 +1,147 @@ +--- +title: EnumDescriptionConverter - .NET MAUI Community Toolkit +author: BillyMartin1964 +description: "Converts an Enum value to its display string using DisplayAttribute or DescriptionAttribute." +ms.date: 06/10/2024 +--- + +# EnumDescriptionConverter + + +The `EnumDescriptionConverter` is a one way converter that returns a `string` representing the display name or description of an `Enum` value. It uses the [`DisplayAttribute`](https://learn.microsoft.com/dotnet/api/system.componentmodel.dataannotations.displayattribute) or [`DescriptionAttribute`](https://learn.microsoft.com/dotnet/api/system.componentmodel.descriptionattribute) if present, otherwise returns the enum name. +The `EnumDescriptionConverter` is a one way converter that returns a `string` representing the display name or description of an `Enum` value. It uses the [`DisplayAttribute`](/dotnet/api/system.componentmodel.dataannotations.displayattribute) or [`DescriptionAttribute`](/dotnet/api/system.componentmodel.descriptionattribute) if present, otherwise returns the enum name. + +The `Convert` method returns the value of the `DisplayAttribute.Name` if defined, otherwise the value of the `DescriptionAttribute.Description` if defined, otherwise the enum name as a string. + +The `ConvertBack` method is not supported. + +[!INCLUDE [common converter properties](../includes/communitytoolkit-converter.md)] + +## Syntax + +### XAML + +#### Including the XAML namespace + +[!INCLUDE [XAML usage guidance](../includes/xaml-usage.md)] + +#### Using the EnumDescriptionConverter + +The `EnumDescriptionConverter` can be used as follows in XAML: + +```xaml + + + + + + + + + +``` + +### C# + +The `EnumDescriptionConverter` can be used as follows in C#: + +```csharp +class EnumDescriptionConverterPage : ContentPage +{ + public EnumDescriptionConverterPage() + { + var label = new Label(); + label.SetBinding( + Label.TextProperty, + new Binding( + static (ViewModel vm) => vm.MyEnumValue, + converter: new EnumDescriptionConverter())); + Content = label; + } +} +``` + +### C# Markup + +Our [`CommunityToolkit.Maui.Markup`](../markup/markup.md) package provides a concise way to use this converter in C#. + +```csharp +using CommunityToolkit.Maui.Markup; + +class EnumDescriptionConverterPage : ContentPage +{ + public EnumDescriptionConverterPage() + { + Content = new Label() + .Bind( + Label.TextProperty, + static (ViewModel vm) => vm.MyEnumValue, + converter: new EnumDescriptionConverter()); + } +} +``` + +## Examples + + +Suppose you have an enum defined as follows: + +```csharp +public enum Status +{ + [Display(Name = "Active User")] + Active, + [Description("Inactive User")] + Inactive, + Pending +} +``` + +Binding a value of `Status.Active` to the converter will display "Active User". If the value is `Status.Inactive`, it will display "Inactive User". If the value is `Status.Pending`, it will display "Pending" (the enum name). + +### Localized Enum Example + +You can use `DisplayAttribute` with `ResourceType` to provide localized display names: + +```csharp +public enum Status +{ + [Display(Name = "Active_User", ResourceType = typeof(Resources.StatusResources))] + Active, + [Display(Name = "Inactive_User", ResourceType = typeof(Resources.StatusResources))] + Inactive, + Pending +} +``` + +Where `StatusResources` is a resource file containing: + +| Key | Value (en-US) | Value (fr-FR) | +|---------------|-----------------|-----------------| +| Active_User | Active User | Utilisateur Actif| +| Inactive_User | Inactive User | Utilisateur Inactif| + +> **Note:** If the resource key is missing or not found, the converter will return the enum member name (e.g., `Active`). This ensures a string is always returned, but may not be localized or user-friendly. + + +## API + +You can find the source code for `EnumDescriptionConverter` over on the [CommunityToolkit.Maui GitHub repository](https://github.com/CommunityToolkit/Maui/blob/main/src/CommunityToolkit.Maui/Converters/EnumDescriptionConverter.shared.cs). + +- If `DisplayAttribute.Name` is defined, it is used. +- If `DescriptionAttribute.Description` is defined, it is used. +- Otherwise, the enum name is returned. + +**Namespace:** `CommunityToolkit.Maui.Converters` + +**Class:** `EnumDescriptionConverter` + +**Base:** `BaseConverterOneWay` + +## See Also +- [DisplayAttribute Documentation](/dotnet/api/system.componentmodel.dataannotations.displayattribute) +- [DescriptionAttribute Documentation](/dotnet/api/system.componentmodel.descriptionattribute)