acdream/src/AcDream.App/UI/UiElement.cs

using System;
using System.Collections.Generic;
using System.Numerics;

namespace AcDream.App.UI;

/// <summary>
/// Base class for every UI widget in the retained-mode tree.
///
/// Design notes:
/// - Retail AC delegates widget semantics to the external
///   <c>keystone.dll</c> library (see
///   <c>docs/research/retail-ui/02-class-hierarchy.md</c> — there is no
///   widget hierarchy inside <c>acclient.exe</c> itself). We implement
///   our own retained-mode toolkit here, matching the <i>behavior</i>
///   described in the decompile without trying to byte-match Keystone's
///   internal class layout.
/// - Events use the retail-faithful <see cref="UiEvent"/> struct and
///   the <see cref="UiEventType"/> constants so that hand-ported panel
///   code can use the same magic numbers the decompiled C uses
///   (e.g. <c>if (e.Type == 0x15) ...</c> for drag-begin).
/// - Hit-testing is children-first (topmost wins) with Z-order tie
///   breaking; drawing is back-to-front so later children appear on top.
/// - Coordinates are in <b>screen pixels</b>, origin top-left.
///   <see cref="Bounds"/> is in the parent's local coordinate space.
/// </summary>
public abstract class UiElement
{
    // ── Identity ─────────────────────────────────────────────────────────
    /// <summary>
    /// Unique 32-bit event ID. Retail uses the range <c>0x10000000+</c>
    /// for custom app events (see
    /// <c>docs/research/retail-ui/04-input-events.md §3</c>). Assigned
    /// by <see cref="UiRoot"/> when the element is added to the tree.
    /// </summary>
    public uint EventId { get; internal set; }

    /// <summary>Human-readable name for debugging / FindByName.</summary>
    public string? Name { get; init; }

    // ── Geometry ────────────────────────────────────────────────────────
    /// <summary>X in the parent's local pixel space.</summary>
    public float Left   { get; set; }
    public float Top    { get; set; }
    public float Width  { get; set; }
    public float Height { get; set; }

    /// <summary>Absolute (screen-space) top-left, computed by walking Parent.</summary>
    public Vector2 ScreenPosition
    {
        get
        {
            var p = new Vector2(Left, Top);
            var parent = Parent;
            while (parent is not null)
            {
                p += new Vector2(parent.Left, parent.Top);
                parent = parent.Parent;
            }
            return p;
        }
    }

    // ── State flags ─────────────────────────────────────────────────────
    public bool Visible         { get; set; } = true;
    public bool Enabled         { get; set; } = true;

    /// <summary>
    /// If true, <see cref="HitTest"/> skips this element — the event
    /// passes through to whatever is behind. Used by decoration widgets
    /// (portrait frames, ornamental dividers).
    /// </summary>
    public bool ClickThrough    { get; set; }

    /// <summary>
    /// If true, <see cref="UiRoot"/> will set focus here on click,
    /// routing WM_KEYDOWN / WM_CHAR to <see cref="OnEvent"/> as
    /// <see cref="UiEventType.KeyDown"/> / <see cref="UiEventType.Char"/>.
    /// </summary>
    public bool AcceptsFocus    { get; set; }

    /// <summary>
    /// True if this is a text-entry (edit box); used by focus routing
    /// to suppress global hotkeys while typing.
    /// </summary>
    public bool IsEditControl   { get; set; }

    /// <summary>Painter's-algorithm z-order within siblings. Higher = on top.</summary>
    public int  ZOrder          { get; set; }

    // ── Tree structure ──────────────────────────────────────────────────
    public UiElement? Parent { get; private set; }

    private readonly List<UiElement> _children = new();
    public IReadOnlyList<UiElement> Children => _children;

    public virtual void AddChild(UiElement child)
    {
        if (child.Parent is not null) child.Parent.RemoveChild(child);
        child.Parent = this;
        _children.Add(child);
    }

    public virtual bool RemoveChild(UiElement child)
    {
        if (!_children.Remove(child)) return false;
        child.Parent = null;
        return true;
    }

    // ── Virtual overrides ───────────────────────────────────────────────

    /// <summary>
    /// Draw THIS element (not its children). Children are composited by
    /// <see cref="UiRoot"/> after this returns.
    /// </summary>
    protected virtual void OnDraw(UiRenderContext ctx) { }

    /// <summary>Per-frame tick (animations, timers, caret blink).</summary>
    protected virtual void OnTick(double deltaSeconds) { }

    /// <summary>
    /// Custom hit-test override. Default is a rectangle containment
    /// check on (<see cref="Width"/>, <see cref="Height"/>).
    /// </summary>
    protected virtual bool OnHitTest(float localX, float localY)
        => localX >= 0f && localX < Width && localY >= 0f && localY < Height;

    /// <summary>
    /// Event handler. Return <c>true</c> to consume the event (the
    /// <see cref="UiRoot"/> will stop propagation). Return <c>false</c>
    /// to let ancestors / fall-through handle it.
    /// </summary>
    public virtual bool OnEvent(in UiEvent e) => false;

    /// <summary>
    /// Tooltip text for this widget. Retail fires event 0x07 after
    /// ~1000ms hover, then queries the widget's virtual "GetString"
    /// (vtable +0x88) to render the tooltip body.
    /// </summary>
    public virtual string? GetTooltipText() => null;

    // ── Framework entry points (internal, called by UiRoot) ─────────────

    internal void DrawSelfAndChildren(UiRenderContext ctx)
    {
        if (!Visible) return;

        // Translate into our local space.
        ctx.PushTransform(Left, Top);
        try
        {
            OnDraw(ctx);

            // Children painted back-to-front (lowest ZOrder first).
            if (_children.Count > 0)
            {
                // Avoid LINQ allocation by copying to a temp array and sorting.
                var ordered = _children.ToArray();
                Array.Sort(ordered, static (a, b) => a.ZOrder.CompareTo(b.ZOrder));
                for (int i = 0; i < ordered.Length; i++)
                    ordered[i].DrawSelfAndChildren(ctx);
            }
        }
        finally
        {
            ctx.PopTransform();
        }
    }

    internal void TickSelfAndChildren(double dt)
    {
        if (!Visible) return;
        OnTick(dt);
        for (int i = 0; i < _children.Count; i++)
            _children[i].TickSelfAndChildren(dt);
    }

    /// <summary>
    /// Top-down, children-first hit-test. <paramref name="localX"/> /
    /// <paramref name="localY"/> are in THIS element's local space.
    /// Returns the topmost descendant (or this) at the point, or null.
    /// </summary>
    internal UiElement? HitTest(float localX, float localY)
    {
        if (!Visible || !Enabled || ClickThrough) return null;

        // Children first, in reverse Z-order (topmost first).
        if (_children.Count > 0)
        {
            var ordered = _children.ToArray();
            Array.Sort(ordered, static (a, b) => b.ZOrder.CompareTo(a.ZOrder));
            for (int i = 0; i < ordered.Length; i++)
            {
                var c = ordered[i];
                var childHit = c.HitTest(localX - c.Left, localY - c.Top);
                if (childHit is not null) return childHit;
            }
        }

        return OnHitTest(localX, localY) ? this : null;
    }
}