add content language changed event (#243)

release-notes.md

@@ -5,8 +5,9 @@
 See [log](https://github.com/Pathoschild/SMAPI/compare/1.9...2.0).
 
 For mod developers:
-* Added content events and an API which let you intercept XNB content as it's loaded, then
+* Added `ContentEvents.AssetLoading` event with a helper which lets you intercept the XNB content
-  dynamically replace data entries or patch images.
+  load, and dynamically adjust or replace the content being loaded (including support for patching
+  images).
 -->
 
 ## 1.9
@@ -29,7 +30,7 @@ For players:
 * Fixed errors in console command handlers causing the game to crash.
 
 For mod developers:
-* Added `SaveEvents.AfterReturnToTitle` and `TimeEvents.AfterDayStarted` events.
+* Added `SaveEvents.AfterReturnToTitle`, `TimeEvents.AfterDayStarted`, and `ContentEvents.AfterLocaleChanged` events.
 * Added a simpler API for console commands (see `helper.ConsoleCommands`).
 * Added `GetPrivateProperty` reflection helper.
 * SMAPI now writes XNA input enums (`Buttons` and `Keys`) to JSON as strings automatically, so mods no longer need to add a `StringEnumConverter` themselves for those.

src/StardewModdingAPI/Events/ContentEvents.cs

@@ -24,6 +24,9 @@ namespace StardewModdingAPI.Events
         /*********
         ** Events
         *********/
+        /// <summary>Raised after the content language changes.</summary>
+        public static event EventHandler<EventArgsValueChanged<string>> AfterLocaleChanged;
+
         /// <summary>Raised when an XNB file is being read into the cache. Mods can change the data here before it's cached.</summary>
         public static event EventHandler<IContentEventHelper> AssetLoading;
 
@@ -40,6 +43,15 @@ namespace StardewModdingAPI.Events
             ContentEvents.Monitor = monitor;
         }
 
+        /// <summary>Raise an <see cref="AfterLocaleChanged"/> event.</summary>
+        /// <param name="monitor">Encapsulates monitoring and logging.</param>
+        /// <param name="oldLocale">The previous locale.</param>
+        /// <param name="newLocale">The current locale.</param>
+        internal static void InvokeAfterLocaleChanged(IMonitor monitor, string oldLocale, string newLocale)
+        {
+            monitor.SafelyRaiseGenericEvent($"{nameof(ContentEvents)}.{nameof(ContentEvents.AfterLocaleChanged)}", ContentEvents.AfterLocaleChanged?.GetInvocationList(), null, new EventArgsValueChanged<string>(oldLocale, newLocale));
+        }
+
         /// <summary>Raise an <see cref="AssetLoading"/> event.</summary>
         /// <param name="monitor">Encapsulates monitoring and logging.</param>
         /// <param name="contentHelper">Encapsulates access and changes to content being read from a data file.</param>

src/StardewModdingAPI/Events/EventArgsIntChanged.cs

@@ -9,11 +9,10 @@ namespace StardewModdingAPI.Events
         ** Accessors
         *********/
         /// <summary>The previous value.</summary>
-        public int NewInt { get; }
-
-        /// <summary>The current value.</summary>
         public int PriorInt { get; }
 
+        /// <summary>The current value.</summary>
+        public int NewInt { get; }
 
         /*********
         ** Public methods

src/StardewModdingAPI/Events/EventArgsValueChanged.cs

@@ -0,0 +1,31 @@
+using System;
+
+namespace StardewModdingAPI.Events
+{
+    /// <summary>Event arguments for a field that changed value.</summary>
+    /// <typeparam name="T">The value type.</typeparam>
+    public class EventArgsValueChanged<T> : EventArgs
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The previous value.</summary>
+        public T PriorValue { get; }
+
+        /// <summary>The current value.</summary>
+        public T NewValue { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="priorValue">The previous value.</param>
+        /// <param name="newValue">The current value.</param>
+        public EventArgsValueChanged(T priorValue, T newValue)
+        {
+            this.PriorValue = priorValue;
+            this.NewValue = newValue;
+        }
+    }
+}

src/StardewModdingAPI/Framework/SGame.cs

@@ -159,6 +159,9 @@ namespace StardewModdingAPI.Framework
         /// <summary>The player character at last check.</summary>
         public SFarmer PreviousFarmer { get; private set; }
 
+        /// <summary>The previous content locale.</summary>
+        public LocalizedContentManager.LanguageCode? PreviousLocale { get; private set; }
+
         /// <summary>An index incremented on every tick and reset every 60th tick (0–59).</summary>
         public int CurrentUpdateTick { get; private set; }
 
@@ -1079,6 +1082,17 @@ namespace StardewModdingAPI.Framework
         /// <summary>Detect changes since the last update ticket and trigger mod events.</summary>
         private void UpdateEventCalls()
         {
+            // content locale changed event
+            if (this.PreviousLocale != LocalizedContentManager.CurrentLanguageCode)
+            {
+                var oldValue = this.PreviousLocale;
+                var newValue = LocalizedContentManager.CurrentLanguageCode;
+
+                if (oldValue != null)
+                    ContentEvents.InvokeAfterLocaleChanged(this.Monitor, oldValue.ToString(), newValue.ToString());
+                this.PreviousLocale = newValue;
+            }
+
             // save loaded event
             if (Game1.hasLoadedGame && !SaveGame.IsProcessing/*still loading save*/ && this.AfterLoadTimer >= 0)
             {

src/StardewModdingAPI/StardewModdingAPI.csproj

@@ -119,6 +119,7 @@
     <Compile Include="Advanced\IConfigFile.cs" />
     <Compile Include="Command.cs" />
     <Compile Include="Events\ContentEvents.cs" />
+    <Compile Include="Events\EventArgsValueChanged.cs" />
     <Compile Include="Framework\Command.cs" />
     <Compile Include="Config.cs" />
     <Compile Include="Constants.cs" />