From b2e88bccf63545d950f4cbf47a0466321c614245 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Wed, 8 Mar 2017 15:25:30 -0500
Subject: add dictionary/image content helpers for more intuitive usage (#173)

---
 .../Framework/Content/ContentEventBaseHelper.cs    | 98 ++++++++++++++++++++++
 .../Framework/Content/ContentEventHelper.cs        | 47 +++++++++++
 .../Content/ContentEventHelperForDictionary.cs     | 36 ++++++++
 .../Content/ContentEventHelperForImage.cs          | 70 ++++++++++++++++
 4 files changed, 251 insertions(+)
 create mode 100644 src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
 create mode 100644 src/StardewModdingAPI/Framework/Content/ContentEventHelper.cs
 create mode 100644 src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
 create mode 100644 src/StardewModdingAPI/Framework/Content/ContentEventHelperForImage.cs

(limited to 'src/StardewModdingAPI/Framework/Content')

diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs b/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
new file mode 100644
index 00000000..736cdc70
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
@@ -0,0 +1,98 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Xna.Framework.Graphics;
+
+namespace StardewModdingAPI.Framework.Content
+{
+    /// <summary>Base implementation for a content helper which encapsulates access and changes to content being read from a data file.</summary>
+    /// <typeparam name="TValue">The interface value type.</typeparam>
+    internal class ContentEventBaseHelper<TValue> : EventArgs
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>Normalises an asset key to match the cache key.</summary>
+        protected readonly Func<string, string> GetNormalisedPath;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The content's locale code, if the content is localised.</summary>
+        public string Locale { get; }
+
+        /// <summary>The normalised asset name being read. The format may change between platforms; see <see cref="IsAssetName"/> to compare with a known path.</summary>
+        public string AssetName { get; }
+
+        /// <summary>The content data being read.</summary>
+        public TValue Data { get; protected set; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="locale">The content's locale code, if the content is localised.</param>
+        /// <param name="assetName">The normalised asset name being read.</param>
+        /// <param name="data">The content data being read.</param>
+        /// <param name="getNormalisedPath">Normalises an asset key to match the cache key.</param>
+        public ContentEventBaseHelper(string locale, string assetName, TValue data, Func<string, string> getNormalisedPath)
+        {
+            this.Locale = locale;
+            this.AssetName = assetName;
+            this.Data = data;
+            this.GetNormalisedPath = getNormalisedPath;
+        }
+
+        /// <summary>Get whether the asset name being loaded matches a given name after normalisation.</summary>
+        /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
+        public bool IsAssetName(string path)
+        {
+            path = this.GetNormalisedPath(path);
+            return this.AssetName.Equals(path, StringComparison.InvariantCultureIgnoreCase);
+        }
+
+        /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
+        /// <param name="value">The new content value.</param>
+        /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
+        /// <exception cref="InvalidCastException">The <paramref name="value"/>'s type is not compatible with the loaded asset's type.</exception>
+        public void ReplaceWith(TValue value)
+        {
+            if (value == null)
+                throw new ArgumentNullException(nameof(value), "Can't set a loaded asset to a null value.");
+            if (!this.Data.GetType().IsInstanceOfType(value))
+                throw new InvalidCastException($"Can't replace loaded asset of type {this.GetFriendlyTypeName(this.Data.GetType())} with value of type {this.GetFriendlyTypeName(value.GetType())}. The new type must be compatible to prevent game errors.");
+
+            this.Data = value;
+        }
+
+
+        /*********
+        ** Protected methods
+        *********/
+        /// <summary>Get a human-readable type name.</summary>
+        /// <param name="type">The type to name.</param>
+        protected string GetFriendlyTypeName(Type type)
+        {
+            // dictionary
+            if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Dictionary<,>))
+            {
+                Type[] genericArgs = type.GetGenericArguments();
+                return $"Dictionary<{this.GetFriendlyTypeName(genericArgs[0])}, {this.GetFriendlyTypeName(genericArgs[1])}>";
+            }
+
+            // texture
+            if (type == typeof(Texture2D))
+                return type.Name;
+
+            // native type
+            if (type == typeof(int))
+                return "int";
+            if (type == typeof(string))
+                return "string";
+
+            // default
+            return type.FullName;
+        }
+    }
+}
diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventHelper.cs b/src/StardewModdingAPI/Framework/Content/ContentEventHelper.cs
new file mode 100644
index 00000000..26292cab
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventHelper.cs
@@ -0,0 +1,47 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Xna.Framework.Graphics;
+
+namespace StardewModdingAPI.Framework.Content
+{
+    /// <summary>Encapsulates access and changes to content being read from a data file.</summary>
+    internal class ContentEventHelper : ContentEventBaseHelper<object>, IContentEventHelper
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="locale">The content's locale code, if the content is localised.</param>
+        /// <param name="assetName">The normalised asset name being read.</param>
+        /// <param name="data">The content data being read.</param>
+        /// <param name="getNormalisedPath">Normalises an asset key to match the cache key.</param>
+        public ContentEventHelper(string locale, string assetName, object data, Func<string, string> getNormalisedPath)
+            : base(locale, assetName, data, getNormalisedPath) { }
+
+        /// <summary>Get a helper to manipulate the data as a dictionary.</summary>
+        /// <typeparam name="TKey">The expected dictionary key.</typeparam>
+        /// <typeparam name="TValue">The expected dictionary balue.</typeparam>
+        /// <exception cref="InvalidOperationException">The content being read isn't a dictionary.</exception>
+        public IContentEventHelperForDictionary<TKey, TValue> AsDictionary<TKey, TValue>()
+        {
+            return new ContentEventHelperForDictionary<TKey, TValue>(this.Locale, this.AssetName, this.GetData<IDictionary<TKey, TValue>>(), this.GetNormalisedPath);
+        }
+
+        /// <summary>Get a helper to manipulate the data as an image.</summary>
+        /// <exception cref="InvalidOperationException">The content being read isn't an image.</exception>
+        public IContentEventHelperForImage AsImage()
+        {
+            return new ContentEventHelperForImage(this.Locale, this.AssetName, this.GetData<Texture2D>(), this.GetNormalisedPath);
+        }
+
+        /// <summary>Get the data as a given type.</summary>
+        /// <typeparam name="TData">The expected data type.</typeparam>
+        /// <exception cref="InvalidCastException">The data can't be converted to <typeparamref name="TData"/>.</exception>
+        public TData GetData<TData>()
+        {
+            if (!(this.Data is TData))
+                throw new InvalidCastException($"The content data of type {this.Data.GetType().FullName} can't be converted to the requested {typeof(TData).FullName}.");
+            return (TData)this.Data;
+        }
+    }
+}
diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
new file mode 100644
index 00000000..8fcaae3c
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
@@ -0,0 +1,36 @@
+using System;
+using System.Collections.Generic;
+
+namespace StardewModdingAPI.Framework.Content
+{
+    /// <summary>Encapsulates access and changes to dictionary content being read from a data file.</summary>
+    internal class ContentEventHelperForDictionary<TKey, TValue> : ContentEventBaseHelper<IDictionary<TKey, TValue>>, IContentEventHelperForDictionary<TKey, TValue>
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="locale">The content's locale code, if the content is localised.</param>
+        /// <param name="assetName">The normalised asset name being read.</param>
+        /// <param name="data">The content data being read.</param>
+        /// <param name="getNormalisedPath">Normalises an asset key to match the cache key.</param>
+        public ContentEventHelperForDictionary(string locale, string assetName, IDictionary<TKey, TValue> data, Func<string, string> getNormalisedPath)
+            : base(locale, assetName, data, getNormalisedPath) { }
+
+        /// <summary>Add or replace an entry in the dictionary data.</summary>
+        /// <param name="key">The entry key.</param>
+        /// <param name="value">The entry value.</param>
+        public void SetEntry(TKey key, TValue value)
+        {
+            this.Data[key] = value;
+        }
+
+        /// <summary>Add or replace an entry in the dictionary data.</summary>
+        /// <param name="key">The entry key.</param>
+        /// <param name="value">A callback which accepts the current value and returns the new value.</param>
+        public void SetEntry(TKey key, Func<TValue, TValue> value)
+        {
+            this.Data[key] = value(this.Data[key]);
+        }
+    }
+}
diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForImage.cs b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForImage.cs
new file mode 100644
index 00000000..23760f0f
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForImage.cs
@@ -0,0 +1,70 @@
+using System;
+using Microsoft.Xna.Framework;
+using Microsoft.Xna.Framework.Graphics;
+
+namespace StardewModdingAPI.Framework.Content
+{
+    /// <summary>Encapsulates access and changes to dictionary content being read from a data file.</summary>
+    internal class ContentEventHelperForImage : ContentEventBaseHelper<Texture2D>, IContentEventHelperForImage
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="locale">The content's locale code, if the content is localised.</param>
+        /// <param name="assetName">The normalised asset name being read.</param>
+        /// <param name="data">The content data being read.</param>
+        /// <param name="getNormalisedPath">Normalises an asset key to match the cache key.</param>
+        public ContentEventHelperForImage(string locale, string assetName, Texture2D data, Func<string, string> getNormalisedPath)
+            : base(locale, assetName, data, getNormalisedPath) { }
+
+        /// <summary>Overwrite part of the image.</summary>
+        /// <param name="source">The image to patch into the content.</param>
+        /// <param name="sourceArea">The part of the <paramref name="source"/> to copy (or <c>null</c> to take the whole texture). This must be within the bounds of the <paramref name="source"/> texture.</param>
+        /// <param name="targetArea">The part of the content to patch (or <c>null</c> to patch the whole texture). The original content within this area will be erased. This must be within the bounds of the existing spritesheet.</param>
+        /// <param name="patchMode">Indicates how an image should be patched.</param>
+        /// <exception cref="ArgumentNullException">One of the arguments is null.</exception>
+        /// <exception cref="ArgumentOutOfRangeException">The <paramref name="targetArea"/> is outside the bounds of the spritesheet.</exception>
+        public void PatchImage(Texture2D source, Rectangle? sourceArea = null, Rectangle? targetArea = null, PatchMode patchMode = PatchMode.Replace)
+        {
+            // get texture
+            Texture2D target = this.Data;
+
+            // get areas
+            sourceArea = sourceArea ?? new Rectangle(0, 0, source.Width, source.Height);
+            targetArea = targetArea ?? new Rectangle(0, 0, Math.Min(sourceArea.Value.Width, target.Width), Math.Min(sourceArea.Value.Height, target.Height));
+
+            // validate
+            if (source == null)
+                throw new ArgumentNullException(nameof(source), "Can't patch from a null source texture.");
+            if (sourceArea.Value.X < 0 || sourceArea.Value.Y < 0 || sourceArea.Value.Right > source.Width || sourceArea.Value.Bottom > source.Height)
+                throw new ArgumentOutOfRangeException(nameof(sourceArea), "The source area is outside the bounds of the source texture.");
+            if (targetArea.Value.X < 0 || targetArea.Value.Y < 0 || targetArea.Value.Right > target.Width || targetArea.Value.Bottom > target.Height)
+                throw new ArgumentOutOfRangeException(nameof(targetArea), "The target area is outside the bounds of the target texture.");
+            if (sourceArea.Value.Width != targetArea.Value.Width || sourceArea.Value.Height != targetArea.Value.Height)
+                throw new InvalidOperationException("The source and target areas must be the same size.");
+
+            // get source data
+            int pixelCount = sourceArea.Value.Width * sourceArea.Value.Height;
+            Color[] sourceData = new Color[pixelCount];
+            source.GetData(0, sourceArea, sourceData, 0, pixelCount);
+
+            // merge data in overlay mode
+            if (patchMode == PatchMode.Overlay)
+            {
+                Color[] newData = new Color[targetArea.Value.Width * targetArea.Value.Height];
+                target.GetData(0, targetArea, newData, 0, newData.Length);
+                for (int i = 0; i < sourceData.Length; i++)
+                {
+                    Color pixel = sourceData[i];
+                    if (pixel.A != 0) // not transparent
+                        newData[i] = pixel;
+                }
+                sourceData = newData;
+            }
+
+            // patch target texture
+            target.SetData(0, targetArea, sourceData, 0, pixelCount);
+        }
+    }
+}
-- 
cgit 


From 28c78e8f25a0d062d0dda49bc089ebebef8bfa20 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Wed, 8 Mar 2017 15:30:27 -0500
Subject: add dict content helper method to replace values based on a lambda
 (#173)

---
 .../Framework/Content/ContentEventHelperForDictionary.cs         | 9 +++++++++
 src/StardewModdingAPI/IContentEventHelperForDictionary.cs        | 4 ++++
 2 files changed, 13 insertions(+)

(limited to 'src/StardewModdingAPI/Framework/Content')

diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
index 8fcaae3c..9bfc16d8 100644
--- a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Linq;
 
 namespace StardewModdingAPI.Framework.Content
 {
@@ -32,5 +33,13 @@ namespace StardewModdingAPI.Framework.Content
         {
             this.Data[key] = value(this.Data[key]);
         }
+
+        /// <summary>Dynamically replace values in the dictionary.</summary>
+        /// <param name="replacer">A lambda which takes the current key and value for an entry, and returns the new value.</param>
+        public void Replace(Func<TKey, TValue, TValue> replacer)
+        {
+            foreach (var pair in this.Data.ToArray())
+                this.Data[pair.Key] = replacer(pair.Key, pair.Value);
+        }
     }
 }
diff --git a/src/StardewModdingAPI/IContentEventHelperForDictionary.cs b/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
index 1f259920..34796d5c 100644
--- a/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
+++ b/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
@@ -36,6 +36,10 @@ namespace StardewModdingAPI
         /// <param name="value">A callback which accepts the current value and returns the new value.</param>
         void SetEntry(TKey key, Func<TValue, TValue> value);
 
+        /// <summary>Dynamically replace values in the dictionary.</summary>
+        /// <param name="replacer">A lambda which takes the current key and value for an entry, and returns the new value.</param>
+        void Replace(Func<TKey, TValue, TValue> replacer);
+
         /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
         /// <param name="value">The new content value.</param>
         /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
-- 
cgit 


From d47cf433f39ddfa77c7903bca676f725052a2592 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Wed, 8 Mar 2017 15:34:38 -0500
Subject: use consistent dict helper method naming (#173)

---
 .../Framework/Content/ContentEventHelperForDictionary.cs       | 10 +++++-----
 src/StardewModdingAPI/IContentEventHelperForDictionary.cs      | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

(limited to 'src/StardewModdingAPI/Framework/Content')

diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
index 9bfc16d8..8a8a4845 100644
--- a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
@@ -18,25 +18,25 @@ namespace StardewModdingAPI.Framework.Content
         public ContentEventHelperForDictionary(string locale, string assetName, IDictionary<TKey, TValue> data, Func<string, string> getNormalisedPath)
             : base(locale, assetName, data, getNormalisedPath) { }
 
-        /// <summary>Add or replace an entry in the dictionary data.</summary>
+        /// <summary>Add or replace an entry in the dictionary.</summary>
         /// <param name="key">The entry key.</param>
         /// <param name="value">The entry value.</param>
-        public void SetEntry(TKey key, TValue value)
+        public void Set(TKey key, TValue value)
         {
             this.Data[key] = value;
         }
 
-        /// <summary>Add or replace an entry in the dictionary data.</summary>
+        /// <summary>Add or replace an entry in the dictionary.</summary>
         /// <param name="key">The entry key.</param>
         /// <param name="value">A callback which accepts the current value and returns the new value.</param>
-        public void SetEntry(TKey key, Func<TValue, TValue> value)
+        public void Set(TKey key, Func<TValue, TValue> value)
         {
             this.Data[key] = value(this.Data[key]);
         }
 
         /// <summary>Dynamically replace values in the dictionary.</summary>
         /// <param name="replacer">A lambda which takes the current key and value for an entry, and returns the new value.</param>
-        public void Replace(Func<TKey, TValue, TValue> replacer)
+        public void Set(Func<TKey, TValue, TValue> replacer)
         {
             foreach (var pair in this.Data.ToArray())
                 this.Data[pair.Key] = replacer(pair.Key, pair.Value);
diff --git a/src/StardewModdingAPI/IContentEventHelperForDictionary.cs b/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
index 34796d5c..34e69d42 100644
--- a/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
+++ b/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
@@ -26,19 +26,19 @@ namespace StardewModdingAPI
         /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
         bool IsAssetName(string path);
 
-        /// <summary>Add or replace an entry in the dictionary data.</summary>
+        /// <summary>Add or replace an entry in the dictionary.</summary>
         /// <param name="key">The entry key.</param>
         /// <param name="value">The entry value.</param>
-        void SetEntry(TKey key, TValue value);
+        void Set(TKey key, TValue value);
 
-        /// <summary>Add or replace an entry in the dictionary data.</summary>
+        /// <summary>Add or replace an entry in the dictionary.</summary>
         /// <param name="key">The entry key.</param>
         /// <param name="value">A callback which accepts the current value and returns the new value.</param>
-        void SetEntry(TKey key, Func<TValue, TValue> value);
+        void Set(TKey key, Func<TValue, TValue> value);
 
         /// <summary>Dynamically replace values in the dictionary.</summary>
         /// <param name="replacer">A lambda which takes the current key and value for an entry, and returns the new value.</param>
-        void Replace(Func<TKey, TValue, TValue> replacer);
+        void Set(Func<TKey, TValue, TValue> replacer);
 
         /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
         /// <param name="value">The new content value.</param>
-- 
cgit 


From ff39e9b1716104e02c92dfd56bb919887873bd3d Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Fri, 10 Mar 2017 11:05:17 -0500
Subject: move generic content properties & methods into separate interface
 (#173)

---
 .../Framework/Content/ContentEventBaseHelper.cs    |  2 +-
 src/StardewModdingAPI/IContentEventData.cs         | 35 ++++++++++++++++++++++
 src/StardewModdingAPI/IContentEventHelper.cs       | 25 +---------------
 .../IContentEventHelperForDictionary.cs            | 24 +--------------
 .../IContentEventHelperForImage.cs                 | 24 +--------------
 src/StardewModdingAPI/StardewModdingAPI.csproj     |  1 +
 6 files changed, 40 insertions(+), 71 deletions(-)
 create mode 100644 src/StardewModdingAPI/IContentEventData.cs

(limited to 'src/StardewModdingAPI/Framework/Content')

diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs b/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
index 736cdc70..a89fe337 100644
--- a/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
@@ -6,7 +6,7 @@ namespace StardewModdingAPI.Framework.Content
 {
     /// <summary>Base implementation for a content helper which encapsulates access and changes to content being read from a data file.</summary>
     /// <typeparam name="TValue">The interface value type.</typeparam>
-    internal class ContentEventBaseHelper<TValue> : EventArgs
+    internal class ContentEventBaseHelper<TValue> : EventArgs, IContentEventData<TValue>
     {
         /*********
         ** Properties
diff --git a/src/StardewModdingAPI/IContentEventData.cs b/src/StardewModdingAPI/IContentEventData.cs
new file mode 100644
index 00000000..a21861d2
--- /dev/null
+++ b/src/StardewModdingAPI/IContentEventData.cs
@@ -0,0 +1,35 @@
+using System;
+
+namespace StardewModdingAPI
+{
+    /// <summary>Generic metadata and methods for a content asset being loaded.</summary>
+    /// <typeparam name="TValue">The expected data type.</typeparam>
+    public interface IContentEventData<TValue>
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The content's locale code, if the content is localised.</summary>
+        string Locale { get; }
+
+        /// <summary>The normalised asset name being read. The format may change between platforms; see <see cref="IsAssetName"/> to compare with a known path.</summary>
+        string AssetName { get; }
+
+        /// <summary>The content data being read.</summary>
+        TValue Data { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get whether the asset name being loaded matches a given name after normalisation.</summary>
+        /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
+        bool IsAssetName(string path);
+
+        /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
+        /// <param name="value">The new content value.</param>
+        /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
+        /// <exception cref="InvalidCastException">The <paramref name="value"/>'s type is not compatible with the loaded asset's type.</exception>
+        void ReplaceWith(TValue value);
+    }
+}
diff --git a/src/StardewModdingAPI/IContentEventHelper.cs b/src/StardewModdingAPI/IContentEventHelper.cs
index 341778b4..421a1e06 100644
--- a/src/StardewModdingAPI/IContentEventHelper.cs
+++ b/src/StardewModdingAPI/IContentEventHelper.cs
@@ -3,28 +3,11 @@
 namespace StardewModdingAPI
 {
     /// <summary>Encapsulates access and changes to content being read from a data file.</summary>
-    public interface IContentEventHelper
+    public interface IContentEventHelper : IContentEventData<object>
     {
-        /*********
-        ** Accessors
-        *********/
-        /// <summary>The content's locale code, if the content is localised.</summary>
-        string Locale { get; }
-
-        /// <summary>The normalised asset name being read. The format may change between platforms; see <see cref="IsAssetName"/> to compare with a known path.</summary>
-        string AssetName { get; }
-
-        /// <summary>The content data being read.</summary>
-        object Data { get; }
-
-
         /*********
         ** Public methods
         *********/
-        /// <summary>Get whether the asset name being loaded matches a given name after normalisation.</summary>
-        /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
-        bool IsAssetName(string path);
-
         /// <summary>Get a helper to manipulate the data as a dictionary.</summary>
         /// <typeparam name="TKey">The expected dictionary key.</typeparam>
         /// <typeparam name="TValue">The expected dictionary balue.</typeparam>
@@ -39,11 +22,5 @@ namespace StardewModdingAPI
         /// <typeparam name="TData">The expected data type.</typeparam>
         /// <exception cref="InvalidCastException">The data can't be converted to <typeparamref name="TData"/>.</exception>
         TData GetData<TData>();
-
-        /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
-        /// <param name="value">The new content value.</param>
-        /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
-        /// <exception cref="InvalidCastException">The <paramref name="value"/>'s type is not compatible with the loaded asset's type.</exception>
-        void ReplaceWith(object value);
     }
 }
diff --git a/src/StardewModdingAPI/IContentEventHelperForDictionary.cs b/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
index 34e69d42..2f9d5a65 100644
--- a/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
+++ b/src/StardewModdingAPI/IContentEventHelperForDictionary.cs
@@ -4,28 +4,11 @@ using System.Collections.Generic;
 namespace StardewModdingAPI
 {
     /// <summary>Encapsulates access and changes to dictionary content being read from a data file.</summary>
-    public interface IContentEventHelperForDictionary<TKey, TValue>
+    public interface IContentEventHelperForDictionary<TKey, TValue> : IContentEventData<IDictionary<TKey, TValue>>
     {
-        /*********
-        ** Accessors
-        *********/
-        /// <summary>The content's locale code, if the content is localised.</summary>
-        string Locale { get; }
-
-        /// <summary>The normalised asset name being read. The format may change between platforms; see <see cref="IsAssetName"/> to compare with a known path.</summary>
-        string AssetName { get; }
-
-        /// <summary>The content data being read.</summary>
-        IDictionary<TKey, TValue> Data { get; }
-
-
         /*********
         ** Public methods
         *********/
-        /// <summary>Get whether the asset name being loaded matches a given name after normalisation.</summary>
-        /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
-        bool IsAssetName(string path);
-
         /// <summary>Add or replace an entry in the dictionary.</summary>
         /// <param name="key">The entry key.</param>
         /// <param name="value">The entry value.</param>
@@ -39,10 +22,5 @@ namespace StardewModdingAPI
         /// <summary>Dynamically replace values in the dictionary.</summary>
         /// <param name="replacer">A lambda which takes the current key and value for an entry, and returns the new value.</param>
         void Set(Func<TKey, TValue, TValue> replacer);
-
-        /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
-        /// <param name="value">The new content value.</param>
-        /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
-        void ReplaceWith(IDictionary<TKey, TValue> value);
     }
 }
diff --git a/src/StardewModdingAPI/IContentEventHelperForImage.cs b/src/StardewModdingAPI/IContentEventHelperForImage.cs
index 14bc23a4..1158c868 100644
--- a/src/StardewModdingAPI/IContentEventHelperForImage.cs
+++ b/src/StardewModdingAPI/IContentEventHelperForImage.cs
@@ -5,28 +5,11 @@ using Microsoft.Xna.Framework.Graphics;
 namespace StardewModdingAPI
 {
     /// <summary>Encapsulates access and changes to dictionary content being read from a data file.</summary>
-    public interface IContentEventHelperForImage
+    public interface IContentEventHelperForImage : IContentEventData<Texture2D>
     {
-        /*********
-        ** Accessors
-        *********/
-        /// <summary>The content's locale code, if the content is localised.</summary>
-        string Locale { get; }
-
-        /// <summary>The normalised asset name being read. The format may change between platforms; see <see cref="IsAssetName"/> to compare with a known path.</summary>
-        string AssetName { get; }
-
-        /// <summary>The content data being read.</summary>
-        Texture2D Data { get; }
-
-
         /*********
         ** Public methods
         *********/
-        /// <summary>Get whether the asset name being loaded matches a given name after normalisation.</summary>
-        /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
-        bool IsAssetName(string path);
-
         /// <summary>Overwrite part of the image.</summary>
         /// <param name="source">The image to patch into the content.</param>
         /// <param name="sourceArea">The part of the <paramref name="source"/> to copy (or <c>null</c> to take the whole texture). This must be within the bounds of the <paramref name="source"/> texture.</param>
@@ -36,10 +19,5 @@ namespace StardewModdingAPI
         /// <exception cref="ArgumentOutOfRangeException">The <paramref name="targetArea"/> is outside the bounds of the spritesheet.</exception>
         /// <exception cref="InvalidOperationException">The content being read isn't an image.</exception>
         void PatchImage(Texture2D source, Rectangle? sourceArea = null, Rectangle? targetArea = null, PatchMode patchMode = PatchMode.Replace);
-
-        /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
-        /// <param name="value">The new content value.</param>
-        /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
-        void ReplaceWith(Texture2D value);
     }
 }
diff --git a/src/StardewModdingAPI/StardewModdingAPI.csproj b/src/StardewModdingAPI/StardewModdingAPI.csproj
index 478d1af0..445f6f37 100644
--- a/src/StardewModdingAPI/StardewModdingAPI.csproj
+++ b/src/StardewModdingAPI/StardewModdingAPI.csproj
@@ -168,6 +168,7 @@
     <Compile Include="IContentEventHelper.cs" />
     <Compile Include="IContentEventHelperForDictionary.cs" />
     <Compile Include="IContentEventHelperForImage.cs" />
+    <Compile Include="IContentEventData.cs" />
     <Compile Include="IModRegistry.cs" />
     <Compile Include="Events\LocationEvents.cs" />
     <Compile Include="Events\MenuEvents.cs" />
-- 
cgit 


From e3522edddd0636116bd4772b4e4dbfce9c7c0f8d Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Fri, 10 Mar 2017 12:00:11 -0500
Subject: extend base content helper to support null content (#173)

---
 .../Framework/Content/ContentEventBaseHelper.cs    |  98 ------------------
 .../Framework/Content/ContentEventData.cs          | 111 +++++++++++++++++++++
 .../Framework/Content/ContentEventHelper.cs        |   2 +-
 .../Content/ContentEventHelperForDictionary.cs     |   2 +-
 .../Content/ContentEventHelperForImage.cs          |   2 +-
 src/StardewModdingAPI/IContentEventData.cs         |   3 +
 src/StardewModdingAPI/StardewModdingAPI.csproj     |   4 +-
 7 files changed, 119 insertions(+), 103 deletions(-)
 delete mode 100644 src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
 create mode 100644 src/StardewModdingAPI/Framework/Content/ContentEventData.cs

(limited to 'src/StardewModdingAPI/Framework/Content')

diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs b/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
deleted file mode 100644
index a89fe337..00000000
--- a/src/StardewModdingAPI/Framework/Content/ContentEventBaseHelper.cs
+++ /dev/null
@@ -1,98 +0,0 @@
-using System;
-using System.Collections.Generic;
-using Microsoft.Xna.Framework.Graphics;
-
-namespace StardewModdingAPI.Framework.Content
-{
-    /// <summary>Base implementation for a content helper which encapsulates access and changes to content being read from a data file.</summary>
-    /// <typeparam name="TValue">The interface value type.</typeparam>
-    internal class ContentEventBaseHelper<TValue> : EventArgs, IContentEventData<TValue>
-    {
-        /*********
-        ** Properties
-        *********/
-        /// <summary>Normalises an asset key to match the cache key.</summary>
-        protected readonly Func<string, string> GetNormalisedPath;
-
-
-        /*********
-        ** Accessors
-        *********/
-        /// <summary>The content's locale code, if the content is localised.</summary>
-        public string Locale { get; }
-
-        /// <summary>The normalised asset name being read. The format may change between platforms; see <see cref="IsAssetName"/> to compare with a known path.</summary>
-        public string AssetName { get; }
-
-        /// <summary>The content data being read.</summary>
-        public TValue Data { get; protected set; }
-
-
-        /*********
-        ** Public methods
-        *********/
-        /// <summary>Construct an instance.</summary>
-        /// <param name="locale">The content's locale code, if the content is localised.</param>
-        /// <param name="assetName">The normalised asset name being read.</param>
-        /// <param name="data">The content data being read.</param>
-        /// <param name="getNormalisedPath">Normalises an asset key to match the cache key.</param>
-        public ContentEventBaseHelper(string locale, string assetName, TValue data, Func<string, string> getNormalisedPath)
-        {
-            this.Locale = locale;
-            this.AssetName = assetName;
-            this.Data = data;
-            this.GetNormalisedPath = getNormalisedPath;
-        }
-
-        /// <summary>Get whether the asset name being loaded matches a given name after normalisation.</summary>
-        /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
-        public bool IsAssetName(string path)
-        {
-            path = this.GetNormalisedPath(path);
-            return this.AssetName.Equals(path, StringComparison.InvariantCultureIgnoreCase);
-        }
-
-        /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
-        /// <param name="value">The new content value.</param>
-        /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
-        /// <exception cref="InvalidCastException">The <paramref name="value"/>'s type is not compatible with the loaded asset's type.</exception>
-        public void ReplaceWith(TValue value)
-        {
-            if (value == null)
-                throw new ArgumentNullException(nameof(value), "Can't set a loaded asset to a null value.");
-            if (!this.Data.GetType().IsInstanceOfType(value))
-                throw new InvalidCastException($"Can't replace loaded asset of type {this.GetFriendlyTypeName(this.Data.GetType())} with value of type {this.GetFriendlyTypeName(value.GetType())}. The new type must be compatible to prevent game errors.");
-
-            this.Data = value;
-        }
-
-
-        /*********
-        ** Protected methods
-        *********/
-        /// <summary>Get a human-readable type name.</summary>
-        /// <param name="type">The type to name.</param>
-        protected string GetFriendlyTypeName(Type type)
-        {
-            // dictionary
-            if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Dictionary<,>))
-            {
-                Type[] genericArgs = type.GetGenericArguments();
-                return $"Dictionary<{this.GetFriendlyTypeName(genericArgs[0])}, {this.GetFriendlyTypeName(genericArgs[1])}>";
-            }
-
-            // texture
-            if (type == typeof(Texture2D))
-                return type.Name;
-
-            // native type
-            if (type == typeof(int))
-                return "int";
-            if (type == typeof(string))
-                return "string";
-
-            // default
-            return type.FullName;
-        }
-    }
-}
diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventData.cs b/src/StardewModdingAPI/Framework/Content/ContentEventData.cs
new file mode 100644
index 00000000..1a1779d4
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventData.cs
@@ -0,0 +1,111 @@
+using System;
+using System.Collections.Generic;
+using Microsoft.Xna.Framework.Graphics;
+
+namespace StardewModdingAPI.Framework.Content
+{
+    /// <summary>Base implementation for a content helper which encapsulates access and changes to content being read from a data file.</summary>
+    /// <typeparam name="TValue">The interface value type.</typeparam>
+    internal class ContentEventData<TValue> : EventArgs, IContentEventData<TValue>
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>Normalises an asset key to match the cache key.</summary>
+        protected readonly Func<string, string> GetNormalisedPath;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The content's locale code, if the content is localised.</summary>
+        public string Locale { get; }
+
+        /// <summary>The normalised asset name being read. The format may change between platforms; see <see cref="IsAssetName"/> to compare with a known path.</summary>
+        public string AssetName { get; }
+
+        /// <summary>The content data being read.</summary>
+        public TValue Data { get; protected set; }
+
+        /// <summary>The content data type.</summary>
+        public Type DataType { get; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="locale">The content's locale code, if the content is localised.</param>
+        /// <param name="assetName">The normalised asset name being read.</param>
+        /// <param name="data">The content data being read.</param>
+        /// <param name="getNormalisedPath">Normalises an asset key to match the cache key.</param>
+        public ContentEventData(string locale, string assetName, TValue data, Func<string, string> getNormalisedPath)
+            : this(locale, assetName, data, data.GetType(), getNormalisedPath) { }
+
+        /// <summary>Construct an instance.</summary>
+        /// <param name="locale">The content's locale code, if the content is localised.</param>
+        /// <param name="assetName">The normalised asset name being read.</param>
+        /// <param name="data">The content data being read.</param>
+        /// <param name="dataType">The content data type being read.</param>
+        /// <param name="getNormalisedPath">Normalises an asset key to match the cache key.</param>
+        public ContentEventData(string locale, string assetName, TValue data, Type dataType, Func<string, string> getNormalisedPath)
+        {
+            this.Locale = locale;
+            this.AssetName = assetName;
+            this.Data = data;
+            this.DataType = dataType;
+            this.GetNormalisedPath = getNormalisedPath;
+        }
+
+        /// <summary>Get whether the asset name being loaded matches a given name after normalisation.</summary>
+        /// <param name="path">The expected asset path, relative to the game's content folder and without the .xnb extension or locale suffix (like 'Data\ObjectInformation').</param>
+        public bool IsAssetName(string path)
+        {
+            path = this.GetNormalisedPath(path);
+            return this.AssetName.Equals(path, StringComparison.InvariantCultureIgnoreCase);
+        }
+
+        /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
+        /// <param name="value">The new content value.</param>
+        /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
+        /// <exception cref="InvalidCastException">The <paramref name="value"/>'s type is not compatible with the loaded asset's type.</exception>
+        public void ReplaceWith(TValue value)
+        {
+            if (value == null)
+                throw new ArgumentNullException(nameof(value), "Can't set a loaded asset to a null value.");
+            if (!this.DataType.IsInstanceOfType(value))
+                throw new InvalidCastException($"Can't replace loaded asset of type {this.GetFriendlyTypeName(this.DataType)} with value of type {this.GetFriendlyTypeName(value.GetType())}. The new type must be compatible to prevent game errors.");
+
+            this.Data = value;
+        }
+
+
+        /*********
+        ** Protected methods
+        *********/
+        /// <summary>Get a human-readable type name.</summary>
+        /// <param name="type">The type to name.</param>
+        protected string GetFriendlyTypeName(Type type)
+        {
+            // dictionary
+            if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Dictionary<,>))
+            {
+                Type[] genericArgs = type.GetGenericArguments();
+                return $"Dictionary<{this.GetFriendlyTypeName(genericArgs[0])}, {this.GetFriendlyTypeName(genericArgs[1])}>";
+            }
+
+            // texture
+            if (type == typeof(Texture2D))
+                return type.Name;
+
+            // native type
+            if (type == typeof(int))
+                return "int";
+            if (type == typeof(string))
+                return "string";
+
+            // default
+            return type.FullName;
+        }
+    }
+}
diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventHelper.cs b/src/StardewModdingAPI/Framework/Content/ContentEventHelper.cs
index 26292cab..9bf1ea17 100644
--- a/src/StardewModdingAPI/Framework/Content/ContentEventHelper.cs
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventHelper.cs
@@ -5,7 +5,7 @@ using Microsoft.Xna.Framework.Graphics;
 namespace StardewModdingAPI.Framework.Content
 {
     /// <summary>Encapsulates access and changes to content being read from a data file.</summary>
-    internal class ContentEventHelper : ContentEventBaseHelper<object>, IContentEventHelper
+    internal class ContentEventHelper : ContentEventData<object>, IContentEventHelper
     {
         /*********
         ** Public methods
diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
index 8a8a4845..26f059e4 100644
--- a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForDictionary.cs
@@ -5,7 +5,7 @@ using System.Linq;
 namespace StardewModdingAPI.Framework.Content
 {
     /// <summary>Encapsulates access and changes to dictionary content being read from a data file.</summary>
-    internal class ContentEventHelperForDictionary<TKey, TValue> : ContentEventBaseHelper<IDictionary<TKey, TValue>>, IContentEventHelperForDictionary<TKey, TValue>
+    internal class ContentEventHelperForDictionary<TKey, TValue> : ContentEventData<IDictionary<TKey, TValue>>, IContentEventHelperForDictionary<TKey, TValue>
     {
         /*********
         ** Public methods
diff --git a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForImage.cs b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForImage.cs
index 23760f0f..da30590b 100644
--- a/src/StardewModdingAPI/Framework/Content/ContentEventHelperForImage.cs
+++ b/src/StardewModdingAPI/Framework/Content/ContentEventHelperForImage.cs
@@ -5,7 +5,7 @@ using Microsoft.Xna.Framework.Graphics;
 namespace StardewModdingAPI.Framework.Content
 {
     /// <summary>Encapsulates access and changes to dictionary content being read from a data file.</summary>
-    internal class ContentEventHelperForImage : ContentEventBaseHelper<Texture2D>, IContentEventHelperForImage
+    internal class ContentEventHelperForImage : ContentEventData<Texture2D>, IContentEventHelperForImage
     {
         /*********
         ** Public methods
diff --git a/src/StardewModdingAPI/IContentEventData.cs b/src/StardewModdingAPI/IContentEventData.cs
index a21861d2..7e2d4df1 100644
--- a/src/StardewModdingAPI/IContentEventData.cs
+++ b/src/StardewModdingAPI/IContentEventData.cs
@@ -18,6 +18,9 @@ namespace StardewModdingAPI
         /// <summary>The content data being read.</summary>
         TValue Data { get; }
 
+        /// <summary>The content data type.</summary>
+        Type DataType { get; }
+
 
         /*********
         ** Public methods
diff --git a/src/StardewModdingAPI/StardewModdingAPI.csproj b/src/StardewModdingAPI/StardewModdingAPI.csproj
index 445f6f37..ab808948 100644
--- a/src/StardewModdingAPI/StardewModdingAPI.csproj
+++ b/src/StardewModdingAPI/StardewModdingAPI.csproj
@@ -150,7 +150,7 @@
     <Compile Include="Framework\AssemblyDefinitionResolver.cs" />
     <Compile Include="Framework\AssemblyParseResult.cs" />
     <Compile Include="Framework\CommandManager.cs" />
-    <Compile Include="Framework\Content\ContentEventBaseHelper.cs" />
+    <Compile Include="Framework\Content\ContentEventData.cs" />
     <Compile Include="Framework\Content\ContentEventHelper.cs" />
     <Compile Include="Framework\Content\ContentEventHelperForDictionary.cs" />
     <Compile Include="Framework\Content\ContentEventHelperForImage.cs" />
@@ -165,10 +165,10 @@
     <Compile Include="Framework\Serialisation\SelectiveStringEnumConverter.cs" />
     <Compile Include="Framework\Serialisation\SemanticVersionConverter.cs" />
     <Compile Include="ICommandHelper.cs" />
+    <Compile Include="IContentEventData.cs" />
     <Compile Include="IContentEventHelper.cs" />
     <Compile Include="IContentEventHelperForDictionary.cs" />
     <Compile Include="IContentEventHelperForImage.cs" />
-    <Compile Include="IContentEventData.cs" />
     <Compile Include="IModRegistry.cs" />
     <Compile Include="Events\LocationEvents.cs" />
     <Compile Include="Events\MenuEvents.cs" />
-- 
cgit