Add more cap setter utilities.

src/Directory.Build.props

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <!--change these in each release-->
     <VersionPrefix>4.0.0.0</VersionPrefix>
-    <VersionSuffix>alpha.18</VersionSuffix>
+    <VersionSuffix>alpha.19</VersionSuffix>
     
     <!--keep it the same until major # changes-->
     <AssemblyVersion>4.0.0.0</AssemblyVersion>

src/NTwain/Caps/CapWriter.cs

@@ -1,10 +1,10 @@
 using NTwain.Data;
 using System.Collections.Generic;
 
-namespace NTwain.Caps
+namespace NTwain.Caps;
+
+public class CapWriter<TValue> : CapReader<TValue> where TValue : struct
 {
-  public class CapWriter<TValue> : CapReader<TValue> where TValue : struct
-  {
     public CapWriter(TwainAppSession twain, CAP cap, float introducedVersion = 1)
       : base(twain, cap, introducedVersion)
     {
@@ -17,7 +17,7 @@ namespace NTwain.Caps
     /// <returns></returns>
     public STS Set(TValue value)
     {
-      return LastSTS = _twain.SetCap(Cap, value);
+        return LastSTS = _twain.SetCap(Cap, value);
     }
 
     /// <summary>
@@ -27,8 +27,7 @@ namespace NTwain.Caps
     /// <returns></returns>
     public STS Set(IList<TValue> values)
     {
-      var twcap = ValueWriter.CreateArrayCap(Cap, _twain, values);
+        return LastSTS = _twain.SetCap(Cap, values);
-      return LastSTS = _twain.SetCap(ref twcap);
     }
 
     /// <summary>
@@ -38,8 +37,7 @@ namespace NTwain.Caps
     /// <returns></returns>
     public STS Set(Enumeration<TValue> values)
     {
-      var twcap = ValueWriter.CreateEnumCap(Cap, _twain, values);
+        return LastSTS = _twain.SetCap(Cap, values);
-      return LastSTS = _twain.SetCap(ref twcap);
     }
 
     /// <summary>
@@ -49,8 +47,7 @@ namespace NTwain.Caps
     /// <returns></returns>
     public STS Set(Range<TValue> values)
     {
-      var twcap = ValueWriter.CreateRangeCap(Cap, _twain, values);
+        return LastSTS = _twain.SetCap(Cap, values);
-      return LastSTS = _twain.SetCap(ref twcap);
     }
 
 
@@ -61,8 +58,7 @@ namespace NTwain.Caps
     /// <returns></returns>
     public STS SetConstraint(TValue value)
     {
-      var twcap = ValueWriter.CreateOneValueCap(Cap, _twain, value);
+        return LastSTS = _twain.SetConstraint(Cap, value);
-      return LastSTS = _twain.SetConstraint(ref twcap);
     }
 
     /// <summary>
@@ -72,8 +68,7 @@ namespace NTwain.Caps
     /// <returns></returns>
     public STS SetConstraint(IList<TValue> values)
     {
-      var twcap = ValueWriter.CreateArrayCap(Cap, _twain, values);
+        return LastSTS = _twain.SetConstraint(Cap, values);
-      return LastSTS = _twain.SetConstraint(ref twcap);
     }
 
     /// <summary>
@@ -83,8 +78,7 @@ namespace NTwain.Caps
     /// <returns></returns>
     public STS SetConstraint(Enumeration<TValue> values)
     {
-      var twcap = ValueWriter.CreateEnumCap(Cap, _twain, values);
+        return LastSTS = _twain.SetConstraint(Cap, values);
-      return LastSTS = _twain.SetConstraint(ref twcap);
     }
 
     /// <summary>
@@ -94,19 +88,17 @@ namespace NTwain.Caps
     /// <returns></returns>
     public STS SetConstraint(Range<TValue> values)
     {
-      var twcap = ValueWriter.CreateRangeCap(Cap, _twain, values);
+        return LastSTS = _twain.SetConstraint(Cap, values);
-      return LastSTS = _twain.SetConstraint(ref twcap);
     }
 
     /// <summary>
     /// Resets this cap to power-on default.
     /// </summary>
+    /// <param name="value">The current value after reset.</param>
     /// <returns></returns>
-    public STS Reset()
+    public STS Reset(out List<TValue> value)
     {
-      LastSTS = _twain.ResetCap(Cap, out TW_CAPABILITY twcap);
+        LastSTS = _twain.ResetCap(Cap, out value);
-      twcap.Free(_twain);
+        return LastSTS;
-      return LastSTS;
     }
-  }
 }

src/NTwain/TwainAppSession.Caps.cs

@@ -71,7 +71,7 @@ namespace NTwain
         /// <returns></returns>
         public STS GetCapCurrent<TValue>(CAP cap, out List<TValue> value) where TValue : struct
         {
-            value = new List<TValue>();
+            value = [];
             var sts = GetCapCurrent(cap, out TW_CAPABILITY twcap);
             if (sts.RC == TWRC.SUCCESS)
             {
@@ -422,8 +422,7 @@ namespace NTwain
         }
 
         /// <summary>
-        /// A simpler cap value setter for common one-value scenarios
+        /// A simpler cap value setter for one-value type.
-        /// that's easier to use. Not for other container type sets.
         /// </summary>
         /// <typeparam name="TValue"></typeparam>
         /// <param name="cap"></param>
@@ -435,6 +434,45 @@ namespace NTwain
             return SetCap(ref twcap);
         }
 
+        /// <summary>
+        /// A cap value setter for enumeration container type.
+        /// </summary>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="cap"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
+        public STS SetCap<TValue>(CAP cap, Enumeration<TValue> value) where TValue : struct
+        {
+            var twcap = ValueWriter.CreateEnumCap(cap, this, value);
+            return SetCap(ref twcap);
+        }
+
+        /// <summary>
+        /// A cap value setter for range container type.
+        /// </summary>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="cap"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
+        public STS SetCap<TValue>(CAP cap, Range<TValue> value) where TValue : struct
+        {
+            var twcap = ValueWriter.CreateRangeCap(cap, this, value);
+            return SetCap(ref twcap);
+        }
+
+        /// <summary>
+        /// A cap value setter for array container type.
+        /// </summary>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="cap"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
+        public STS SetCap<TValue>(CAP cap, IList<TValue> value) where TValue : struct
+        {
+            var twcap = ValueWriter.CreateArrayCap(cap, this, value);
+            return SetCap(ref twcap);
+        }
+
         /// <summary>
         /// A cap value setter for all kinds of container types.
         /// </summary>
@@ -442,36 +480,25 @@ namespace NTwain
         /// <param name="cap"></param>
         /// <param name="value"></param>
         /// <returns></returns>
+        /// <exception cref="ArgumentException"></exception>
         public STS SetCap<TValue>(CAP cap, ValueContainer<TValue> value) where TValue : struct
         {
             switch (value.ContainerType)
             {
                 case TWON.ONEVALUE:
-                    {
+                    return SetCap(cap, value.OneValue);
-                        var twcap = ValueWriter.CreateOneValueCap(cap, this, value.OneValue);
-                        return SetCap(ref twcap);
-                    }
                 case TWON.ENUMERATION:
-                    {
+                    if (value.EnumValue == null)
-                        if (value.EnumValue == null)
+                        throw new ArgumentException("EnumValue cannot be null when ContainerType is ENUMERATION.", nameof(value));
-                            throw new ArgumentException("EnumValue cannot be null when ContainerType is ENUMERATION.", nameof(value));
+                    return SetCap(cap, value.EnumValue);
-                        var twcap = ValueWriter.CreateEnumCap(cap, this, value.EnumValue);
-                        return SetCap(ref twcap);
-                    }
                 case TWON.RANGE:
-                    {
+                    if (value.RangeValue == null)
-                        if (value.RangeValue == null)
+                        throw new ArgumentException("RangeValue cannot be null when ContainerType is RANGE.", nameof(value));
-                            throw new ArgumentException("RangeValue cannot be null when ContainerType is RANGE.", nameof(value));
+                    return SetCap(cap, value.RangeValue);
-                        var twcap = ValueWriter.CreateRangeCap(cap, this, value.RangeValue);
-                        return SetCap(ref twcap);
-                    }
                 case TWON.ARRAY:
-                    {
+                    if (value.ArrayValue == null)
-                        if (value.ArrayValue == null)
+                        throw new ArgumentException("ArrayValue cannot be null when ContainerType is ARRAY.", nameof(value));
-                            throw new ArgumentException("ArrayValue cannot be null when ContainerType is ARRAY.", nameof(value));
+                    return SetCap(cap, value.ArrayValue);
-                        var twcap = ValueWriter.CreateArrayCap(cap, this, value.ArrayValue);
-                        return SetCap(ref twcap);
-                    }
                 default:
                     throw new ArgumentException("Unsupported ContainerType for setting CAP.", nameof(value));
             }
@@ -493,6 +520,90 @@ namespace NTwain
             return WrapInSTS(rc);
         }
 
+
+        /// <summary>
+        /// A simpler cap constraint setter for one-value type.
+        /// </summary>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="cap"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
+        public STS SetConstraint<TValue>(CAP cap, TValue value) where TValue : struct
+        {
+            var twcap = ValueWriter.CreateOneValueCap(cap, this, value);
+            return SetConstraint(ref twcap);
+        }
+
+        /// <summary>
+        /// A cap constraint setter for enumeration container type.
+        /// </summary>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="cap"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
+        public STS SetConstraint<TValue>(CAP cap, Enumeration<TValue> value) where TValue : struct
+        {
+            var twcap = ValueWriter.CreateEnumCap(cap, this, value);
+            return SetConstraint(ref twcap);
+        }
+
+        /// <summary>
+        /// A cap constraint setter for range container type.
+        /// </summary>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="cap"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
+        public STS SetConstraint<TValue>(CAP cap, Range<TValue> value) where TValue : struct
+        {
+            var twcap = ValueWriter.CreateRangeCap(cap, this, value);
+            return SetConstraint(ref twcap);
+        }
+
+        /// <summary>
+        /// A cap constraint setter for array container type.
+        /// </summary>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="cap"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
+        public STS SetConstraint<TValue>(CAP cap, IList<TValue> value) where TValue : struct
+        {
+            var twcap = ValueWriter.CreateArrayCap(cap, this, value);
+            return SetConstraint(ref twcap);
+        }
+
+        /// <summary>
+        /// A cap constraint setter for all kinds of container types.
+        /// </summary>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="cap"></param>
+        /// <param name="value"></param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentException"></exception>
+        public STS SetConstraint<TValue>(CAP cap, ValueContainer<TValue> value) where TValue : struct
+        {
+            switch (value.ContainerType)
+            {
+                case TWON.ONEVALUE:
+                    return SetConstraint(cap, value.OneValue);
+                case TWON.ENUMERATION:
+                    if (value.EnumValue == null)
+                        throw new ArgumentException("EnumValue cannot be null when ContainerType is ENUMERATION.", nameof(value));
+                    return SetConstraint(cap, value.EnumValue);
+                case TWON.RANGE:
+                    if (value.RangeValue == null)
+                        throw new ArgumentException("RangeValue cannot be null when ContainerType is RANGE.", nameof(value));
+                    return SetConstraint(cap, value.RangeValue);
+                case TWON.ARRAY:
+                    if (value.ArrayValue == null)
+                        throw new ArgumentException("ArrayValue cannot be null when ContainerType is ARRAY.", nameof(value));
+                    return SetConstraint(cap, value.ArrayValue);
+                default:
+                    throw new ArgumentException("Unsupported ContainerType for setting CAP constraint.", nameof(value));
+            }
+        }
+
         /// <summary>
         /// Resets a CAP's current value to power-on default.
         /// Caller will need to manually read and free the memory.
@@ -520,30 +631,31 @@ namespace NTwain
         /// <param name="cap"></param>
         /// <param name="value"></param>
         /// <returns></returns>
-        public STS ResetCap<TValue>(CAP cap, out TValue value) where TValue : struct
+        public STS ResetCap<TValue>(CAP cap, out List<TValue> value) where TValue : struct
         {
-            value = default;
+            value = [];
             var sts = ResetCap(cap, out TW_CAPABILITY twcap);
+
             if (sts.RC == TWRC.SUCCESS)
             {
                 switch (twcap.ConType)
                 {
                     case TWON.ONEVALUE:
-                        value = twcap.ReadOneValue<TValue>(this);
+                        value.Add(twcap.ReadOneValue<TValue>(this));
                         break;
                     case TWON.ENUMERATION:
                         var twenum = twcap.ReadEnumeration<TValue>(this);
                         if (twenum.Items != null && twenum.CurrentIndex < twenum.Items.Length)
                         {
-                            value = twenum.Items[twenum.CurrentIndex];
+                            value.Add(twenum.Items[twenum.CurrentIndex]);
                         }
                         break;
                     case TWON.RANGE:
-                        value = twcap.ReadRange<TValue>(this).CurrentValue;
+                        value.Add(twcap.ReadRange<TValue>(this).CurrentValue);
                         break;
                     case TWON.ARRAY:
                         var twarr = twcap.ReadArray<TValue>(this);
-                        if (twarr != null && twarr.Count > 0) value = twarr[0];
+                        if (twarr != null && twarr.Count > 0) value.AddRange(twarr);
                         break;
                     default:
                         twcap.Free(this); break;