Release v3.0..0-rc.5

Author: rabanti-github

Changelog.md

@@ -3,7 +3,7 @@
 ## v3.0.0-rc.5
 
 ---
-Release Date: **22.12.2025**
+Release Date: **04.01.2026**
 
 - Added explicit operator for Address to convert from string to Address (string can be cast to address explicitly)
 - Added implicit operator for Range to convert from string to Range (string can be cast to range implicitly)
@@ -13,7 +13,10 @@ Release Date: **22.12.2025**
   - ThemeColor (Color, defined by theme elements)
   - SystemColor (Color, defined by system colors)
   - AutoColor (automatic color, no value / dummy class)
+- Changed the type of `Font.ColorValue` from string to Color (can be sRGB/ARGB, Indexed, Theme, System or Auto)
+- Removed the property `Font.ColorTheme`, since only relevant for theme colors. The value is now handled by `Font.ColorValue`, in case of a ThemeColor
 - Re-implementation of the Fill class to use the new Color class for color representation of the foreground and background colors (indexed property removed)
+- Removed the property `Fill.IndexedColor`, since only relevant for Indexed colors. The value is now handled by `Fill.ForegroundColor` or `Fill.BackgroundColor`, in case of a IndexedColor
 - Added implicit operator for Fill to create a fill color by a string (RGB or ARGB value)
 - Added implicit operator for Fill to create a fill color by an integer (indexed color value)
 - Changed internal handling of text cell values

MigrationGuide.md

@@ -125,14 +125,23 @@ The following guide lists all necessary changes, as well as changed behaviors of
 - The property `Row` is now read-only (immutable). To change the property, a new Address object has to be created
 - The property `Column` is now read-only (immutable). To change the property, a new Address object has to be created
 - The property `Type` is now read-only (immutable). To change the property, a new Address object has to be created
+- An Address object can now be de defined by an explicit cast (implicit casting was not realized due to potential issues with object comparison). Example:
+```cs
+sting addressString = "A15";
+Address address = (Address)addressString;
+```
 
 ---
 
 ### Range (struct)
 
 - The property `StartAddress` is now read-only (immutable). To change the property, a new Range object has to be created
 - The property `EndAddress` is now read-only (immutable). To change the property, a new Range object has to be created
- 
+- A Range object can now be de defined by an implicit cast using a string. Example:
+```cs
+Range range = "A2:D15";
+```
+
 ---
 
 ### Styles 
@@ -197,7 +206,37 @@ ApplicationDefined, ANSI, Default, Symbols, Mac, ShiftJIS, Hangul, Johab, GBK, B
 // ApplicableDefined is usually ignored, and Default may be used instead
 ```
 
-- The property `Font.ColorScheme` was changed from type `int` to the enum `Theme.ColorSchemeElement`. The value has to be replaced by one of the available values (See **Theme section** ). The initialization default value is `Theme.ColorSchemeElement.light1`.
+- The property `Font.ColorValue` was changed from type `string ` to the new `Color` class (namespace `NanoXLSX.Colors`). The new Color class can represent an RGB, ARGB, system, theme or indexed color. However, there are also implicit conversions. See the Color class documentation for more details. Usage examples:
+```cs
+Font font = new Font();
+font.ColorValue = Color.CreateIndexed(IndexedColor.Value.Yellow);
+
+// Different examples with other color types
+
+Font font2 = new Font();
+font.ColorValue = Color.CreateRgb("FF00FF00"); // ARGB
+
+Font font3 = new Font();
+font3.ColorValue = Color.CreateTheme(Theme.ColorSchemeElement.Accent1, 0.5f); // Theme color with tint
+
+// Implicit creation of specific color from a string (ARGB):
+Font font4 = new Font();
+font4.ColorValue = "FF00FF00"; // Implicit conversion to SrgbColor
+
+// Implicit creation of font from an int (indexed color):
+Font font5 = new Font();
+Font font5.ColorValue = IndexedColor.Value.Black; // Implicit conversion to IndexedColor as background
+
+// Implicit creation of specific color from an int (color index):
+Font font6 = new Font();
+font6.ColorValue = 63; // Implicit conversion to IndexedColor
+
+// Implicit creation of specific color from an enum value (color index):
+Font font7 = new Font();
+font7.ColorValue = IndexedColor.Value.Magenta; // Implicit conversion to IndexedColor enum value
+```
+
+- The property `Font.ColorTheme` was completely removed. This value is only relevant, if the property `Font.ColorValue` is of the type `ThemeColor`. All references are to be removed.
 - The property `Font.VerticalAlign` was changed from type `Font.VerticalAlignValue` to the enum `Font.VerticalTextAlignValue`. Only the enum name has to be changed (see below):
 - The enum `Font.VerticalAlignValue` was renamed to `Font.VerticalTextAlignValue`. The available values remain unchanged
 
@@ -262,7 +301,7 @@ Fill was completely overhauled in version 3.0.0, to support more flexible color
 - The static method `Fill.ValidateColr(string,bool, bool)` was moved to the utils class `Validators.ValidateColr(string,bool, bool)` in namespace `NanoXLSX.Utils`. The class has to be changed in the code, but the method signature remains unchanged.
 - The property `Fill.BackgroundColor` was changed from type `string` to the new `Color` class (namespace `NanoXLSX.Colors`). The new Color class can represent an RGB, ARGB, system, theme or indexed color. See the Color class documentation for more details.
 - The property `Fill.ForegroundColor` was changed from type `string` to the new `Color` class (namespace `NanoXLSX.Colors`). The new Color class can represent an RGB, ARGB, system, theme or indexed color. See the Color class documentation for more details.
-- The property `IndexedColor` was removed and is now part of the new `Color` class, applied to `BackgroundColor` and `ForegroundColor`. In the `Color` class, there is a property `IndexedColor` that holds an object of the type `IndexedColor` (namespace `NanoXLSX.Themes`). The original `int` value has to be replaced by one of the available enum values in the class `IndexedColor`. Usage example:
+- The property `IndexedColor` was removed and is now part of the new `Color` class, applied to `BackgroundColor` and `ForegroundColor`. In the `Color` class, there is a property `IndexedColor` that holds an object of the type `IndexedColor` (namespace `NanoXLSX.Themes`). The original `int` value has to be replaced by one of the available enum values in the class `IndexedColor`. However, there are also implicit conversions. See the Color class documentation for more details. Usage examples:
 
 ```csharp
 Fill fill = new Fill();
@@ -278,21 +317,21 @@ fill3.ForegroundColor = Color.CreateTheme(Theme.ColorSchemeElement.Accent1, 0.5f
 // Implicit creation of fill from a string (ARGB):
 Fill fill4 = "FF00FF00"; // Implicit conversion to SrgbColor as foreground
 
-// Implicit creation of fill from a int (indexed color):
+// Implicit creation of fill from an int (indexed color):
 Fill fill5 = IndexedColor.Value.Red2; // Implicit conversion to IndexedColor as foreground
 
-// Implicit creation of fill from a int (indexed color):
-Fill fill6 = 64; // Implicit conversion to IndexedColor as foreground, ising the index number
+// Implicit creation of fill from an int (indexed color):
+Fill fill6 = 64; // Implicit conversion to IndexedColor as foreground, using the index number
 
 // Implicit creation of specific color from a string (ARGB):
 Fill fill7 = new Fill();
 fill7.ForegroundColor = "FF00FF00"; // Implicit conversion to SrgbColor
 
-// Implicit creation of fill from a int (indexed color):
+// Implicit creation of fill from an int (indexed color):
 Fill fill8 = new Fill();
 Fill fill8.BackgroundColor = IndexedColor.Value.Black; // Implicit conversion to IndexedColor as background
 
-// Implicit creation of specific color from a int (color index):
+// Implicit creation of specific color from an int (color index):
 Fill fill9 = new Fill();
 fill9.BackgroundColor = 63; // Implicit conversion to IndexedColor
 ```

NanoXLSX.Core/Changelog.md

@@ -3,9 +3,12 @@
 ## v3.0.0-rc.3
 
 ---
-Release Date: **11.12.2025**
+Release Date: **04.01.2026**
 
 - Internal change of structured text handling
+- Formal change of the `Color` and `ThemeColor` classes
+- Removed the property `ColorTheme` from the `Font` class
+- Changed the type of the property `ColorVlaue` of the Font class from `string` to `Color` (namespace `NanoXLES.Colors`)
 
 
 ## v3.0.0-rc.2

NanoXLSX.Core/Colors/Color.cs

@@ -72,9 +72,10 @@ public enum ColorType
         public SystemColor SystemColor { get; private set; }
 
         /// <summary>
-        /// Optional tint value for colors (-1.0 to 1.0)
+        /// Optional tint value for colors (-1.0 to 1.0), mainly for theme colors
         /// Positive values lighten, negative values darken
         /// </summary>
+        /// \remark <remarks>Although tint is generally specified for all color types, according to the OOXML specifications, it seems only to have an effect on colors of the type <see cref="ThemeColor"/>. Therefore, the value is also not written on any color except ThemeColor</remarks>
         public double? Tint { get; set; }
 
         /// <summary>
@@ -340,6 +341,29 @@ public static implicit operator Color(IndexedColor.Value colorIndex)
             return CreateIndexed(colorIndex);
         }
 
+        /// <summary>
+        /// String representation od a Color instance
+        /// </summary>
+        /// <returns>String value</returns>
+        public override string ToString()
+        {
+            switch (Type)
+            {
+                case ColorType.Rgb:
+                    return "RGBColor:" + RgbColor.StringValue;
+                case ColorType.Indexed:
+                    return "IndexedColor:" + IndexedColor.StringValue;
+                case ColorType.Theme:
+                    return "ThemeColor:" + ThemeColor.StringValue;
+                case ColorType.System:
+                    return "SystemColor:" + SystemColor.StringValue;
+                case ColorType.Auto:
+                    return "Auto-Color";
+                default:
+                    return "Undefined Color";
+            }
+        }
+
 
         /// <summary>
         /// Determines whether the specified object is equal to the current object

NanoXLSX.Core/Colors/ThemeColor.cs

@@ -22,7 +22,7 @@ public class ThemeColor : ITypedColor<Theme.ColorSchemeElement>
         public Theme.ColorSchemeElement ColorValue { get; set; }
 
         /// <summary>
-        /// Gets the internal OOXML string value of the enum, defined in <see cref="ColorValue"/>
+        /// Gets the internal, numeric OOXML string value of the enum, defined in <see cref="ColorValue"/>
         /// </summary>
         public string StringValue
         {

NanoXLSX.Core/Styles/Font.cs

@@ -7,6 +7,7 @@
 
 using System.Collections.Generic;
 using System.Text;
+using NanoXLSX.Colors;
 using NanoXLSX.Exceptions;
 using NanoXLSX.Utils;
 using static NanoXLSX.Themes.Theme;
@@ -303,56 +304,21 @@ public enum FontFamilyValue
         /// Gets or sets the char set of the Font
         /// </summary>
         [Append]
-        //TODO: v3> Refactor to enum according to specs
-        // OOXML: Chp.19.2.1.13
         public CharsetValue Charset { get; set; } = CharsetValue.Default;
 
         /// <summary>
-        /// Gets or sets the font color theme, represented by a color scheme
-        /// </summary>
-        [Append]
-        //TODO: v3> Reference to Theming
-        //OOXML: Chp.18.8.3 and 20.1.6.2
-        public ColorSchemeElement ColorTheme
-        {
-            get => colorTheme;
-            set
-            {
-                if (value == null)
-                {
-                    throw new StyleException("A color theme cannot be null");
-                }
-                colorTheme = value;
-            }
-        }
-        /// <summary>
-        /// Gets or sets the color code of the font color. The value is expressed as hex string with the format AARRGGBB. AA (Alpha) is usually FF. If set, the value will be cast to upper case
+        /// Gets or sets the color code of the font color. The value is an instance of <see cref="Color"/>
         /// To omit the color, an empty string can be set. Empty is also default.
         /// </summary>
-        /// <exception cref="StyleException">Throws a StyleException if the passed ARGB value is not valid</exception>
         [Append]
-        public string ColorValue
+        public Color ColorValue
         {
-            get => colorValue;
-            set
-            {
-                Validators.ValidateColor(value, true, true);
-                if (value != null)
-                {
-                    colorValue = ParserUtils.ToUpper(value);
-                }
-                else
-                {
-                    colorValue = value;
-                }
-            }
+            get; set;
         }
         /// <summary>
         ///  Gets or sets the font family (Default is 2 = Swiss)
         /// </summary>
         [Append]
-        //TODO: v3> Refactor to enum according to specs (18.18.94)
-        //OOXML: Chp.18.8.18 and 18.18.94
         public FontFamilyValue Family { get; set; }
         /// <summary>
         /// Gets whether the font is equal to the default font
@@ -367,7 +333,6 @@ public bool IsDefaultFont
             }
         }
 
-
         /// <summary>
         /// Gets or sets the font name (Default is Calibri)
         /// </summary>
@@ -417,13 +382,13 @@ public float Size
         /// <summary>
         /// Default constructor
         /// </summary>
+        /// \remark <remarks>When using the default constructor, an object of type <see cref="Color"/> with the type <see cref="Color.ColorType.None"/> will be created for the property <see cref="Font.ColorValue"/>. To set a font color, the property has to be updated with a new value</remarks>
         public Font()
         {
             size = DefaultFontSize;
             Name = DefaultFontName;
             Family = DefaultFontFamily;
-            ColorTheme = ColorSchemeElement.Light1;
-            ColorValue = string.Empty;
+            ColorValue = Color.CreateNone();// Default is none
             Scheme = DefaultFontScheme;
             VerticalAlign = DefaultVerticalAlign;
         }
@@ -464,7 +429,6 @@ public override string ToString()
             sb.Append("\"Font\": {\n");
             AddPropertyAsJson(sb, "Bold", Bold);
             AddPropertyAsJson(sb, "Charset", Charset);
-            AddPropertyAsJson(sb, "ColorTheme", ColorTheme);
             AddPropertyAsJson(sb, "ColorValue", ColorValue);
             AddPropertyAsJson(sb, "VerticalAlign", VerticalAlign);
             AddPropertyAsJson(sb, "Family", Family);
@@ -489,7 +453,6 @@ public override AbstractStyle Copy()
             {
                 Bold = Bold,
                 Charset = Charset,
-                ColorTheme = ColorTheme,
                 ColorValue = ColorValue,
                 VerticalAlign = VerticalAlign,
                 Family = Family,
@@ -517,8 +480,7 @@ public override int GetHashCode()
                 hashCode = hashCode * -1521134295 + size.GetHashCode();
                 hashCode = hashCode * -1521134295 + Bold.GetHashCode();
                 hashCode = hashCode * -1521134295 + Charset.GetHashCode();
-                hashCode = hashCode * -1521134295 + ColorTheme.GetHashCode();
-                hashCode = hashCode * -1521134295 + EqualityComparer<string>.Default.GetHashCode(ColorValue);
+                hashCode = hashCode * -1521134295 + EqualityComparer<Color>.Default.GetHashCode(ColorValue);
                 hashCode = hashCode * -1521134295 + Family.GetHashCode();
                 hashCode = hashCode * -1521134295 + Italic.GetHashCode();
                 hashCode = hashCode * -1521134295 + EqualityComparer<string>.Default.GetHashCode(Name);
@@ -544,7 +506,6 @@ public override bool Equals(object obj)
                    Strike == font.Strike &&
                    Underline == font.Underline &&
                    Charset == font.Charset &&
-                   ColorTheme == font.ColorTheme &&
                    ColorValue == font.ColorValue &&
                    Family == font.Family &&
                    Name == font.Name &&

NanoXLSX.Core/Utils/Validators.cs

@@ -61,7 +61,7 @@ private static string ValidateColorInternal(string hexCode, bool useAlpha, bool
                 {
                     return null;
                 }
-                return "The color expression was null or empty";
+                return "The color expression cannot be null or empty";
             }
 
             int length = useAlpha ? 8 : 6;

NanoXLSX.Reader/Changelog.md

@@ -3,7 +3,7 @@
 ## v3.0.0-rc.3
 
 ---
-Release Date: **21.12.2025**
+Release Date: **04.01.2026**
 
 - Changed handling of colors in the style reader (Fills) to consider:
   - sRGB colors (RGB / ARGB)

NanoXLSX.Reader/Documentation/projectNumber.doxygen

@@ -1 +1 @@
-PROJECT_NUMBER = 3.0.0-rc.2 
+PROJECT_NUMBER = 3.0.0-rc.3