From 075a26dc83eb2144e1fa5be12fa3e97196e77989 Mon Sep 17 00:00:00 2001 From: Billy Martin Date: Tue, 10 Mar 2026 03:18:39 -0400 Subject: [PATCH 1/4] Add documentation for EnumDescriptionConverter Include usage instructions and examples for the EnumDescriptionConverter, which converts enum values to display strings using the DisplayAttribute or DescriptionAttribute. The documentation covers XAML, C#, and C# Markup implementations. --- .../converters/enum-description-converter.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs/maui/converters/enum-description-converter.md diff --git a/docs/maui/converters/enum-description-converter.md b/docs/maui/converters/enum-description-converter.md new file mode 100644 index 00000000..428de60f --- /dev/null +++ b/docs/maui/converters/enum-description-converter.md @@ -0,0 +1,122 @@ +--- +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 `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). + +You can find an example of this converter in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Converters/EnumDescriptionConverterPage.xaml). + +## API + +You can find the source code for `EnumDescriptionConverter` over on the [.NET MAUI Community Toolkit 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. + +## API + +- **Namespace:** `CommunityToolkit.Maui.Converters` +- **Class:** `EnumDescriptionConverter` +- **Base:** `BaseConverterOneWay` + +## See Also +- [DisplayAttribute Documentation](https://learn.microsoft.com/dotnet/api/system.componentmodel.dataannotations.displayattribute) +- [DescriptionAttribute Documentation](https://learn.microsoft.com/dotnet/api/system.componentmodel.descriptionattribute) From 32377530dfc4845647ef1012ae77f07a8690008f Mon Sep 17 00:00:00 2001 From: Billy Martin Date: Tue, 10 Mar 2026 04:15:10 -0400 Subject: [PATCH 2/4] Add localized enum example to EnumDescriptionConverter documentation Include a new section demonstrating how to use the DisplayAttribute with ResourceType for localized display names. This update also clarifies that the converter returns the enum member name as a fallback if a resource key is missing. --- .../converters/enum-description-converter.md | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/maui/converters/enum-description-converter.md b/docs/maui/converters/enum-description-converter.md index 428de60f..65298c95 100644 --- a/docs/maui/converters/enum-description-converter.md +++ b/docs/maui/converters/enum-description-converter.md @@ -86,6 +86,7 @@ class EnumDescriptionConverterPage : ContentPage ## Examples + Suppose you have an enum defined as follows: ```csharp @@ -101,7 +102,29 @@ public enum Status 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). -You can find an example of this converter in action in the [.NET MAUI Community Toolkit Sample Application](https://github.com/CommunityToolkit/Maui/blob/main/samples/CommunityToolkit.Maui.Sample/Pages/Converters/EnumDescriptionConverterPage.xaml). +### 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 From adc487fa5b3ab36dc1faf751f1d5a3b4dc2bf30d Mon Sep 17 00:00:00 2001 From: Billy Martin Date: Tue, 10 Mar 2026 05:48:08 -0400 Subject: [PATCH 3/4] Update EnumDescriptionConverter documentation and links Update repository name references and clean up the API section formatting by removing a duplicate header. Convert absolute Microsoft Learn links to site-relative paths for better integration within the documentation site. --- .../maui/converters/enum-description-converter.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/maui/converters/enum-description-converter.md b/docs/maui/converters/enum-description-converter.md index 65298c95..683257cc 100644 --- a/docs/maui/converters/enum-description-converter.md +++ b/docs/maui/converters/enum-description-converter.md @@ -126,20 +126,21 @@ Where `StatusResources` is a resource file containing: > **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 [.NET MAUI Community Toolkit GitHub repository](https://github.com/CommunityToolkit/Maui/blob/main/src/CommunityToolkit.Maui/Converters/EnumDescriptionConverter.shared.cs). +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. -## API +**Namespace:** `CommunityToolkit.Maui.Converters` + +**Class:** `EnumDescriptionConverter` -- **Namespace:** `CommunityToolkit.Maui.Converters` -- **Class:** `EnumDescriptionConverter` -- **Base:** `BaseConverterOneWay` +**Base:** `BaseConverterOneWay` ## See Also -- [DisplayAttribute Documentation](https://learn.microsoft.com/dotnet/api/system.componentmodel.dataannotations.displayattribute) -- [DescriptionAttribute Documentation](https://learn.microsoft.com/dotnet/api/system.componentmodel.descriptionattribute) +- [DisplayAttribute Documentation](/dotnet/api/system.componentmodel.dataannotations.displayattribute) +- [DescriptionAttribute Documentation](/dotnet/api/system.componentmodel.descriptionattribute) From 256980a23b2bded81b7111f9c306534dc75abd5c Mon Sep 17 00:00:00 2001 From: Billy Martin Date: Tue, 10 Mar 2026 05:51:29 -0400 Subject: [PATCH 4/4] Update enum converter links to site-relative paths Update the introductory paragraph in the EnumDescriptionConverter documentation to use site-relative paths for the DisplayAttribute and DescriptionAttribute links. --- docs/maui/converters/enum-description-converter.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/maui/converters/enum-description-converter.md b/docs/maui/converters/enum-description-converter.md index 683257cc..70f23076 100644 --- a/docs/maui/converters/enum-description-converter.md +++ b/docs/maui/converters/enum-description-converter.md @@ -9,6 +9,7 @@ ms.date: 06/10/2024 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.