重构字体诊断信息为 LvglFontDiagnostics 结构体

统一字体诊断信息的管理方式，引入 LvglFontDiagnostics 结构体，替换原有的字符串字段，简化了诊断信息的传递与释放接口。各 View 及相关 Helper 方法均改为使用结构化的诊断信息，并统一 ToString 输出格式。提升了代码的可维护性和诊断一致性。

Author: maikebing

src/LVGLSharp.Core/LVGLSharp.Core.csproj

@@ -24,4 +24,8 @@
 	  <ProjectReference Include="..\LVGLSharp.Interop\LVGLSharp.Interop.csproj" />
 	</ItemGroup>
 
+ <ItemGroup>
+   <Folder Include="Drawing\" />
+ </ItemGroup>
+
 </Project>

src/LVGLSharp.Core/LvglFontDiagnostics.cs

@@ -0,0 +1,43 @@
+using SixLabors.Fonts;
+
+namespace LVGLSharp;
+
+public readonly record struct LvglFontDiagnostics(
+    string? ResolvedFontPath,
+    string? DiagnosticSummary,
+    string? GlyphDiagnosticSummary)
+{
+    public string DisplayResolvedFontPath => string.IsNullOrWhiteSpace(ResolvedFontPath) ? "<none>" : ResolvedFontPath;
+
+    public string DisplaySummary => string.IsNullOrWhiteSpace(DiagnosticSummary) ? "<unresolved>" : DiagnosticSummary;
+
+    public string DisplayGlyphSummary => string.IsNullOrWhiteSpace(GlyphDiagnosticSummary) ? "<unresolved>" : GlyphDiagnosticSummary;
+
+    public static LvglFontDiagnostics Empty => default;
+
+    public static LvglFontDiagnostics FromPath(string? resolvedFontPath, string? diagnosticSummary, string? glyphDiagnosticSummary)
+    {
+        return new LvglFontDiagnostics(resolvedFontPath, diagnosticSummary, glyphDiagnosticSummary);
+    }
+
+    public static LvglFontDiagnostics FromFontFamily(FontFamily? fontFamily, IEnumerable<string> candidates, bool enabled)
+    {
+        ArgumentNullException.ThrowIfNull(candidates);
+
+        if (!enabled)
+        {
+            return new LvglFontDiagnostics(null, "ManagedFontDisabled", null);
+        }
+
+        var candidateList = string.Join(", ", candidates.Where(static candidate => !string.IsNullOrWhiteSpace(candidate)));
+        if (fontFamily is null)
+        {
+            return new LvglFontDiagnostics(null, $"ManagedFontEnabled; Family=<none>; Candidates={candidateList}", null);
+        }
+
+        return new LvglFontDiagnostics(
+            fontFamily.Value.Name,
+            $"ManagedFontEnabled; Family={fontFamily.Value.Name}; Candidates={candidateList}",
+            null);
+    }
+}

src/LVGLSharp.Core/LvglManagedFontHelper.cs

@@ -50,6 +50,47 @@ public static bool TryResolveFontFamily(IEnumerable<string> fontFamilyNames, out
         return false;
     }
 
+    /// <summary>
+    /// Initializes managed font state from a resolved font file path.
+    /// </summary>
+    public static LvglManagedFontState InitializeManagedFont(
+        lv_obj_t* root,
+        string? fontPath,
+        float size,
+        float dpi,
+        LvglFontDiagnostics diagnostics,
+        bool enabled)
+    {
+        var fallbackFont = LvglFontHelper.GetEffectiveTextFont(root, lv_part_t.LV_PART_MAIN);
+        var fontManager = TryApplyManagedFont(root, fontPath, size, dpi, fallbackFont, out var font, out var style, enabled);
+        return new LvglManagedFontState(fallbackFont, font, fontManager, diagnostics, style);
+    }
+
+    /// <summary>
+    /// Initializes managed font state from a resolved font family.
+    /// </summary>
+    public static LvglManagedFontState InitializeManagedFont(
+        lv_obj_t* root,
+        FontFamily? fontFamily,
+        IEnumerable<string> fontFamilyNames,
+        float size,
+        float dpi,
+        bool enabled)
+    {
+        var diagnostics = CreateFontDiagnostics(fontFamily, fontFamilyNames, enabled);
+        var fallbackFont = LvglFontHelper.GetEffectiveTextFont(root, lv_part_t.LV_PART_MAIN);
+        var fontManager = TryApplyManagedFont(root, fontFamily, size, dpi, fallbackFont, out var font, out var style, enabled);
+        return new LvglManagedFontState(fallbackFont, font, fontManager, diagnostics, style);
+    }
+
+    /// <summary>
+    /// Creates a shared diagnostics model for managed font family resolution.
+    /// </summary>
+    public static LvglFontDiagnostics CreateFontDiagnostics(FontFamily? fontFamily, IEnumerable<string> fontFamilyNames, bool enabled)
+    {
+        return LvglFontDiagnostics.FromFontFamily(fontFamily, fontFamilyNames, enabled);
+    }
+
     /// <summary>
     /// Applies a managed font from the specified font file path when managed fonts are enabled.
     /// </summary>
@@ -127,4 +168,31 @@ public static void ReleaseManagedFont(
         lv_font_t* font = null;
         ReleaseManagedFont(ref fallbackFont, ref font, ref fontManager, ref defaultFontStyle);
     }
+
+    /// <summary>
+    /// Releases managed font state and diagnostics.
+    /// </summary>
+    public static void ReleaseManagedFont(
+        ref lv_font_t* fallbackFont,
+        ref lv_font_t* font,
+        ref SixLaborsFontManager? fontManager,
+        ref LvglFontDiagnostics diagnostics,
+        ref lv_style_t* defaultFontStyle)
+    {
+        ReleaseManagedFont(ref fallbackFont, ref font, ref fontManager, ref defaultFontStyle);
+        diagnostics = LvglFontDiagnostics.Empty;
+    }
+
+    /// <summary>
+    /// Releases managed font state and diagnostics.
+    /// </summary>
+    public static void ReleaseManagedFont(
+        ref lv_font_t* fallbackFont,
+        ref SixLaborsFontManager? fontManager,
+        ref LvglFontDiagnostics diagnostics,
+        ref lv_style_t* defaultFontStyle)
+    {
+        lv_font_t* font = null;
+        ReleaseManagedFont(ref fallbackFont, ref font, ref fontManager, ref diagnostics, ref defaultFontStyle);
+    }
 }

src/LVGLSharp.Core/LvglManagedFontState.cs

@@ -0,0 +1,66 @@
+using LVGLSharp.Interop;
+
+namespace LVGLSharp;
+
+/// <summary>
+/// Represents the managed font state applied to an LVGL root object.
+/// </summary>
+public readonly unsafe struct LvglManagedFontState
+{
+    internal LvglManagedFontState(
+        lv_font_t* fallbackFont,
+        lv_font_t* managedFont,
+        SixLaborsFontManager? fontManager,
+        LvglFontDiagnostics diagnostics,
+        lv_style_t* defaultFontStyle)
+    {
+        FallbackFont = fallbackFont;
+        ManagedFont = managedFont;
+        FontManager = fontManager;
+        Diagnostics = diagnostics;
+        DefaultFontStyle = defaultFontStyle;
+    }
+
+    public static LvglManagedFontState Empty => default;
+
+    public lv_font_t* FallbackFont { get; }
+
+    public lv_font_t* ManagedFont { get; }
+
+    public SixLaborsFontManager? FontManager { get; }
+
+    public LvglFontDiagnostics Diagnostics { get; }
+
+    public lv_style_t* DefaultFontStyle { get; }
+
+    public void ApplyTo(
+        ref lv_font_t* fallbackFont,
+        ref SixLaborsFontManager? fontManager,
+        ref lv_style_t* defaultFontStyle)
+    {
+        fallbackFont = FallbackFont;
+        fontManager = FontManager;
+        defaultFontStyle = DefaultFontStyle;
+    }
+
+    public void ApplyTo(
+        ref lv_font_t* fallbackFont,
+        ref SixLaborsFontManager? fontManager,
+        ref LvglFontDiagnostics diagnostics,
+        ref lv_style_t* defaultFontStyle)
+    {
+        ApplyTo(ref fallbackFont, ref fontManager, ref defaultFontStyle);
+        diagnostics = Diagnostics;
+    }
+
+    public void ApplyTo(
+        ref lv_font_t* fallbackFont,
+        ref lv_font_t* managedFont,
+        ref SixLaborsFontManager? fontManager,
+        ref LvglFontDiagnostics diagnostics,
+        ref lv_style_t* defaultFontStyle)
+    {
+        ApplyTo(ref fallbackFont, ref fontManager, ref diagnostics, ref defaultFontStyle);
+        managedFont = ManagedFont;
+    }
+}

src/LVGLSharp.Drawing/Color.cs

@@ -2,28 +2,100 @@ namespace LVGLSharp.Drawing;
 
 public readonly struct Color : IEquatable<Color>
 {
+    private readonly string? _name;
+
     public Color(byte r, byte g, byte b, byte a = 255)
+        : this(a, r, g, b, null)
+    {
+    }
+
+    private Color(byte a, byte r, byte g, byte b, string? name)
     {
         A = a;
         R = r;
         G = g;
         B = b;
+        _name = name;
     }
 
     public byte A { get; }
+
     public byte R { get; }
+
     public byte G { get; }
+
     public byte B { get; }
 
-    public static Color Empty => new(0, 0, 0, 0);
+    public bool IsEmpty => A == 0 && R == 0 && G == 0 && B == 0 && _name is null;
+
+    public string Name => _name ?? (IsEmpty ? nameof(Empty) : ToArgb().ToString("X8"));
+
+    public static Color Empty => default;
 
-    public bool Equals(Color other) => A == other.A && R == other.R && G == other.G && B == other.B;
+    public static Color Transparent => new(0, 255, 255, 255, nameof(Transparent));
+
+    public static Color Black => new(255, 0, 0, 0, nameof(Black));
+
+    public static Color White => new(255, 255, 255, 255, nameof(White));
+
+    public static Color Red => new(255, 255, 0, 0, nameof(Red));
+
+    public static Color Green => new(255, 0, 128, 0, nameof(Green));
+
+    public static Color Blue => new(255, 0, 0, 255, nameof(Blue));
+
+    public static Color FromArgb(int red, int green, int blue)
+    {
+        return FromArgb(255, red, green, blue);
+    }
+
+    public static Color FromArgb(int alpha, int red, int green, int blue)
+    {
+        return new Color(ToByte(alpha), ToByte(red), ToByte(green), ToByte(blue), null);
+    }
+
+    public static Color FromArgb(int alpha, Color baseColor)
+    {
+        return new Color(ToByte(alpha), baseColor.R, baseColor.G, baseColor.B, baseColor._name);
+    }
+
+    public static Color FromName(string name)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(name);
+
+        return name switch
+        {
+            nameof(Transparent) => Transparent,
+            nameof(Black) => Black,
+            nameof(White) => White,
+            nameof(Red) => Red,
+            nameof(Green) => Green,
+            nameof(Blue) => Blue,
+            _ => new Color(0, 0, 0, 0, name),
+        };
+    }
+
+    public int ToArgb()
+    {
+        return (A << 24) | (R << 16) | (G << 8) | B;
+    }
+
+    public bool Equals(Color other) => A == other.A && R == other.R && G == other.G && B == other.B && string.Equals(_name, other._name, StringComparison.Ordinal);
 
     public override bool Equals(object? obj) => obj is Color other && Equals(other);
 
-    public override int GetHashCode() => HashCode.Combine(A, R, G, B);
+    public override int GetHashCode() => HashCode.Combine(A, R, G, B, _name);
+
+    public override string ToString() => Name;
 
     public static bool operator ==(Color left, Color right) => left.Equals(right);
 
     public static bool operator !=(Color left, Color right) => !left.Equals(right);
+
+    private static byte ToByte(int value)
+    {
+        return value < byte.MinValue || value > byte.MaxValue
+            ? throw new ArgumentOutOfRangeException(nameof(value))
+            : (byte)value;
+    }
 }

src/LVGLSharp.Drawing/Font.cs

@@ -1,15 +1,68 @@
 namespace LVGLSharp.Drawing;
 
-public class Font
+public sealed class Font : IEquatable<Font>
 {
-    public Font(string name, float size)
+    public Font(string familyName, float emSize)
+        : this(familyName, emSize, FontStyle.Regular, GraphicsUnit.Point)
     {
-        ArgumentException.ThrowIfNullOrWhiteSpace(name);
-        Name = name;
-        Size = size;
+    }
+
+    public Font(string familyName, float emSize, FontStyle style)
+        : this(familyName, emSize, style, GraphicsUnit.Point)
+    {
+    }
+
+    public Font(string familyName, float emSize, FontStyle style, GraphicsUnit unit)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(familyName);
+        if (emSize <= 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(emSize));
+        }
+
+        Name = familyName;
+        Size = emSize;
+        Style = style;
+        Unit = unit;
     }
 
     public string Name { get; }
 
     public float Size { get; }
+
+    public float SizeInPoints => Unit == GraphicsUnit.Point ? Size : Size;
+
+    public FontStyle Style { get; }
+
+    public GraphicsUnit Unit { get; }
+
+    public bool Bold => (Style & FontStyle.Bold) != 0;
+
+    public bool Italic => (Style & FontStyle.Italic) != 0;
+
+    public bool Underline => (Style & FontStyle.Underline) != 0;
+
+    public bool Strikeout => (Style & FontStyle.Strikeout) != 0;
+
+    public FontFamily FontFamily => new(Name);
+
+    public Font WithSize(float emSize)
+    {
+        return new Font(Name, emSize, Style, Unit);
+    }
+
+    public bool Equals(Font? other)
+    {
+        return other is not null &&
+            string.Equals(Name, other.Name, StringComparison.Ordinal) &&
+            Size.Equals(other.Size) &&
+            Style == other.Style &&
+            Unit == other.Unit;
+    }
+
+    public override bool Equals(object? obj) => obj is Font other && Equals(other);
+
+    public override int GetHashCode() => HashCode.Combine(Name, Size, Style, Unit);
+
+    public override string ToString() => $"[{Name}, {SizeInPoints}pt]";
 }

src/LVGLSharp.Drawing/FontFamily.cs

@@ -0,0 +1,20 @@
+namespace LVGLSharp.Drawing;
+
+public sealed class FontFamily : IEquatable<FontFamily>
+{
+    public FontFamily(string name)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(name);
+        Name = name;
+    }
+
+    public string Name { get; }
+
+    public bool Equals(FontFamily? other) => other is not null && string.Equals(Name, other.Name, StringComparison.Ordinal);
+
+    public override bool Equals(object? obj) => obj is FontFamily other && Equals(other);
+
+    public override int GetHashCode() => StringComparer.Ordinal.GetHashCode(Name);
+
+    public override string ToString() => Name;
+}