Merge pull request #4518 from smoogipoo/add-localisable-description

Add LocalisableEnumAttribute and GetLocalisableDescription() extension method

osu.Framework.Tests/Localisation/LocalisableEnumAttributeTest.cs

···
+// Copyright (c) ppy Pty Ltd <[e-mail]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using NUnit.Framework;
+using osu.Framework.Extensions;
+using osu.Framework.Localisation;
+
+namespace osu.Framework.Tests.Localisation
+{
+    [TestFixture]
+    public class LocalisableEnumAttributeTest
+    {
+        [TestCase(EnumA.Item1, "Item1")]
+        [TestCase(EnumA.Item2, "B")]
+        public void TestNonLocalisableEnumReturnsDescriptionOrToString(EnumA value, string expected)
+        {
+            Assert.That(value.GetLocalisableDescription().ToString(), Is.EqualTo(expected));
+        }
+
+        [TestCase(EnumB.Item1, "A")]
+        [TestCase(EnumB.Item2, "B")]
+        public void TestLocalisableEnumReturnsMappedValue(EnumB value, string expected)
+        {
+            Assert.That(value.GetLocalisableDescription().ToString(), Is.EqualTo(expected));
+        }
+
+        [Test]
+        public void TestLocalisableEnumWithInvalidBaseTypeThrows()
+        {
+            // ReSharper disable once ReturnValueOfPureMethodIsNotUsed
+            Assert.Throws<ArgumentException>(() => EnumC.Item1.GetLocalisableDescription().ToString());
+        }
+
+        [Test]
+        public void TestLocalisableEnumWithInvalidGenericTypeThrows()
+        {
+            // ReSharper disable once ReturnValueOfPureMethodIsNotUsed
+            Assert.Throws<InvalidOperationException>(() => EnumD.Item1.GetLocalisableDescription().ToString());
+        }
+
+        public enum EnumA
+        {
+            Item1,
+
+            [System.ComponentModel.Description("B")]
+            Item2
+        }
+
+        [LocalisableEnum(typeof(EnumBEnumLocalisationMapper))]
+        public enum EnumB
+        {
+            Item1,
+            Item2
+        }
+
+        private class EnumBEnumLocalisationMapper : EnumLocalisationMapper<EnumB>
+        {
+            public override LocalisableString Map(EnumB value)
+            {
+                switch (value)
+                {
+                    case EnumB.Item1:
+                        return "A";
+
+                    case EnumB.Item2:
+                        return "B";
+
+                    default:
+                        throw new ArgumentOutOfRangeException(nameof(value), value, null);
+                }
+            }
+        }
+
+        [LocalisableEnum(typeof(EnumCEnumLocalisationMapper))]
+        public enum EnumC
+        {
+            Item1,
+        }
+
+        private class EnumCEnumLocalisationMapper
+        {
+        }
+
+        [LocalisableEnum(typeof(EnumDEnumLocalisationMapper))]
+        public enum EnumD
+        {
+            Item1,
+        }
+
+        private class EnumDEnumLocalisationMapper : EnumLocalisationMapper<EnumA>
+        {
+            public override LocalisableString Map(EnumA value) => "A";
+        }
+    }
+}

osu.Framework/Extensions/ExtensionMethods.cs

···
 using System;
 using System.Collections.Generic;
 using System.ComponentModel;
+using System.Diagnostics;
 using System.Drawing;
 using System.IO;
 using System.Linq;
 using System.Reflection;
 using System.Security.Cryptography;
 using System.Text;
+using osu.Framework.Extensions.TypeExtensions;
+using osu.Framework.Localisation;
 using osu.Framework.Platform;
 using osuTK;
 
···
             }
         }
 
+        /// <summary>
+        /// Returns the description of a given enum value, via (in order):
+        /// <list type="number">
+        ///   <item>
+        ///     <description>Any <see cref="LocalisableEnumAttribute"/> attached to the enum type.</description>
+        ///   </item>
+        ///   <item>
+        ///     <description><see cref="GetDescription"/></description>
+        ///   </item>
+        /// </list>
+        /// </summary>
+        /// <exception cref="InvalidOperationException">When the enum type has an attached <see cref="LocalisableEnumAttribute"/>
+        /// and the <see cref="EnumLocalisationMapper{T}"/> could not be instantiated.</exception>
+        /// <exception cref="InvalidOperationException">When the enum type has an attached <see cref="LocalisableEnumAttribute"/>
+        /// and the type handled by the <see cref="EnumLocalisationMapper{T}"/> is not <typeparamref name="T"/>.</exception>
+        public static LocalisableString GetLocalisableDescription<T>(this T value)
+            where T : Enum
+        {
+            var enumType = value.GetType();
+
+            var mapperType = enumType.GetCustomAttribute<LocalisableEnumAttribute>()?.MapperType;
+            if (mapperType == null)
+                return GetDescription(value);
+
+            var mapperInstance = Activator.CreateInstance(mapperType);
+            if (mapperInstance == null)
+                throw new InvalidOperationException($"Could not create the {nameof(EnumLocalisationMapper<T>)} for enum type {enumType.ReadableName()}");
+
+            var mapMethod = mapperType.GetMethod(nameof(EnumLocalisationMapper<T>.Map), BindingFlags.Instance | BindingFlags.Public);
+            Debug.Assert(mapMethod != null);
+
+            var expectedMappingType = mapMethod.GetParameters()[0].ParameterType;
+            if (expectedMappingType != enumType)
+                throw new InvalidOperationException($"Cannot use {mapperType.ReadableName()} (maps {expectedMappingType.ReadableName()} enum values) to map {enumType.ReadableName()} enum values.");
+
+            var mappedValue = mapMethod.Invoke(mapperInstance, new object[] { value });
+            Debug.Assert(mappedValue != null);
+
+            return (LocalisableString)mappedValue;
+        }
+
+        /// <summary>
+        /// Returns the description of a given object, via (in order):
+        /// <list type="number">
+        ///   <item>
+        ///     <description>Any attached <see cref="DescriptionAttribute"/>.</description>
+        ///   </item>
+        ///   <item>
+        ///     <description>The object's <see cref="object.ToString()"/>.</description>
+        ///   </item>
+        /// </list>
+        /// </summary>
         public static string GetDescription(this object value)
             => value.GetType()
                     .GetField(value.ToString())?

osu.Framework/Graphics/UserInterface/Dropdown.cs

···
                     return t.Text;
 
                 case Enum e:
-                    return e.GetDescription();
+                    return e.GetLocalisableDescription();
 
                 default:
                     return item?.ToString() ?? "null";

osu.Framework/Localisation/EnumLocalisationMapper.cs

···
+// Copyright (c) ppy Pty Ltd <[e-mail]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+
+namespace osu.Framework.Localisation
+{
+    /// <summary>
+    /// Describes the values of an <see cref="Enum"/> type by <see cref="LocalisableString"/>s.
+    /// </summary>
+    /// <typeparam name="T">The <see cref="Enum"/> type.</typeparam>
+    public abstract class EnumLocalisationMapper<T> : IEnumLocalisationMapper
+        where T : Enum
+    {
+        /// <summary>
+        /// Describes a <typeparamref name="T"/> value by a <see cref="LocalisableString"/>.
+        /// </summary>
+        /// <param name="value">The value to map.</param>
+        /// <returns>The <see cref="LocalisableString"/> describing <paramref name="value"/>.</returns>
+        public abstract LocalisableString Map(T value);
+    }
+
+    /// <summary>
+    /// Marker class for <see cref="EnumLocalisationMapper{T}"/>. Do not use.
+    /// </summary>
+    internal interface IEnumLocalisationMapper
+    {
+    }
+}

osu.Framework/Localisation/LocalisableEnumAttribute.cs

···
+// Copyright (c) ppy Pty Ltd <[e-mail]>. Licensed under the MIT Licence.
+// See the LICENCE file in the repository root for full licence text.
+
+using System;
+using osu.Framework.Extensions;
+using osu.Framework.Extensions.TypeExtensions;
+
+namespace osu.Framework.Localisation
+{
+    /// <summary>
+    /// Indicates that the values of an enum have <see cref="LocalisableString"/> descriptions.
+    /// The descriptions can be retrieved through <see cref="ExtensionMethods.GetLocalisableDescription{T}"/>.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Enum)]
+    public sealed class LocalisableEnumAttribute : Attribute
+    {
+        /// <summary>
+        /// The <see cref="EnumLocalisationMapper{T}"/> type that maps enum values to <see cref="LocalisableString"/>s.
+        /// </summary>
+        public readonly Type MapperType;
+
+        /// <summary>
+        /// Creates a new <see cref="LocalisableEnumAttribute"/>.
+        /// </summary>
+        /// <param name="mapperType">The <see cref="EnumLocalisationMapper{T}"/> type that maps enum values to <see cref="LocalisableString"/>s.</param>
+        public LocalisableEnumAttribute(Type mapperType)
+        {
+            MapperType = mapperType;
+
+            if (!typeof(IEnumLocalisationMapper).IsAssignableFrom(mapperType))
+                throw new ArgumentException($"Type \"{mapperType.ReadableName()}\" must inherit from {nameof(EnumLocalisationMapper<Enum>)}.", nameof(mapperType));
+        }
+    }
+}