Merge branch 'master' into bassmix

osu.Framework.Benchmarks/BenchmarkLocalisableDescription.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 BenchmarkDotNet.Attributes;
+using osu.Framework.Extensions;
+using osu.Framework.Localisation;
+
+namespace osu.Framework.Benchmarks
+{
+    public class BenchmarkLocalisableDescription
+    {
+        private LocalisableString[] descriptions;
+
+        [Params(1, 10, 100, 1000)]
+        public int Times { get; set; }
+
+        [GlobalSetup]
+        public void SetUp()
+        {
+            descriptions = new LocalisableString[Times];
+        }
+
+        [Benchmark]
+        public LocalisableString[] GetLocalisableDescription()
+        {
+            for (int i = 0; i < Times; i++)
+                descriptions[i] = TestLocalisableEnum.One.GetLocalisableDescription();
+
+            return descriptions;
+        }
+
+        private enum TestLocalisableEnum
+        {
+            [LocalisableDescription(typeof(TestStrings), nameof(TestStrings.One))]
+            One,
+        }
+
+        private static class TestStrings
+        {
+            public static LocalisableString One => "1";
+        }
+    }
+}

osu.Framework.Templates/templates/template-empty/TemplateGame.Game/TemplateGame.Game.csproj

···
     <ProjectReference Include="..\TemplateGame.Resources\TemplateGame.Resources.csproj" />
   </ItemGroup>
   <ItemGroup>
-    <PackageReference Include="ppy.osu.Framework" Version="2021.630.0" />
+    <PackageReference Include="ppy.osu.Framework" Version="2021.728.0" />
   </ItemGroup>
 </Project>

osu.Framework.Templates/templates/template-empty/TemplateGame.iOS/TemplateGame.iOS.csproj

···
     <Reference Include="System.Net.Http" />
   </ItemGroup>
   <ItemGroup Label="Package References">
-    <PackageReference Include="ppy.osu.Framework.iOS" Version="2021.630.0" />
+    <PackageReference Include="ppy.osu.Framework.iOS" Version="2021.728.0" />
   </ItemGroup>
   <ItemGroup Label="Transitive Dependencies">
-    <PackageReference Include="ppy.osu.Framework" Version="2021.630.0" />
+    <PackageReference Include="ppy.osu.Framework" Version="2021.728.0" />
     <PackageReference Include="ppy.osu.Framework.NativeLibs" Version="2019.1104.0" ExcludeAssets="all" />
   </ItemGroup>
   <Import Project="$(MSBuildExtensionsPath)\Xamarin\iOS\Xamarin.iOS.CSharp.targets" />

osu.Framework.Templates/templates/template-flappy/FlappyDon.Game/FlappyDon.Game.csproj

···
     <TargetFramework>netstandard2.1</TargetFramework>
   </PropertyGroup>
   <ItemGroup>
-    <PackageReference Include="ppy.osu.Framework" Version="2021.630.0" />
+    <PackageReference Include="ppy.osu.Framework" Version="2021.728.0" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\FlappyDon.Resources\FlappyDon.Resources.csproj" />

osu.Framework.Templates/templates/template-flappy/FlappyDon.iOS/FlappyDon.iOS.csproj

···
     <Reference Include="System.Net.Http" />
   </ItemGroup>
   <ItemGroup Label="Package References">
-    <PackageReference Include="ppy.osu.Framework.iOS" Version="2021.630.0" />
+    <PackageReference Include="ppy.osu.Framework.iOS" Version="2021.728.0" />
   </ItemGroup>
   <ItemGroup Label="Transitive Dependencies">
-    <PackageReference Include="ppy.osu.Framework" Version="2021.630.0" />
+    <PackageReference Include="ppy.osu.Framework" Version="2021.728.0" />
     <PackageReference Include="ppy.osu.Framework.NativeLibs" Version="2019.1104.0" ExcludeAssets="all" />
   </ItemGroup>
   <Import Project="$(MSBuildExtensionsPath)\Xamarin\iOS\Xamarin.iOS.CSharp.targets" />

osu.Framework.Tests/Localisation/LocalisableDescriptionAttributeTest.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 LocalisableDescriptionAttributeTest
+    {
+        [TestCase(EnumA.Item1, "Item1")]
+        [TestCase(EnumA.Item2, "B")]
+        public void TestNonLocalisableDescriptionReturnsDescriptionOrToString(EnumA value, string expected)
+        {
+            Assert.That(value.GetLocalisableDescription().ToString(), Is.EqualTo(expected));
+        }
+
+        [TestCase(EnumB.Item1, "Localised A")]
+        [TestCase(EnumB.Item2, "Localised B")]
+        public void TestLocalisableDescriptionReturnsDesignatedString(EnumB value, string expected)
+        {
+            Assert.That(value.GetLocalisableDescription().ToString(), Is.EqualTo(expected));
+        }
+
+        [Test]
+        public void TestClassLocalisableDescription()
+        {
+            Assert.That(new ClassA().GetLocalisableDescription().ToString(), Is.EqualTo("Localised A"));
+        }
+
+        [Test]
+        public void TestLocalisableDescriptionWithNonExistingMemberThrows()
+        {
+            Assert.Throws<InvalidOperationException>(() => EnumC.Item1.GetLocalisableDescription());
+        }
+
+        [Test]
+        public void TestLocalisableDescriptionWithInstanceMemberThrows()
+        {
+            Assert.Throws<InvalidOperationException>(() => EnumD.Item1.GetLocalisableDescription());
+        }
+
+        public enum EnumA
+        {
+            Item1,
+
+            [System.ComponentModel.Description("B")]
+            Item2
+        }
+
+        public enum EnumB
+        {
+            [LocalisableDescription(typeof(TestStrings), nameof(TestStrings.A))]
+            Item1,
+
+            [LocalisableDescription(typeof(TestStrings), nameof(TestStrings.B))]
+            Item2
+        }
+
+        public enum EnumC
+        {
+            [LocalisableDescription(typeof(LocalisableDescriptionAttributeTest), nameof(TestStrings.A))]
+            Item1,
+        }
+
+        public enum EnumD
+        {
+            [LocalisableDescription(typeof(TestStrings), nameof(TestStrings.Instance))]
+            Item1,
+        }
+
+        [LocalisableDescription(typeof(TestStrings), nameof(TestStrings.A))]
+        public class ClassA
+        {
+        }
+
+        private class TestStrings
+        {
+            public static LocalisableString A => "Localised A";
+
+            public static readonly LocalisableString B = "Localised B";
+
+            public LocalisableString Instance => string.Empty;
+        }
+    }
+}

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.Extensions.ObjectExtensions;
 using osu.Framework.Localisation;
 using osu.Framework.Platform;
 using osuTK;
···
         }
 
         /// <summary>
-        /// Returns the description of a given enum value, via (in order):
+        /// Returns the localisable description of a given object, via (in order):
         /// <list type="number">
         ///   <item>
-        ///     <description>Any <see cref="LocalisableEnumAttribute"/> attached to the enum type.</description>
+        ///     <description>Any attached <see cref="LocalisableDescriptionAttribute"/>.</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>
+        /// <exception cref="InvalidOperationException">
+        /// When the <see cref="LocalisableDescriptionAttribute.Name"/> specified in the <see cref="LocalisableDescriptionAttribute"/>
+        /// does not match any of the existing members in <see cref="LocalisableDescriptionAttribute.DeclaringType"/>.
+        /// </exception>
         public static LocalisableString GetLocalisableDescription<T>(this T value)
-            where T : Enum
         {
-            var enumType = value.GetType();
+            MemberInfo type;
 
-            var mapperType = enumType.GetCustomAttribute<LocalisableEnumAttribute>()?.MapperType;
-            if (mapperType == null)
-                return GetDescription(value);
+            if (value is Enum)
+                type = value.GetType().GetField(value.ToString());
+            else
+                type = value.GetType();
 
-            var mapperInstance = Activator.CreateInstance(mapperType);
-            if (mapperInstance == null)
-                throw new InvalidOperationException($"Could not create the {nameof(EnumLocalisationMapper<T>)} for enum type {enumType.ReadableName()}");
+            var attribute = type.GetCustomAttribute<LocalisableDescriptionAttribute>();
+            if (attribute == null)
+                return GetDescription(value);
 
-            var mapMethod = mapperType.GetMethod(nameof(EnumLocalisationMapper<T>.Map), BindingFlags.Instance | BindingFlags.Public);
-            Debug.Assert(mapMethod != null);
+            var property = attribute.DeclaringType.GetMember(attribute.Name, BindingFlags.Static | BindingFlags.Public).FirstOrDefault();
 
-            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.");
+            switch (property)
+            {
+                case FieldInfo f:
+                    return (LocalisableString)f.GetValue(null).AsNonNull();
 
-            var mappedValue = mapMethod.Invoke(mapperInstance, new object[] { value });
-            Debug.Assert(mappedValue != null);
+                case PropertyInfo p:
+                    return (LocalisableString)p.GetValue(null).AsNonNull();
 
-            return (LocalisableString)mappedValue;
+                default:
+                    throw new InvalidOperationException($"Member \"{attribute.Name}\" was not found in type {attribute.DeclaringType} (must be a static field or property)");
+            }
         }
 
         /// <summary>

osu.Framework/Graphics/Drawable.cs

···
         /// <summary>
         /// A lock exclusively used for initial acquisition/construction of the <see cref="Scheduler"/>.
         /// </summary>
-        private readonly object schedulerAcquisitionLock = new object();
+        private static readonly object scheduler_acquisition_lock = new object();
 
         private Scheduler scheduler;
 
···
                 if (scheduler != null)
                     return scheduler;
 
-                lock (schedulerAcquisitionLock)
+                lock (scheduler_acquisition_lock)
                     return scheduler ??= new Scheduler(() => ThreadSafety.IsUpdateThread, Clock);
             }
         }

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/LocalisableDescriptionAttribute.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;
+
+namespace osu.Framework.Localisation
+{
+    /// <summary>
+    /// Specifies a <see cref="LocalisableString"/>-based description for the target element.
+    /// The description can be retrieved through <see cref="ExtensionMethods.GetLocalisableDescription{T}"/>.
+    /// </summary>
+    /// <remarks>
+    /// The C# language specification
+    /// <a href="https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/attributes#attribute-parameter-types">
+    /// only permits a limited set of parameter types for attributes,
+    /// </a>
+    /// and as such <see cref="LocalisableString"/> instances cannot be passed in directly.
+    /// Therefore usages must pass both the target type in which the <see cref="LocalisableString"/> description is declared,
+    /// as well as the name of the member which contains/returns the <see cref="LocalisableString"/> (using <see langword="nameof"/> for this is strongly encouraged).
+    /// </remarks>
+    /// <example>
+    /// Assuming the following source class from which the <see cref="LocalisableString"/> description should be returned:
+    /// <code>
+    /// class Strings
+    /// {
+    ///     public static LocalisableString Example => "example string";
+    /// }
+    /// </code>
+    /// the attribute should be used in the following way:
+    /// <code>
+    /// [LocalisableDescription(typeof(Strings), nameof(Strings.Example))]
+    /// </code>
+    /// </example>
+    [AttributeUsage(AttributeTargets.All)]
+    public sealed class LocalisableDescriptionAttribute : Attribute
+    {
+        /// <summary>
+        /// The type declaring the static member providing the localisable description.
+        /// </summary>
+        public readonly Type DeclaringType;
+
+        /// <summary>
+        /// The name of the static member providing the localisable description.
+        /// </summary>
+        public readonly string Name;
+
+        /// <summary>
+        /// Creates a new <see cref="LocalisableDescriptionAttribute"/>.
+        /// </summary>
+        public LocalisableDescriptionAttribute(Type declaringType, string name)
+        {
+            DeclaringType = declaringType;
+            Name = name;
+        }
+    }
+}

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));
-        }
-    }
-}

osu.Framework/Platform/Windows/Native/Input.cs

···
     internal static class Input
     {
         [DllImport("user32.dll")]
-        public static extern bool RegisterRawInputDevices([MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)]
-                                                          RawInputDevice[] pRawInputDevices, int uiNumDevices, int cbSize);
+        public static extern bool RegisterRawInputDevices(
+            [MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 1)]
+            RawInputDevice[] pRawInputDevices,
+            int uiNumDevices,
+            int cbSize);
 
         [DllImport("user32.dll")]
         public static extern int GetRawInputData(IntPtr hRawInput, RawInputCommand uiCommand, out RawInputData pData, ref int pcbSize, int cbSizeHeader);