GPALControls.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Text.RegularExpressions;
using System.Threading.Tasks;
using System.Data;
using System.Windows.Forms;
using System.Windows.Forms.DataVisualization.Charting;
using static GenerallyPositive.Enums;
 
namespace GenerallyPositive.GPALForm
{
    class GPALControls
    {
    }
    #region <GPAL Controls>
    public class GPALControl : IAllowControlSettingsAndFontSettings, IAllowToolTipDelay, IAllowForEventControlSettings
    {
        public Font FontType { get; internal set; } = new Font("Georgia", 12);
        public ContentAlignment TextAlignment { get; internal set; } = ContentAlignment.MiddleLeft;
        public bool AutoSize { get; internal set; } = true;
        //public ContentAlignment ControlAlignment { get; internal set; } = ContentAlignment.MiddleLeft;
        public IAllowControlSettingsAndFontSettings WithFont(Font font)
        {
            FontType = font;
            return this;
        }

        public IAllowControlSettingsAndFontSettings WithTextAlignment(ContentAlignment textAlignment)
        {
            TextAlignment = textAlignment;
            return this;
        }

        public IAllowControlSettingsAndFontSettings WithAutoSize(bool autoSize)
        {
            AutoSize = autoSize;
            return this;
        }

        //public IAllowControlSettings WithAlignment(ContentAlignment alignment)
        //{
        //    throw new NotImplementedException();
        //}
        public int Height { get; internal set; } = 0;
        public int Width { get; internal set; } = 0;
        private string _text;
        public string Text
        {
            get => _text;
            set
            {
                _text = value;
                if (WindowsControl is Control ctrl && true == Alive(ctrl))
                {
                    PostToUi(ctrl, () => ctrl.Text = value);
                }
            }
        }

        public string Name { get; internal set; }
        public object Tag { get; internal set; }
        public dynamic WindowsControl
        {
            get => _windowsControl;
            internal set
            {
                _windowsControl = value;
 
                // anything a workflow did before the form was built was held rather than dropped, and this is
                // the moment it can be done for real
                if (null != value)
                    Realized();
            }
        }
 
        private dynamic _windowsControl;

        internal virtual void Realized()
        {
            // the text controls hold their text in a field of their own and the form writes that field into
            // the control it builds, so a line appended before then is already on screen. Its queued copy is
            // dropped rather than appended again
            while (true == pendingLines.TryDequeue(out string _))
            {
            }
        }
 
        public bool IsReady => WindowsControl != null;
 
        // Line appending, shared by the text controls. Held on the base because the marshalling and the
        // not-yet-created-handle case are the same for all of them
        private readonly ConcurrentQueue<string> pendingLines = new ConcurrentQueue<string>();
        private readonly object appendGate = new object();
        private bool waitingForHandle = false;
 
        internal void AppendLineCore(string text, int maxLines)
        {
            // Queued here and written only on the UI thread. Called from whichever thread published, which
            // during a workflow is a worker while the UI thread is blocked inside Run
            pendingLines.Enqueue(text);
 
            DrainLines(maxLines);
        }
 
        // TextBoxBase, the type GPALTextArea and GPALRichTextBox share
        private void DrainLines(int maxLines)
        {
            // A closing form still publishes, and posting to a disposed control makes Windows Forms recreate
            // its handle
            if (!(WindowsControl is TextBoxBase tb) || false == Alive(tb)) return;
 
            // No handle means created but not yet shown, since the disposed case is handled above. The lines
            // stay queued and HandleCreated drains them
            if (false == tb.IsHandleCreated)
            {
                lock (appendGate)
                {
                    if (false == waitingForHandle)
                    {
                        waitingForHandle = true;
                        tb.HandleCreated += (sender, args) => DrainLines(maxLines);
                    }
                }
 
                return;
            }
 
            MethodInvoker drain = () =>
            {
                // Posted while the handle existed and run after it went
                if (false == Alive(tb) || false == tb.IsHandleCreated) return;
 
                // the whole queue in one pass. Asking the control for its Lines splits the entire buffer, and
                // rewriting Text at the cap rebuilds every line, so doing either once per queued line made a
                // busy workflow take minutes here with the form unable to answer a click
                List<string> arrived = new List<string>();
 
                while (true == pendingLines.TryDequeue(out string line))
                    arrived.Add(line);
 
                if (0 == arrived.Count) return;
 
                string[] held = 0 < maxLines ? tb.Lines : new string[0];
 
                if (0 < maxLines && held.Length + arrived.Count > maxLines)
                {
                    // over the cap, so the tail of what is held plus the batch is written once
                    List<string> keeping = new List<string>(maxLines);
 
                    int roomForHeld = maxLines - Math.Min(arrived.Count, maxLines);
 
                    for (int each = Math.Max(0, held.Length - roomForHeld); each < held.Length; each++)
                        keeping.Add(held[each]);
 
                    for (int each = Math.Max(0, arrived.Count - maxLines); each < arrived.Count; each++)
                        keeping.Add(arrived[each]);
 
                    tb.Text = string.Join("\r\n", keeping);
                }
                else
                {
                    if (0 < tb.TextLength) tb.AppendText("\r\n");
 
                    tb.AppendText(string.Join("\r\n", arrived));
                }
 
                tb.SelectionStart = tb.TextLength;
                tb.ScrollToCaret();
            };
            // Posted rather than invoked. A workflow started from a button holds the UI thread, so an invoke
            // from a worker would block until it finished
            PostToUi(tb, drain);
        }
 
        internal void ClearLinesCore()
        {
            // The queue is emptied too, or lines held during a run arrive after the clear
            while (true == pendingLines.TryDequeue(out string dropped)) { }
 
            if (!(WindowsControl is TextBoxBase tb) || false == Alive(tb)) return;
 
            if (false == tb.IsHandleCreated)
            {
                tb.Text = string.Empty;
                return;
            }
 
            MethodInvoker clear = () =>
            {
                if (false == Alive(tb) || false == tb.IsHandleCreated) return;
 
                tb.Clear();
            };
 
            PostToUi(tb, clear);
        }
 
        internal void ScrollToEndCore()
        {
            if (!(WindowsControl is TextBoxBase tb) || false == Alive(tb)) return;
 
            PostToUi(tb, () => tb.ScrollToCaret());
        }

        internal static bool Alive(Control control)
        {
            // whether the control is still there, and nothing about whether it can be marshalled to. a control
            // on a tab nobody has opened has no handle yet and is very much still there: its value is set on it
            // now and painted when the tab is first shown. deciding that here would throw those writes away,
            // so the handle is asked about where the marshalling happens instead
            return null != control
                && false == control.IsDisposed
                && false == control.Disposing;
        }
 
        public void Focus()
        {
            if (WindowsControl is Control ctrl && true == Alive(ctrl))
                ctrl.Focus();
        }
        public FormControlType ControlType { get; internal set; }
        internal bool ReadOnly { get; set; }
        internal bool IsChecked { get; set; }
        internal bool IsEnabled { get; set; } = true;

        public virtual bool Enabled
        {
            get
            {
                bool retVal = IsEnabled;
 
                if (WindowsControl is Control control && true == Alive(control))
                    retVal = OnUiRead(control, () => control.Enabled, IsEnabled);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is Control control && true == Alive(control))
                    OnUi(control, () => control.Enabled = value);
 
                // kept either way, so a control disabled before the form is built comes up disabled and a
                // control read back after being closed still answers with what it was last told
                IsEnabled = value;
            }
        }

        public virtual IAllowControlSettings WithEnabled(bool enabled = true)
        {
            Enabled = enabled;
            return this;
        }

        public virtual IAllowControlSettings WithReadOnly(bool readOnly = true)
        {
            IsReadOnly = readOnly;
            return this;
        }

        internal bool IsReadOnly { get; set; }
        internal string ToolTipText { get; private set; }
        internal int ToolTipAutoPopDelayMs { get; private set; } = 5000;   // default 5 seconds
        internal System.Windows.Forms.Keys ShortCutKey { get; set; }
        internal List<(ControlEventType EventType, Delegate Handler)> Callbacks { get; } = new List<(ControlEventType EventType, Delegate Handler)>();

        public IAllowForEventControlSettings WithCallback<TDelegate>(TDelegate handler)
            where TDelegate : Delegate
        {
            Callbacks.Add((ControlEventType.Default, WrapHandler(handler, RunOnUiThread) ?? (Delegate)handler));
 
            return this;
        }

        private const double UiHeldWarningSeconds = 2.0;

        private int _callbackDepth;

        private int _callbackPending;

        private const int CallbackBacklogWarning = 5;

        private System.Threading.Tasks.Task _callbackChain = System.Threading.Tasks.Task.CompletedTask;

        private readonly object _callbackChainGate = new object();

        private string CallbackOwner => true == string.IsNullOrEmpty(Name) ? GetType().Name : Name;

        private void EnterCallback()
        {
            if (1 < System.Threading.Interlocked.Increment(ref _callbackDepth))
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"The callback for [{CallbackOwner}] was entered while it was still running, which is what a handler writing to its own control does", this, GPALObjectType.Other);
        }

        private void RunOnUiThread(Action call)
        {
            System.Diagnostics.Stopwatch held = System.Diagnostics.Stopwatch.StartNew();
 
            EnterCallback();
 
            try
            {
                call();
            }
            finally
            {
                // the depth comes back down even when the handler threw, or the next press is reported as a loop
                System.Threading.Interlocked.Decrement(ref _callbackDepth);
            }
 
            if (UiHeldWarningSeconds < held.Elapsed.TotalSeconds)
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"The handler for [{CallbackOwner}] held the window for [{held.Elapsed.TotalSeconds:0.0}] seconds. Attach it with WithCallbackOffUIThread and it runs on a thread of its own", this, GPALObjectType.Other);
        }

        public IAllowForEventControlSettings WithCallbackOffUIThread<TDelegate>(TDelegate handler)
            where TDelegate : Delegate
        {
            // a drag handler sets args.Effect and a key handler sets args.Handled, and the event reads both the
            // moment the handler returns. running one of those on a thread of its own means the answer is set
            // after it was wanted, so the drop is refused or the key goes through anyway
            bool answersAsItReturns = handler is DragEventHandler || handler is KeyEventHandler;
 
            Delegate wrapped = true == answersAsItReturns ? null : WrapHandler(handler, QueueInBackground);
 
            if (null == wrapped)
            {
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, true == answersAsItReturns
                    ? $"The event reads its answer from [{typeof(TDelegate).Name}] as soon as the handler returns, so the handler for [{CallbackOwner}] stays on the UI thread"
                    : $"[{typeof(TDelegate).Name}] is not a handler type GPAL knows, so the handler for [{CallbackOwner}] stays on the UI thread", this, GPALObjectType.Other);
 
                wrapped = WrapHandler(handler, RunOnUiThread) ?? (Delegate)handler;
            }
 
            Callbacks.Add((ControlEventType.Default, wrapped));
 
            return this;
        }

        private void RunInBackground(Action call)
        {
            EnterCallback();
 
            try
            {
                call();
            }
            catch (Exception ex)
            {
                // nothing is waiting on this thread to catch it, and a handler that died in silence looks
                // like a button that did nothing
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"A background handler for [{CallbackOwner}] ended in an exception", this, GPALObjectType.Other, ex);
            }
            finally
            {
                System.Threading.Interlocked.Decrement(ref _callbackDepth);
                System.Threading.Interlocked.Decrement(ref _callbackPending);
            }
        }

        private Delegate WrapHandler<TDelegate>(TDelegate handler, Action<Action> runner)
            where TDelegate : Delegate
        {
            Delegate retVal;
 
            switch (handler)
            {
                case EventHandler typed:
                    retVal = (EventHandler)((sender, args) => runner(() => typed(sender, args)));
                    break;
 
                case KeyEventHandler typed:
                    retVal = (KeyEventHandler)((sender, args) => runner(() => typed(sender, args)));
                    break;
 
                case DragEventHandler typed:
                    retVal = (DragEventHandler)((sender, args) => runner(() => typed(sender, args)));
                    break;
 
                case ScrollEventHandler typed:
                    retVal = (ScrollEventHandler)((sender, args) => runner(() => typed(sender, args)));
                    break;
 
                case SplitterEventHandler typed:
                    retVal = (SplitterEventHandler)((sender, args) => runner(() => typed(sender, args)));
                    break;
 
                case ItemCheckedEventHandler typed:
                    retVal = (ItemCheckedEventHandler)((sender, args) => runner(() => typed(sender, args)));
                    break;
 
                case TreeViewEventHandler typed:
                    retVal = (TreeViewEventHandler)((sender, args) => runner(() => typed(sender, args)));
                    break;
 
                case DataGridViewCellEventHandler typed:
                    retVal = (DataGridViewCellEventHandler)((sender, args) => runner(() => typed(sender, args)));
                    break;
 
                default:
                    retVal = null;
                    break;
            }
 
            return retVal;
        }

        private void QueueInBackground(Action call)
        {
            if (CallbackBacklogWarning == System.Threading.Interlocked.Increment(ref _callbackPending))
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"[{CallbackBacklogWarning}] handlers for [{CallbackOwner}] are waiting their turn, so the events are arriving faster than the handler runs", this, GPALObjectType.Other);
 
            lock (_callbackChainGate)
                _callbackChain = _callbackChain.ContinueWith(previous => RunInBackground(call));
        }

        public IAllowControlSettings ForEvent(ControlEventType eventType)
        {
            // replace the last "Default" entry with the explicit event
            // (this is the only "magic" — keeps chain order natural)
            if (Callbacks.Count > 0)
            {
                var last = Callbacks[Callbacks.Count - 1];
                if (last.EventType == ControlEventType.Default)
                {
                    Callbacks[Callbacks.Count - 1] = (eventType, last.Handler);
                    return this;
                }
            }
 
            // if no prior Default > just add as explicit (rare misuse case)
            Callbacks.Add((eventType, null)); // null handler = ignore later
            return this;
        }

        public IAllowToolTipDelay WithToolTip(string toolTipText)
        {
            ToolTipText = toolTipText ?? "";
            return this;
        }

        public IAllowControlSettings WithToolTipDelay(int delayInMs)
        {
            ToolTipAutoPopDelayMs = Math.Max(1000, delayInMs); // enforce reasonable minimum
            return this;
        }

        public IAllowControlSettings WithShortcutKey(System.Windows.Forms.Keys shortCutKey)
        {
            ShortCutKey = shortCutKey;
            return this;
        }

        internal static void OnUi(Control control, MethodInvoker work)
        {
            if (false == Alive(control))
                return;
 
            try
            {
                // no handle means no window to marshal to and no thread that owns it, so the work is done here
                // and windows forms keeps it until the control is created
                if (true == control.IsHandleCreated && true == control.InvokeRequired)
                    control.Invoke(work);
                else
                    work();
            }
            catch (ObjectDisposedException)
            {
                // the form went between the check and the work
            }
            catch (InvalidOperationException)
            {
                // the handle went the same way, which Invoke reports as this
            }
        }

        internal static void OnUiOrHere(Control control, MethodInvoker work)
        {
            if (true == Alive(control))
                OnUi(control, work);
            else
                work();
        }

        internal static void PostToUi(Control control, MethodInvoker work)
        {
            if (false == Alive(control))
                return;
 
            try
            {
                if (true == control.IsHandleCreated && true == control.InvokeRequired)
                    control.BeginInvoke(work);
                else
                    work();
            }
            catch (ObjectDisposedException)
            {
                // the form went between the check and the work
            }
            catch (InvalidOperationException)
            {
                // the handle went the same way, which BeginInvoke reports as this
            }
        }

        internal static T OnUiRead<T>(Control control, Func<T> read, T whenGone)
        {
            T retVal = whenGone;
 
            if (true == Alive(control))
                try
                {
                    retVal = true == control.IsHandleCreated && true == control.InvokeRequired
                        ? (T)control.Invoke(read)
                        : read();
                }
                catch (ObjectDisposedException)
                {
                    // the form went between the check and the read
                }
                catch (InvalidOperationException)
                {
                    // the handle went the same way, which Invoke reports as this
                }
 
            return retVal;
        }

        public void OnUiThread(Action action)
        {
            OnUiOrHere(WindowsControl as Control, () => action());
        }

        public IAllowControlSettings WithName(string name)
        {
            this.Name = name;
            return this;
        }

        public IAllowControlSettings WithTag(object tag)
        {
            // Tag is on Control, so every realized control carries one. casting to TextBox threw on a button,
            // a grid or anything else the moment this was called after the form was built
            if (WindowsControl is Control control && true == Alive(control))
                OnUi(control, () => control.Tag = tag);
 
            this.Tag = tag;
 
            return this;
        }

        public IAllowControlSettings WithHeight(int height)
        {
            this.Height = height;
            return this;
        }

        public IAllowControlSettings WithWidth(int width)
        {
            this.Width = width;
            return this;
        }

        public IAllowControlSettingsAndFontSettings WithText(string text)
        {
            if (null != WindowsControl)
                ((TextBox)WindowsControl).Text = text;      // this.Text will be updated via the TextChanged event;
            else
                this.Text = text;
            return this;
        }

        public dynamic ToGPALObject()
        {
            return this;
        }
    }

    public class GPALChart : GPALControl, IAllowControlSettingsAndChartSettings
    {
        internal ChartColorPalette ChartColorPalette { get; set; }
        internal Series mySeries { get; set; }
        internal string Title { get; set; }
 
        internal GPALChart()
        {
            ControlType = FormControlType.Chart;
            Chart chart = new Chart
            {
                Name = Name,
                AutoSize = false,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Dock = DockStyle.Fill,
            };
            chart.ChartAreas.Add(new ChartArea(Name));
            WindowsControl = chart;
        }
        public IAllowControlSettingsAndChartSettings WithPalette(ChartColorPalette colorPalette)
        {
            ((Chart)WindowsControl).Palette = colorPalette;
            return this;
        }

        public IAllowControlSettingsAndChartSettings WithSeries(Series series)
        {
            ((Chart)WindowsControl).Series.Add(series);
            return this;
        }

        public IAllowControlSettingsAndChartSettings WithTitle(string title)
        {
            ((Chart)WindowsControl).Titles.Add(title);
            return this;
        }

        public SeriesCollection Series
        {
            get
            {
                return ((Chart)(WindowsControl)).Series;
            }
        }

        public LegendCollection Legends
        {
            get
            {
                return ((Chart)(WindowsControl)).Legends;
            }
        }

        public TitleCollection Titles
        {
            get
            {
                return ((Chart)(WindowsControl)).Titles;
            }
        }

        internal ChartAreaCollection ChartAreas
        {
            get
            {
                return ((Chart)WindowsControl).ChartAreas;
            }
        }
    }

    public class GPALButton : GPALControl, IAllowControlSettingsAndDefault
    {
        internal bool IsDefault { get; set; }
        internal GPALButton()
        {
            ControlType = FormControlType.Button;
            IsDefault = false;
        }
        public IAllowControlSettingsAndDefault Default
        {
            get
            {
                IsDefault = true;
                return this;
            }
        }
    }

    public class GPALCheckbox : GPALControl, IAllowControlSettingsAndChecked
    {
        internal GPALCheckbox()
        {
            ControlType = FormControlType.Checkbox;
        }
        public IAllowControlSettingsAndChecked WithChecked(bool isChecked)
        {
            this.Checked = isChecked;
            return this;
        }

        public bool Checked
        {
            get
            {
                bool retVal = IsChecked;
 
                if (WindowsControl is CheckBox cb && true == Alive(cb))
                    retVal = OnUiRead(cb, () => cb.Checked, retVal);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is CheckBox cb && true == Alive(cb))
                {
                    OnUi(cb, () => cb.Checked = value);
                }
                else
                {
                    IsChecked = value;
                }
            }
        }
    }

    public class GPALDataGridView : GPALControl, IAllowDataGridViewControlSettings
    {
        private IGPALGrid<string> _grid;
        private readonly List<string> _columnNames = new List<string>();
        private bool _autoGenerateColumns = false;  // default false – only generate if explicitly asked or no columns set
 
        internal GPALDataGridView()
        {
            ControlType = FormControlType.DataGridView;
        }

        public IAllowDataGridViewControlSettings WithColumns(params string[] columnNames)
        {
            if (columnNames != null)
            {
                _columnNames.AddRange(columnNames);
            }
            return this;
        }

        public new IAllowDataGridViewControlSettings WithReadOnly(bool readOnly = true)
        {
            base.ReadOnly = readOnly;
            return this;
        }

        public IAllowDataGridViewControlSettings WithAutoGenerateColumns(bool autoGenerate)
        {
            _autoGenerateColumns = autoGenerate;
            return this;
        }

        public IAllowDataGridViewControlSettings WithInput(IGPALGrid<string> grid)
        {
            this.CurrentGrid = grid;
            return this;
        }

 
 
        // how wide each column is, in column order. Empty leaves every column as the control makes it
        internal readonly List<int> _columnWidths = new List<int>();

        public IAllowDataGridViewControlSettings WithColumnWidth(params int[] widths)
        {
            _columnWidths.Clear();
 
            if (null != widths)
                _columnWidths.AddRange(widths);
 
            ApplyColumnWidths();
 
            return this;
        }
 
 
        // which columns wrap their text, in column order. Empty is every column on one line, which is what a
        // grid does without being asked
        internal readonly List<bool> _columnWrap = new List<bool>();

        public IAllowDataGridViewControlSettings WithWrap(params bool[] wrap)
        {
            _columnWrap.Clear();
            wrapAsked = true;
 
            if (null != wrap)
                _columnWrap.AddRange(wrap);
 
            ApplyWrap();
 
            return this;
        }

        internal void ApplyWrap()
        {
            if (!(WindowsControl is DataGridView dgv) || false == Alive(dgv))
                return;
 
            if (true == dgv.InvokeRequired)
            {
                OnUi(dgv, ApplyWrap);
                return;
            }
 
            // nothing said is every column on one line. Said with no entries at all is every column wrapping,
            // which is the difference between never calling it and calling it bare
            bool everyColumn = 0 == _columnWrap.Count && true == wrapAsked;
 
            for (int column = 0; column < dgv.Columns.Count; column++)
            {
                bool wraps = true == everyColumn
                          || (column < _columnWrap.Count && true == _columnWrap[column]);
 
                dgv.Columns[column].DefaultCellStyle.WrapMode = true == wraps
                                                              ? DataGridViewTriState.True
                                                              : DataGridViewTriState.False;
            }
 
            dgv.AutoResizeRows(DataGridViewAutoSizeRowsMode.AllCellsExceptHeaders);
        }
 
        // whether WithWrap was called at all, which is how a bare call means every column
        private bool wrapAsked = false;
 
        // what share of the width each column takes. Empty leaves the columns as the control makes them
        internal readonly List<double> _columnShares = new List<double>();

        public IAllowDataGridViewControlSettings WithColumnWidth(params double[] shares)
        {
            _columnShares.Clear();
 
            if (null != shares)
                _columnShares.AddRange(shares);
 
            ApplyColumnWidths();
 
            return this;
        }
 
        // the widths are given before the form is built and again after, because a control that does not exist
        // yet cannot be told anything and one that already does will not be rebuilt
        internal void ApplyColumnWidths()
        {
            if (!(WindowsControl is DataGridView dgv) || false == Alive(dgv))
                return;
 
            // shares first: they set the mode the whole control sizes by, and a pixel width said afterwards
            // still lands because a filled column keeps the width it is given until the next resize
            if (0 < _columnShares.Count)
            {
                dgv.AutoSizeColumnsMode = DataGridViewAutoSizeColumnsMode.Fill;
 
                for (int column = 0; column < _columnShares.Count && column < dgv.Columns.Count; column++)
                    dgv.Columns[column].FillWeight = (float)(0 < _columnShares[column] ? _columnShares[column] : 1);
            }
 
            if (0 == _columnWidths.Count)
                return;
 
            if (true == dgv.InvokeRequired)
            {
                OnUi(dgv, ApplyColumnWidths);
                return;
            }
 
            for (int column = 0; column < _columnWidths.Count && column < dgv.Columns.Count; column++)
                if (0 < _columnWidths[column])
                    dgv.Columns[column].Width = _columnWidths[column];
 
            FillLastColumn();
        }
 
        // whether a workflow said anything about the pixel widths, which is what asks the last column to end
        // the row at the edge of the control. shares reach the edge on their own through Fill
        // a width for every column, which is what says the workflow described the whole row. Widths for only
        // the first few leave the rest as the control sizes them, which is what the remarks promise. Shares
        // reach the edge through Fill on their own, so they are not filled a second time here
        internal bool LastColumnFills => 0 < _columnWidths.Count && _columnWidths.Count == (WindowsControl as DataGridView)?.Columns.Count && 0 == _columnShares.Count;
 
        // setting a column's width lays the control out again, which raises the resize this runs from
        private bool filling = false;

        internal void FillLastColumn()
        {
            if (!(WindowsControl is DataGridView dgv) || false == Alive(dgv) || false == LastColumnFills)
                return;
 
            if (true == dgv.InvokeRequired)
            {
                OnUi(dgv, FillLastColumn);
                return;
            }
 
            int last = dgv.Columns.Count - 1;
 
            if (0 > last || true == filling)
                return;
 
            filling = true;
 
            try
            {
                // a filled column takes its width from the mode rather than from Width, so the fill only means
                // anything while the grid is sizing by pixels
                dgv.AutoSizeColumnsMode = DataGridViewAutoSizeColumnsMode.None;
 
                if (last < _columnWidths.Count && 0 < _columnWidths[last])
                    dgv.Columns[last].Width = _columnWidths[last];
 
                int used = 0;
 
                for (int before = 0; before < last; before++)
                    used += dgv.Columns[before].Width;
 
                // the grid's scrollbars are child controls sitting inside the client area, unlike the list
                // view's, so ClientSize still counts the vertical one. Without taking it off, a grid with
                // enough rows to scroll made the last column a scrollbar too wide and grew a horizontal one
                int verticalBar = 0;
 
                foreach (Control child in dgv.Controls)
                    if (child is VScrollBar bar && true == bar.Visible)
                        verticalBar = bar.Width;
 
                // the row header is part of the width the columns have to share, and it is not a column
                int left = dgv.ClientSize.Width - used - (true == dgv.RowHeadersVisible ? dgv.RowHeadersWidth : 0) - verticalBar - GPALListView.FillMargin;
 
                if (left > dgv.Columns[last].Width)
                    dgv.Columns[last].Width = left;
            }
            finally
            {
                filling = false;
            }
        }

        public IAllowDataGridViewControlSettings WithInput(DataTable dataTable)
        {
            IGPALGrid<string> rows = DatabaseHelper.DataTableToGrid(dataTable, out List<DatabaseSettings.DatabaseColumn> columns);
 
            // the names first, because the grid holds rows and nothing else, and a column with no name is shown
            // as its number
            if (0 == _columnNames.Count)
                foreach (DatabaseSettings.DatabaseColumn column in columns)
                    _columnNames.Add(column.ColumnName);
 
            return WithInput(rows);
        }

        public IAllowDataGridViewControlSettings WithInput(IGPALDatabase database)
        {
            DataTable table = null;
 
            if (null != database)
                database.SaveTo(out table);
 
            return WithInput(table);
        }

        public IAllowDataGridViewControlSettings WithInput(GPALFile file)
        {
            IGPALGrid<string> rows = GPAL.Grid.ToGPALObject();
 
            if (null != file)
            {
                FileHelper.GetGrid(((IGPALFileInternal)file).FileSettings, out List<IGPALGrid<string>> tokens);
 
                // a file can hold more than one of them, and a grid control shows one, so they follow each
                // other down the control the way they follow each other through the file
                if (null != tokens)
                    foreach (IGPALGrid<string> token in tokens)
                        foreach (List<string> row in token)
                            rows.AddRow(new List<string>(row));
            }
 
            return WithInput(rows);
        }
 
        // the range a GetGrid reads, counting from one so a workflow says what a person sees. Unset at either
        // end means as far as the control goes in that direction
        private int _startRow = 0;
        private int _startColumn = 0;
        private int _endRow = 0;
        private int _endColumn = 0;

        public IAllowDataGridViewControlSettings WithStartRow(int row)
        {
            _startRow = row;
            return this;
        }

        public IAllowDataGridViewControlSettings WithStartColumn(int column)
        {
            _startColumn = column;
            return this;
        }

        public IAllowDataGridViewControlSettings WithEndRow(int row)
        {
            _endRow = row;
            return this;
        }

        public IAllowDataGridViewControlSettings WithEndColumn(int column)
        {
            _endColumn = column;
            return this;
        }

        public IAllowDataGridViewControlSettings GetGrid(out IGPALGrid<string> grid)
        {
            IGPALGrid<string> reading = GPAL.Grid.ToGPALObject();
 
            if (WindowsControl is DataGridView dgv && true == Alive(dgv))
            {
                if (true == dgv.InvokeRequired)
                    OnUi(dgv, () => ReadInto(dgv, reading));
                else
                    ReadInto(dgv, reading);
            }
            else if (null != _grid)
                foreach (List<string> row in _grid)
                    reading.AddRow(new List<string>(row));
 
            grid = reading;
 
            return this;
        }

        private void ReadInto(DataGridView dgv, IGPALGrid<string> reading)
        {
            int firstRow = 1 > _startRow ? 1 : _startRow;
            int lastRow = 1 > _endRow ? dgv.Rows.Count : (_endRow > dgv.Rows.Count ? dgv.Rows.Count : _endRow);
            int firstColumn = 1 > _startColumn ? 1 : _startColumn;
            int lastColumn = 1 > _endColumn ? dgv.Columns.Count : (_endColumn > dgv.Columns.Count ? dgv.Columns.Count : _endColumn);
 
            // the column names first, so a saved file says what its columns are, and only for the columns the
            // range covers
            if (0 < dgv.Columns.Count)
            {
                List<string> headers = new List<string>();
 
                for (int column = firstColumn; column <= lastColumn; column++)
                    headers.Add(dgv.Columns[column - 1].HeaderText ?? string.Empty);
 
                reading.AddRow(headers);
            }
 
            for (int row = firstRow; row <= lastRow; row++)
            {
                if (true == dgv.Rows[row - 1].IsNewRow)
                    continue;
 
                List<string> cells = new List<string>();
 
                for (int column = firstColumn; column <= lastColumn; column++)
                    cells.Add(dgv.Rows[row - 1].Cells[column - 1].Value?.ToString() ?? string.Empty);
 
                reading.AddRow(cells);
            }
        }
 
        internal void SyncGridToControl()
        {
            if (!(WindowsControl is DataGridView dgv) || false == Alive(dgv) || _grid == null)
            {
                return;
            }
 
            if (dgv.InvokeRequired)
            {
                OnUi(dgv, SyncGridToControl);
                return;
            }
 
            dgv.Rows.Clear();
            dgv.Columns.Clear();
 
            // Determine column count from first non-null row (defensive)
            int columnCount = 0;
            foreach (List<string> row in _grid)
            {
                if (row != null)
                {
                    columnCount = row.Count;
                    break;
                }
            }
 
            // Columns
            if (_columnNames.Count > 0)
            {
                int colIndex = 0;
                foreach (string header in _columnNames)
                {
                    if (colIndex >= columnCount) break;
                    dgv.Columns.Add(header, header);
                    colIndex++;
                }
            }
            else if (_autoGenerateColumns && columnCount > 0)
            {
                for (int i = 0; i < columnCount; i++)
                {
                    string header = $"Column {i + 1}";
                    dgv.Columns.Add(header, header);
                }
            }
 
            // Rows
            foreach (List<string> rowData in _grid)
            {
                if (rowData == null) continue;
 
                var dgvRow = new DataGridViewRow();
                var cells = new DataGridViewCell[rowData.Count];
 
                int colIndex = 0;
                foreach (string cellValue in rowData)
                {
                    cells[colIndex] = new DataGridViewTextBoxCell
                    {
                        Value = cellValue ?? ""
                    };
                    colIndex++;
                }
 
                dgvRow.Cells.AddRange(cells);
                dgv.Rows.Add(dgvRow);
            }
 
            dgv.AutoResizeColumns(DataGridViewAutoSizeColumnsMode.AllCells);
            dgv.AutoResizeRows(DataGridViewAutoSizeRowsMode.AllCellsExceptHeaders);
 
            // the rows just sized every column to its own content, so the widths the workflow asked for are said
            // again here. Without this they lasted only until the grid was refilled, since the widths are applied
            // once as the form is built and a refill happens long after. The list view says its own again the
            // same way, from RefitSizedColumns
            ApplyColumnWidths();
            ApplyWrap();
        }

        public IGPALGrid<string> CurrentGrid
        {
            get => _grid;
            set
            {
                _grid = value;
                SyncGridToControl();
            }
        }

        public IReadOnlyList<string> ColumnNames => _columnNames.AsReadOnly();
        public bool AutoGenerateColumns => _autoGenerateColumns;
    }

    public class GPALInput : GPALControl, IAllowControlSettingsPlaceholderAndPassword
    {
        internal bool InputIsPassword { get; set; } = false;
        internal string PlaceHolder { get; set; }
        internal GPALInput()
        {
            ControlType = FormControlType.Input;
        }
        public bool ShowPassword
        {
            get
            {
                return false == InputIsPassword;
            }
            set
            {
                InputIsPassword = false == value;
 
                if (WindowsControl is PlaceholderTextBox ptbInput && true == Alive(ptbInput))
                {
                    char passwordChar = true == value ? '\0' : '●';  // bullet
 
                    OnUi(ptbInput, () => ptbInput.PasswordChar = passwordChar);
                }
            }
        }
 
        public IAllowControlSettingsPlaceholderAndPassword IsPassword
        {
            get
            {
                InputIsPassword = true;
                if (true == String.IsNullOrEmpty(PlaceHolder))
                    PlaceHolder = "Enter Password";
                return this;
            }
        }
        public IAllowControlSettingsPlaceholderAndPassword WithPlaceholder(string PlaceholderText)
        {
            PlaceHolder = PlaceholderText;
            if (WindowsControl is PlaceholderTextBox tb && true == Alive(tb))
                tb.PlaceholderText = PlaceholderText;
            return this;
        }
 
        public override IAllowControlSettings WithReadOnly(bool readOnly = true)
        {
            IsReadOnly = readOnly;
            if (WindowsControl is PlaceholderTextBox tb && true == Alive(tb))
                tb.ReadOnly = readOnly;
            return this;
        }
 
    }

    // TOFO: font type, font size
    public class GPALLabel : GPALControl, IAllowControlSettingsAndFontSettings
    {
        internal GPALLabel()
        {
            ControlType = FormControlType.Label;
        }
    }

    public class GPALSpacer : GPALControl
    {
        internal GPALSpacer()
        {
            ControlType = FormControlType.Spacer;
        }
    }

    public class GPALLinkLabel : GPALControl, IAllowControlSettingsAndUrl
    {
        internal GPALLinkLabel()
        {
            ControlType = FormControlType.LinkLabel;
        }

        public string Url { get; internal set; }

        public IAllowControlSettingsAndUrl WithUrl(string url)
        {
            Url = url;
            return this;
        }

        internal void Open()
        {
            string target = false == string.IsNullOrWhiteSpace(Url) ? Url : Text;
 
            if (true == target?.StartsWith("http://", StringComparison.OrdinalIgnoreCase)
                || true == target?.StartsWith("https://", StringComparison.OrdinalIgnoreCase))
                GPAL.Launcher.WithExecutable(target).Launch();
        }
    }

    // TODO: group box
    public class GPALRadioButton : GPALControl, IAllowControlSettingsAndChecked
    {
        internal GPALRadioButton()
        {
            ControlType = FormControlType.RadioButton;
        }
        public IAllowControlSettingsAndChecked WithChecked(bool isChecked)
        {
            this.Checked = isChecked;
            return this;
        }

        public bool Checked
        {
            get
            {
                bool retVal = IsChecked;
 
                if (WindowsControl is RadioButton rb && true == Alive(rb))
                    retVal = OnUiRead(rb, () => rb.Checked, retVal);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is RadioButton rb && true == Alive(rb))
                {
                    OnUi(rb, () => rb.Checked = value);
                }
                else
                {
                    IsChecked = value;
                }
            }
        }
    }

    public class GPALTab : GPALControl, IAllowControlSettings
    {
        internal GPALTab()
        {
            ControlType = FormControlType.Tab;
        }
        public override bool Enabled
        {
            get
            {
                // a GPALTab is one page, and its control is the TabPage. asking the TabControl would answer
                // for every tab at once
                bool retVal = IsEnabled;
 
                if (WindowsControl is TabPage page && true == Alive(page))
                    retVal = OnUiRead(page, () => page.Enabled, retVal);
 
                return retVal;
            }
            set
            {
                IsEnabled = value;
 
                if (!(WindowsControl is TabPage page) || false == Alive(page)) return;
 
                OnUi(page, () => page.Enabled = value);
            }
        }
        public void Activate()
        {
            // marshalled like every other control setter: a workflow thread is where this gets called from,
            // and switching tabs from one is a cross thread call into the form
            if (WindowsControl is TabPage tabPage && tabPage.Parent is TabControl tabControl)
                OnUi(tabControl, () => tabControl.SelectedTab = tabPage);
        }
    }

    public class GPALSpliter
    {
        internal GPALSpliter() { }
    }

    public class GPALSplitter : GPALControl, IAllowSplitterControlSettings
    {
        internal bool IsHorizontalSplit { get; private set; } = true;
        internal int Dimension { get; private set; }
        internal double Percentage { get; private set; }
        internal bool IsPercentage => 0 < Percentage;
        internal List<object> FormControls { get; } = new List<object>();
 
        internal GPALSplitter() { }

        public new IAllowSplitterControlSettings WithHeight(int height)
        {
            Height = height;
            return this;
        }
        public IAllowSplitterControlSettings HSplit(int leftWidth)
        {
            IsHorizontalSplit = true;
            Dimension = leftWidth;
            return this;
        }
        public IAllowSplitterControlSettings HSplit(double leftPercent)
        {
            IsHorizontalSplit = true;
            Percentage = leftPercent;
            return this;
        }

        public IAllowSplitterControlSettings VSplit(int topHeight)
        {
            IsHorizontalSplit = false;
            Dimension = topHeight;
            return this;
        }

        public IAllowSplitterControlSettings VSplit(double topPercent)
        {
            IsHorizontalSplit = false;
            Percentage = topPercent;
            return this;
        }

        public IAllowSplitterControlSettings WithFormControl(object gPALFormControl)
        {
            FormControls.Add(gPALFormControl);
            return this;
        }

        public new GPALSplitter ToGPALObject()
        {
            return this;
        }
    }

    public class GPALGroupBox : GPALControl, IAllowGroupBoxControlSettings
    {
        internal List<object> FormControls { get; } = new List<object>();
 
        internal GPALGroupBox() { }

        public new IAllowGroupBoxControlSettings WithText(string text)
        {
            Text = text;
            return this;
        }

        public IAllowGroupBoxControlSettings WithFormControl(object gPALFormControl)
        {
            FormControls.Add(gPALFormControl);
            return this;
        }

        public new GPALGroupBox ToGPALObject()
        {
            return this;
        }
    }

    public class GPALTableLayoutPanel : GPALControl, IAllowControlSettingsAndTableLayoutPanelSettings
    {
        internal GPALTableLayoutPanel()
        {
            ControlType = FormControlType.TableLayoutPanel;
        }
 
        // what the panel is set to before the form is built, the way IsEnabled backs Enabled. Each of the three
        // properties below used to name itself in its own else branch, so reading or writing one on a control
        // that had no WindowsControl yet recursed until the stack was gone, which is a StackOverflowException
        // and cannot be caught. The defaults are the WinForms ones
        private TableLayoutPanelGrowStyle growStyle = TableLayoutPanelGrowStyle.AddRows;
        private int columnCount = 0;
        private int rowCount = 0;
        public TableLayoutPanelGrowStyle GrowStyle
        {
            get
            {
                TableLayoutPanelGrowStyle retVal = growStyle;
 
                if (WindowsControl is TableLayoutPanel panel && true == Alive(panel))
                    retVal = OnUiRead(panel, () => panel.GrowStyle, retVal);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is TableLayoutPanel panel && true == Alive(panel))
                    OnUi(panel, () => panel.GrowStyle = value);
 
                growStyle = value;   // kept either way, so the value survives the control not being there yet
            }
        }

        public int ColumnCount
        {
            get
            {
                int retVal = columnCount;
 
                if (WindowsControl is TableLayoutPanel panel && true == Alive(panel))
                    retVal = OnUiRead(panel, () => panel.ColumnCount, retVal);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is TableLayoutPanel panel && true == Alive(panel))
                    OnUi(panel, () => panel.ColumnCount = value);
 
                columnCount = value;   // kept either way, so the value survives the control not being there yet
            }
        }

        public int RowCount
        {
            get
            {
                int retVal = rowCount;
 
                if (WindowsControl is TableLayoutPanel panel && true == Alive(panel))
                    retVal = OnUiRead(panel, () => panel.RowCount, retVal);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is TableLayoutPanel panel && true == Alive(panel))
                    OnUi(panel, () => panel.RowCount = value);
 
                rowCount = value;   // kept either way, so the value survives the control not being there yet
            }
        }
 

        public IAllowControlSettingsAndTableLayoutPanelSettings WithColumnCount(int columnCount)
        {
            ColumnCount = columnCount;
            return this;
        }

        public new IAllowControlSettingsAndTableLayoutPanelSettings WithEnabled(bool enabled = true)
        {
            this.Enabled = enabled;
            return this;
        }

        public IAllowControlSettingsAndTableLayoutPanelSettings WithGrowStyle(TableLayoutPanelGrowStyle tableLayoutPanelGrowStyle)
        {
            this.GrowStyle = tableLayoutPanelGrowStyle;
            return this;
        }

        public IAllowControlSettingsAndTableLayoutPanelSettings WithRowCount(int rowCount)
        {
            RowCount = rowCount;
            return this;
        }
    }

    public class GPALTextArea : GPALControl, IAllowControlSettingsAndPlaceholder
    {
        internal string PlaceHolder { get; set; }
 
        // lines wait here until the thread that owns the control is free to take them. see AppendLine
 
        internal GPALTextArea()
        {
            ControlType = FormControlType.TextArea;
        }
 
        public IAllowControlSettingsAndPlaceholder WithPlaceholder(string PlaceholderText)
        {
            PlaceHolder = PlaceholderText;
            if (WindowsControl is PlaceholderTextBox tb && true == Alive(tb))
                tb.PlaceholderText = PlaceholderText;
            return this;
        }
 
        public override IAllowControlSettings WithReadOnly(bool readOnly = true)
        {
            IsReadOnly = readOnly;
            if (WindowsControl is PlaceholderTextBox tb && true == Alive(tb))
                tb.ReadOnly = readOnly;
            return this;
        }

        public void AppendLine(string text, int maxLines = 0) => AppendLineCore(text, maxLines);

        public void Clear() => ClearLinesCore();

        public void ScrollToEnd() => ScrollToEndCore();
    }

    public class GPALRichTextBox : GPALControl, IAllowRichTextBoxControlSettings
    {
        private string _text = string.Empty;
 
        internal GPALRichTextBox()
        {
            ControlType = FormControlType.RichTextBox;
            // a rich text box is a rendered view of markdown, so it is read only until told otherwise
            IsReadOnly = true;
        }

        public new string Text
        {
            get => _text;
            set
            {
                _text = value ?? string.Empty;
                if (WindowsControl is RichTextBox rtb && true == Alive(rtb))
                {
                    PostToUi(rtb, () => RenderMarkdown(rtb, _text));
                }
            }
        }

        public void AppendLine(string text, int maxLines = 0)
        {
            _text = 0 == _text.Length ? text : _text + Environment.NewLine + text;
 
            AppendLineCore(text, maxLines);
        }

        public void Clear()
        {
            _text = string.Empty;
 
            ClearLinesCore();
        }

        public void ScrollToEnd() => ScrollToEndCore();

        public new IAllowRichTextBoxControlSettings WithText(string text)
        {
            this.Text = text;
            return this;
        }
 
 
        public override IAllowControlSettings WithReadOnly(bool readOnly = true)
        {
            IsReadOnly = readOnly;
            if (WindowsControl is RichTextBox rtb && true == Alive(rtb))
                rtb.ReadOnly = readOnly;
            return this;
        }
 
        // matches **bold**, *italic*, __underline__, ~~strikethrough~~, `code`, {colorname}text{} — bold before italic to avoid ** ambiguity
        private static readonly Regex _inlinePattern = new Regex(
            @"\*\*(?<b>.+?)\*\*|\*(?<i>.+?)\*|__(?<u>.+?)__|~~(?<s>.+?)~~|`(?<code>.+?)`|{(?<c>[^}]+)}(?<ct>.+?)\{\}",
            RegexOptions.Compiled);

        // the fonts a render asks for, kept rather than made again. A render writes a font per styled run and
        // setting SelectionFont copies what it needs out of the font, so one instance serves every run that
        // wants the same family, size and style. Made fresh each time they were never disposed, and a font
        // holds a GDI handle: a form that keeps appending to a rich text box re-renders the whole document
        // each time, so the handles ran out and the next thing the control was asked to do threw
        private static readonly Dictionary<string, Font> renderFonts = new Dictionary<string, Font>();
        private static readonly object renderFontGate = new object();

        private static Font RenderFont(string family, float size, FontStyle style)
        {
            string key = $"{family}|{size}|{(int)style}";
            Font retVal;
 
            lock (renderFontGate)
            {
                if (false == renderFonts.TryGetValue(key, out retVal))
                {
                    retVal = new Font(family, size, style);
                    renderFonts[key] = retVal;
                }
            }
 
            return retVal;
        }
 
        internal static void RenderMarkdown(RichTextBox rtb, string markdown)
        {
            rtb.Clear();
 
            Font baseFont = rtb.Font;
            Color baseColor = rtb.ForeColor;
            string codeFamily = "Courier New";
            string[] lines = (markdown ?? string.Empty).Replace("\r\n", "\n").Split('\n');
 
            foreach (string rawLine in lines)
            {
                string line = rawLine;
 
                int headingLevel = 0;
                while (headingLevel < line.Length && line[headingLevel] == '#')
                    headingLevel++;
                if (headingLevel > 0 && headingLevel <= 3 && headingLevel < line.Length && line[headingLevel] == ' ')
                    line = line.Substring(headingLevel + 1);
                else
                    headingLevel = 0;
 
                int leadingSpaces = 0;
                while (leadingSpaces < line.Length && line[leadingSpaces] == ' ')
                    leadingSpaces++;
                int indentLevel = leadingSpaces / 2;
                string trimmed = line.Substring(leadingSpaces);
 
                // horizontal rule
                if (trimmed == "---")
                {
                    rtb.SelectionStart = rtb.TextLength;
                    rtb.SelectionLength = 0;
                    rtb.SelectionFont = RenderFont(baseFont.FontFamily.Name, baseFont.Size, FontStyle.Regular);
                    rtb.SelectionColor = Color.Gray;
                    rtb.AppendText(new string('-', 48) + "\n");
                    continue;
                }
 
                bool isBulletItem = false;
                bool isListItem = false;
                if (trimmed.StartsWith("- ") || trimmed.StartsWith("* "))
                {
                    isBulletItem = true;
                    isListItem = true;
                    trimmed = trimmed.Substring(2);
                }
                else
                {
                    Match numberedMatch = Regex.Match(trimmed, @"^(\d+\.\s+)(.*)$");
                    if (numberedMatch.Success)
                    {
                        isListItem = true;
                        trimmed = numberedMatch.Groups[1].Value + numberedMatch.Groups[2].Value;
                    }
                }
 
                int lineStart = rtb.TextLength;
 
                FontStyle headingBase = headingLevel > 0 ? FontStyle.Bold : FontStyle.Regular;
                float headingSize = headingLevel > 0 ? baseFont.Size + (4 - headingLevel) * 2 : baseFont.Size;
 
                foreach ((string segmentText, FontStyle style, Color? color, bool isCode) in SplitInline(trimmed, headingBase))
                {
                    rtb.SelectionStart = rtb.TextLength;
                    rtb.SelectionLength = 0;
                    rtb.SelectionFont = isCode
                        ? RenderFont(codeFamily, baseFont.Size, FontStyle.Regular)
                        : RenderFont(baseFont.FontFamily.Name, headingSize, style);
                    rtb.SelectionColor = isCode ? Color.SteelBlue : (color ?? baseColor);
                    rtb.AppendText(segmentText);
                }
                rtb.AppendText("\n");
 
                if (isListItem)
                {
                    rtb.SelectionStart = lineStart;
                    rtb.SelectionLength = rtb.TextLength - lineStart;
                    rtb.SelectionBullet = isBulletItem;
                    rtb.SelectionIndent = 20 * (indentLevel + 1);
                }
            }
 
            rtb.SelectionStart = 0;
            rtb.SelectionLength = 0;
        }

        private static List<(string Text, FontStyle Style, Color? Color, bool IsCode)> SplitInline(string line, FontStyle inheritBase = FontStyle.Regular)
        {
            var result = new List<(string Text, FontStyle Style, Color? Color, bool IsCode)>();
            int pos = 0;
 
            foreach (Match m in _inlinePattern.Matches(line))
            {
                if (m.Index > pos)
                    result.Add((line.Substring(pos, m.Index - pos), inheritBase, null, false));
 
                if (m.Groups["b"].Success)
                    result.Add((m.Groups["b"].Value, inheritBase | FontStyle.Bold, null, false));
                else if (m.Groups["i"].Success)
                    result.Add((m.Groups["i"].Value, inheritBase | FontStyle.Italic, null, false));
                else if (m.Groups["u"].Success)
                    result.Add((m.Groups["u"].Value, inheritBase | FontStyle.Underline, null, false));
                else if (m.Groups["s"].Success)
                    result.Add((m.Groups["s"].Value, inheritBase | FontStyle.Strikeout, null, false));
                else if (m.Groups["code"].Success)
                    result.Add((m.Groups["code"].Value, FontStyle.Regular, null, true));
                else if (m.Groups["c"].Success)
                {
                    Color named = Color.FromName(m.Groups["c"].Value);
                    Color? resolved = named.IsKnownColor || named.A > 0 ? (Color?)named : null;
                    // recurse so bold/italic/underline inside a color span still render correctly
                    foreach (var inner in SplitInline(m.Groups["ct"].Value, inheritBase))
                        result.Add((inner.Item1, inner.Item2, inner.Item3 ?? resolved, inner.Item4));
                }
 
                pos = m.Index + m.Length;
            }
 
            if (pos < line.Length)
                result.Add((line.Substring(pos), inheritBase, null, false));
            if (result.Count == 0)
                result.Add((string.Empty, inheritBase, null, false));
 
            return result;
        }
    }

    public class GPALComboBox : GPALControl, IAllowComboBoxControlSettings
    {
        internal readonly List<string> items = new List<string>();
        internal int selectedIndex = -1;
        internal string selectedItem = null;
 
        // items that stay on the list but cannot be chosen. an option that does not apply is worth showing
        // greyed, because a list that silently loses an entry reads as a list that never had one
        internal readonly HashSet<string> disabledItems = new HashSet<string>();
 
        // what to fall back to when a disabled item is picked, so the box never sits on something invalid
        internal int lastEnabledIndex = -1;
 
        internal GPALComboBox() 
        {
            ControlType = FormControlType.ComboBox;
        }

        public IAllowComboBoxControlSettings WithItems(params string[] itemArray)
        {
            if (null != itemArray)
            {
                items.AddRange(itemArray);
                ShowItems(itemArray);
            }
            return this;
        }
 
        // the list a form was built with is one thing and the list on screen is another. adding items before
        // the form is shown only has the first to add to; adding them after has both, and a dropdown that does
        // not change is the whole reason a list would look stale
        private void ShowItems(IEnumerable<string> itemsToShow)
        {
            if (!(WindowsControl is ComboBox cb) || false == Alive(cb)) return;
 
            object[] adding = itemsToShow.Cast<object>().ToArray();
 
            OnUi(cb, () => cb.Items.AddRange(adding));
        }

        public void DisableItem(string item)
        {
            if (true == string.IsNullOrEmpty(item)) return;
 
            disabledItems.Add(item);
            Redraw();
        }

        public void EnableItem(string item)
        {
            if (true == string.IsNullOrEmpty(item)) return;
 
            disabledItems.Remove(item);
            Redraw();
        }

        public bool IsItemEnabled(string item)
        {
            return false == disabledItems.Contains(item);
        }
 
        private void Redraw()
        {
            if (!(WindowsControl is ComboBox cb) || false == Alive(cb)) return;
 
            OnUi(cb, () => cb.Invalidate());
        }

        public void ClearItems()
        {
            items.Clear();
            disabledItems.Clear();
            selectedIndex = -1;
            selectedItem = null;
            lastEnabledIndex = -1;
 
            if (!(WindowsControl is ComboBox cb) || false == Alive(cb)) return;
 
            OnUi(cb, () => cb.Items.Clear());
        }

        public IAllowComboBoxControlSettings WithItems(IEnumerable<string> itemCollection)
        {
            if (null != itemCollection)
            {
                items.AddRange(itemCollection);
            }
            return this;
        }

        public IAllowComboBoxControlSettings WithItems(Array itemArray)
        {
            if (null != itemArray)
            {
                foreach (object item in itemArray)
                    items.Add(item?.ToString() ?? string.Empty);
            }
            return this;
        }

        public IAllowComboBoxControlSettings WithSelectedIndex(int index)
        {
            selectedIndex = index;
            selectedItem = null;
            return this;
        }

        public IAllowComboBoxControlSettings WithSelectedItem(string name)
        {
            selectedItem = name;
            selectedIndex = -1;
            return this;
        }

        public string SelectedValue
        {
            get
            {
                int idx = SelectedIndex;
                if ((0 > idx) || (idx >= items.Count))
                    return null;
                return items[idx];
            }
        }

 
        public int SelectedIndex
        {
            // read on the ui thread when asked from another one, the way every setter here already writes on it.
            // a workflow running off the ui thread is the normal case, not an odd one
            get
            {
                int retVal = selectedIndex;
 
                if (WindowsControl is ComboBox cb && true == Alive(cb))
                    retVal = OnUiRead(cb, () => cb.SelectedIndex, retVal);
 
                return retVal;
            }
            set
            {
                if ((0 > value) || (value >= items.Count)) return;
 
                selectedIndex = value;
                if (WindowsControl is ComboBox cb && true == Alive(cb))
                {
                    OnUi(cb, () => cb.SelectedIndex = value);
                }
            }
        }
    }

    public class GPALPicture : GPALControl, IAllowPictureControlSettings
    {
        private System.Drawing.Image _image;
        private PictureBoxSizeMode _sizeMode = PictureBoxSizeMode.Zoom;
 
        internal GPALPicture()
        {
            ControlType = FormControlType.Picture;
        }

        public System.Drawing.Image Image => _image;

        public PictureBoxSizeMode SizeMode => _sizeMode;

        public IAllowPictureControlSettings WithImage(System.Drawing.Image image)
        {
            _image = image;
            SyncImageToControl();
            return this;
        }

        public IAllowPictureControlSettings WithImage(GPALFile file)
        {
            if (true == System.IO.File.Exists(file?.Filename))
                using (var stream = new System.IO.MemoryStream(System.IO.File.ReadAllBytes(file.Filename)))
                    _image = new Bitmap(System.Drawing.Image.FromStream(stream));
            else
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Image file not found for picture [{file?.Filename}]", this, GPALObjectType.Other);
 
            SyncImageToControl();
            return this;
        }

        public IAllowPictureControlSettings WithSizeMode(PictureBoxSizeMode sizeMode)
        {
            _sizeMode = sizeMode;
            SyncImageToControl();
            return this;
        }

        private void SyncImageToControl()
        {
            if (WindowsControl is PictureBox box && true == Alive(box))
                OnUi(box, () =>
                {
                    box.SizeMode = _sizeMode;
                    box.Image = _image;
                });
        }
    }

    public class GPALSlider : GPALControl, IAllowSliderControlSettings
    {
        private int _value = 0;
        private int _minimum = 0;
        private int _maximum = 100;
        private int _tickFrequency = 10;
        private Orientation _orientation = Orientation.Horizontal;
 
        internal GPALSlider()
        {
            ControlType = FormControlType.Slider;
        }

        public int Value
        {
            get => OnUiRead(WindowsControl as TrackBar, () => ((TrackBar)WindowsControl).Value, _value);
 
            set
            {
                _value = value < _minimum ? _minimum : value > _maximum ? _maximum : value;
 
                SyncToControl();
            }
        }

        public int Minimum => _minimum;

        public int Maximum => _maximum;

        public int TickFrequency => _tickFrequency;

        public Orientation Orientation => _orientation;

        public IAllowSliderControlSettings WithMinimum(int min)
        {
            _minimum = min;
 
            if (_value < min)
                _value = min;
 
            SyncToControl();
            return this;
        }

        public IAllowSliderControlSettings WithMaximum(int max)
        {
            _maximum = max;
 
            if (_value > max)
                _value = max;
 
            SyncToControl();
            return this;
        }

        public IAllowSliderControlSettings WithValue(int value)
        {
            Value = value;
            return this;
        }

        public IAllowSliderControlSettings WithTickFrequency(int tickFrequency)
        {
            _tickFrequency = tickFrequency;
 
            SyncToControl();
            return this;
        }

        public IAllowSliderControlSettings WithOrientation(Orientation orientation)
        {
            _orientation = orientation;
 
            SyncToControl();
            return this;
        }

        private void SyncToControl()
        {
            if (WindowsControl is TrackBar bar && true == Alive(bar))
                OnUi(bar, () =>
                {
                    bar.Minimum = _minimum;
                    bar.Maximum = _maximum;
                    bar.TickFrequency = 1 > _tickFrequency ? 1 : _tickFrequency;
                    bar.Orientation = _orientation;
                    bar.Value = _value;
                });
        }
    }
 
    public class GPALProgressBar : GPALControl, IAllowProgressBarControlSettings
    {
        private int _value = 0;
        private int _minimum = 0;
        private int _maximum = 100;
        private ProgressBarStyle _style = ProgressBarStyle.Blocks;
 
        internal GPALProgressBar()
        {
            ControlType = FormControlType.ProgressBar;
        }

        public IAllowProgressBarControlSettings WithValue(int value)
        {
            this.Value = value;
            return this;
        }

        public IAllowProgressBarControlSettings WithMinimum(int min)
        {
            _minimum = min;
            if (_value < min) _value = min;
            SyncValueToControl();
            return this;
        }

        public IAllowProgressBarControlSettings WithMaximum(int max)
        {
            _maximum = max;
            if (_value > max) _value = max;
            SyncValueToControl();
            return this;
        }

        public IAllowProgressBarControlSettings WithStyle(ProgressBarStyle style)
        {
            this.Style = style;
            return this;
        }

        public void Increment(int step = 1)
        {
            this.Value += step;
        }

        private void SyncValueToControl()
        {
            if (WindowsControl is ProgressBar pb && true == Alive(pb))
            {
                OnUi(pb, () => Apply(pb));
            }
        }

        private void Apply(ProgressBar pb)
        {
            // maximum first when it is going up, minimum first when it is coming down, because the control
            // refuses a minimum above its own maximum and a maximum below its own minimum
            if (pb.Maximum < _maximum)
            {
                pb.Maximum = _maximum;
                pb.Minimum = _minimum;
            }
            else
            {
                pb.Minimum = _minimum;
                pb.Maximum = _maximum;
            }
 
            pb.Value = _value;
        }

        private void SyncStyleToControl()
        {
            if (WindowsControl is ProgressBar pb && true == Alive(pb))
            {
                OnUi(pb, () => pb.Style = _style);
            }
        }

        public int Value
        {
            get => _value;
            set
            {
                _value = Math.Max(_minimum, Math.Min(_maximum, value));
                SyncValueToControl();
            }
        }

        public int Minimum => _minimum;
        public int Maximum => _maximum;
        public ProgressBarStyle Style
        {
            get => _style;
            set
            {
                _style = value;
                SyncStyleToControl();
            }
        }
    }

    public class GPALStatusStrip : GPALControl, IAllowStatusStripControlSettings
    {
        private string _text = "";
 
        internal GPALStatusStrip()
        {
            ControlType = FormControlType.StatusStrip;
        }

        public new string Text
        {
            get => _text;
            set
            {
                _text = value ?? "";
                SyncTextToControl();
            }
        }

        public new IAllowStatusStripControlSettings WithText(string text)
        {
            this.Text = text;
            return this;
        }

        private void SyncTextToControl()
        {
            if (WindowsControl is StatusStrip strip && true == Alive(strip) && strip.Items.Count > 0)
            {
                ToolStripStatusLabel label = strip.Items[0] as ToolStripStatusLabel;
                if (label != null)
                {
                    PostToUi(strip, () => label.Text = _text);
                }
            }
        }
    }

    public class GPALBarItem : GPALControl, IAllowBarItemSettings
    {
        internal System.Drawing.Image Image { get; set; }
 
        internal GPALBarItem()
        {
            ControlType = FormControlType.BarItem;
        }

        public new IAllowBarItemSettings WithEnabled(bool trueFalse = true)
        {
            Enabled = trueFalse;
            return this;
        }

        public override bool Enabled
        {
            get
            {
                return WindowsControl is ToolStripItem strip ? strip.Enabled : IsEnabled;
            }
            set
            {
                IsEnabled = value;
 
                if (!(WindowsControl is ToolStripItem strip)) return;
 
                // a ToolStripItem is not a Control and has no InvokeRequired of its own. the strip that owns
                // it is one, and that is what has to be asked whether this is the right thread
                Control owner = strip.Owner;
 
                OnUiOrHere(owner, () => strip.Enabled = value);
            }
        }

        public new IAllowBarItemSettings WithText(string text)
        {
            this.Text = text;
            return this;
        }

        public IAllowBarItemSettings WithImage(System.Drawing.Image image)
        {
            this.Image = image;
            return this;
        }

        public IAllowBarItemSettings WithImage(GPALFile file)
        {
            try
            {
                string path = file?.Filenames?.FirstOrDefault() ?? (string)file;
                if (!string.IsNullOrWhiteSpace(path) && System.IO.File.Exists(path))
                    this.Image = System.Drawing.Image.FromFile(path);
                else
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Image file not found for bar item [{path}]", this, GPALObjectType.Other);
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Failed to load bar item image [{file?.Filename}]", this, GPALObjectType.Other, ex);
            }
            return this;
        }
    }

    public class GPALMenuBar : GPALControl, IAllowMenuBarControlSettings
    {
        private string _currentMenu;
        internal readonly List<(string TopMenu, GPALBarItem Item, bool IsSeparator)> menuEntries
            = new List<(string, GPALBarItem, bool)>();
 
        internal GPALMenuBar()
        {
            ControlType = FormControlType.MenuBar;
        }

        public IAllowMenuBarControlSettings WithMenu(string topMenu)
        {
            _currentMenu = topMenu;
            return this;
        }

        public IAllowMenuBarControlSettings WithItem(GPALBarItem item)
        {
            menuEntries.Add((_currentMenu, item, false));
            return this;
        }

        public IAllowMenuBarControlSettings WithSeparator()
        {
            menuEntries.Add((_currentMenu, null, true));
            return this;
        }
    }

    public class GPALToolbar : GPALControl, IAllowToolbarControlSettings
    {
        internal readonly List<(GPALBarItem Item, bool IsSeparator)> toolbarEntries
            = new List<(GPALBarItem, bool)>();
 
        internal GPALToolbar()
        {
            ControlType = FormControlType.Toolbar;
        }

        public IAllowToolbarControlSettings WithItem(GPALBarItem item)
        {
            toolbarEntries.Add((item, false));
            return this;
        }

        public IAllowToolbarControlSettings WithSeparator()
        {
            toolbarEntries.Add((null, true));
            return this;
        }
    }

    public class GPALListView : GPALControl, IAllowListViewControlSettings
    {
        private readonly List<string> columnHeaders = new List<string>();
        private readonly List<double> columnWeights = new List<double>();
        private ListViewMode viewMode = ListViewMode.Details;
        internal bool checkBoxes = false;
        private bool fullRowSelect = true;
        private bool multiSelect = false;
        private bool sortable = false;
 
        internal GPALListView()
        {
            ControlType = FormControlType.ListView;
        }

        public IAllowListViewControlSettings WithCheckBoxes(bool enable = true)
        {
            CheckBoxes = enable;
            return this;
        }

        public bool CheckBoxes
        {
            get
            {
                return WindowsControl is ListView lv ? lv.CheckBoxes : checkBoxes;
            }
            set
            {
                checkBoxes = value;
 
                if (!(WindowsControl is ListView lv) || false == Alive(lv)) return;
 
                OnUi(lv, () => lv.CheckBoxes = value);
            }
        }
 
        public IAllowListViewControlSettings WithColumns(params string[] headers)
        {
            if (headers != null)
            {
                columnHeaders.AddRange(headers);
            }
            return this;
        }

        public IAllowListViewControlSettings WithView(ListViewMode view)
        {
            viewMode = view;
            return this;
        }

        public IAllowListViewControlSettings WithFullRowSelect(bool enable)
        {
            fullRowSelect = enable;
            return this;
        }

        public IAllowListViewControlSettings WithMultiSelect(bool enable)
        {
            multiSelect = enable;
            return this;
        }

        public IAllowListViewControlSettings WithSortable(bool sortable = true)
        {
            this.sortable = sortable;
            return this;
        }

        public IAllowListViewControlSettings WithColumnWeight(double weight)
        {
            columnWeights.Add(weight);
            return this;
        }

        public IReadOnlyList<string> Columns => columnHeaders.AsReadOnly();

        public IReadOnlyList<double> ColumnWeights => columnWeights.AsReadOnly();

        public bool Sortable => sortable;
        public View ViewMode
        {
            get
            {
                switch (viewMode)
                {
                    case ListViewMode.List:      return View.List;
                    case ListViewMode.LargeIcon: return View.LargeIcon;
                    case ListViewMode.SmallIcon: return View.SmallIcon;
                    case ListViewMode.Tile:      return View.Tile;
                    default:                     return View.Details;
                }
            }
        }

        public bool FullRowSelect => fullRowSelect;
        public bool MultiSelect => multiSelect;
 
        public int SelectedIndex
        {
            get
            {
                int retVal = -1;
 
                if (WindowsControl is ListView lv && true == Alive(lv))
                    retVal = OnUiRead(lv, () => 0 < lv.SelectedItems.Count ? lv.SelectedItems[0].Index : -1, retVal);
 
                return retVal;
            }
        }
 
        public void ClearItems()
        {
            if (!(WindowsControl is ListView lv) || false == Alive(lv)) return;
            OnUi(lv, () => lv.Items.Clear());
        }

        public void DisableItem(int index)
        {
            SetItemEnabled(index, false);
        }

        public void EnableItem(int index)
        {
            SetItemEnabled(index, true);
        }

        public bool IsItemEnabled(int index)
        {
            bool retVal = true;
 
            if (!(WindowsControl is ListView lv) || false == Alive(lv)) return retVal;
 
            MethodInvoker read = () =>
            {
                if (0 <= index && index < lv.Items.Count)
                    retVal = SystemColors.GrayText != lv.Items[index].ForeColor;
            };
 
            OnUi(lv, read);
 
            return retVal;
        }
 
        // the colour is the state, so what a row looks like and what it does can never disagree
        private void SetItemEnabled(int index, bool enabled)
        {
            if (!(WindowsControl is ListView lv) || false == Alive(lv)) return;
 
            MethodInvoker paint = () =>
            {
                if (0 > index || index >= lv.Items.Count) return;
 
                lv.Items[index].ForeColor = true == enabled ? SystemColors.WindowText : SystemColors.GrayText;
 
                if (false == enabled) lv.Items[index].Selected = false;
            };
 
            OnUi(lv, paint);
        }
 
        public void AddItem(string title, params string[] subItems)
        {
            // rows added before the form built the list are held until it exists rather than dropped. A
            // workflow that fills a list at startup is the ordinary case, and losing those rows silently is
            // the kind of thing that reads as an empty list with nothing to explain it
            if (!(WindowsControl is ListView lv) || false == Alive(lv))
            {
                pendingRows.Enqueue(new Tuple<string, string[]>(title, subItems ?? new string[0]));
                return;
            }
 
            var item = new ListViewItem(title);
            foreach (var s in subItems) item.SubItems.Add(s);
            OnUi(lv, () => lv.Items.Add(item));
        }
 
        // what was added before the list existed, in the order it was added
        private readonly System.Collections.Concurrent.ConcurrentQueue<Tuple<string, string[]>> pendingRows =
            new System.Collections.Concurrent.ConcurrentQueue<Tuple<string, string[]>>();

        internal override void Realized()
        {
            while (true == pendingRows.TryDequeue(out Tuple<string, string[]> held))
                AddItem(held.Item1, held.Item2);
 
            // a list on a tab nobody has opened has no handle, so every fit asked for before now was refused.
            // The handle arrives when the tab is first shown, and the rows are measurable from then on
            if (WindowsControl is ListView lv)
            {
                lv.HandleCreated += (sender, args) => LayOutColumns();
                lv.VisibleChanged += (sender, args) => LayOutColumns();
                lv.Resize += (sender, args) => LayOutColumns();
            }
        }
 

        public IAllowListViewControlSettings WithColumnWidth(params double[] shares)
        {
            columnWeights.Clear();
 
            if (null != shares)
                columnWeights.AddRange(shares);
 
            return this;
        }
 
        // how wide each column is, in column order. Empty leaves every column as the control makes it
        internal readonly List<int> _columnWidths = new List<int>();

        public IAllowListViewControlSettings WithColumnWidth(params int[] widths)
        {
            _columnWidths.Clear();
 
            if (null != widths)
                _columnWidths.AddRange(widths);
 
            ApplyColumnWidths();
 
            return this;
        }
 
        // whether a workflow said anything about the widths at all. With shares, the form reflows them on
        // every resize and this stays out of the way: two handlers pulling the same column two ways is what
        // the old code did
        internal bool LastColumnFills => 0 == columnWeights.Count;
 
        // how far short of the edge the last column stops, so a row never tips the control into a horizontal
        // scrollbar as the form is dragged narrower
        internal const int FillMargin = 2;
 
        // narrow enough to be a column, wide enough to be clicked on
        private const int NarrowestColumn = 24;
 
        // laying a column out lays the control out again, which raises the resize this runs from
        private bool layingOut = false;

        internal void LayOutColumns()
        {
            if (!(WindowsControl is ListView lv) || false == Alive(lv) || 0 < columnWeights.Count)
                return;
 
            if (true == lv.InvokeRequired)
            {
                OnUi(lv, LayOutColumns);
                return;
            }
 
            if (false == lv.IsHandleCreated || 0 == lv.Columns.Count || true == layingOut)
                return;
 
            layingOut = true;
 
            try
            {
                int available = Math.Max(NarrowestColumn * lv.Columns.Count, lv.ClientSize.Width - FillMargin);
                int[] widths = new int[lv.Columns.Count];
                int named = 0;
                int unnamed = 0;
 
                // a named width is a positive number. A sentinel, a zero, or a column nobody mentioned is one
                // of the columns that shares what is left
                for (int column = 0; column < widths.Length; column++)
                    if (column < _columnWidths.Count && 0 < _columnWidths[column])
                    {
                        widths[column] = _columnWidths[column];
                        named += widths[column];
                    }
                    else
                        unnamed++;
 
                if (0 < unnamed)
                {
                    int each = Math.Max(NarrowestColumn, (available - named) / unnamed);
 
                    for (int column = 0; column < widths.Length; column++)
                        if (0 == widths[column])
                            widths[column] = each;
                }
 
                // wider than the control, so everything comes down together rather than the last column being
                // squeezed on its own or a scrollbar appearing
                int total = 0;
 
                foreach (int width in widths)
                    total += width;
 
                if (available < total && 0 < total)
                {
                    for (int column = 0; column < widths.Length; column++)
                        widths[column] = Math.Max(NarrowestColumn, widths[column] * available / total);
 
                    total = 0;
 
                    foreach (int width in widths)
                        total += width;
                }
 
                // the last column ends the row at the edge, which is what -2 was always standing in for
                widths[widths.Length - 1] += available - total;
 
                if (NarrowestColumn > widths[widths.Length - 1])
                    widths[widths.Length - 1] = NarrowestColumn;
 
                for (int column = 0; column < widths.Length; column++)
                    lv.Columns[column].Width = widths[column];
            }
            finally
            {
                layingOut = false;
            }
        }
 
// the widths are given before the form is built and again after, because a control that does not exist
        // yet cannot be told anything and one that already does will not be rebuilt
        internal void ApplyColumnWidths()
        {
            LayOutColumns();
        }

        public string SelectedText
        {
            get
            {
                string retVal = null;
 
                // read on the ui thread and guarded, the way SelectedIndex above already is. Read raw it could
                // throw or answer with a half-updated selection when a workflow thread asked
                if (WindowsControl is ListView lv && true == Alive(lv))
                    retVal = OnUiRead(lv, () => 0 < lv.SelectedItems.Count ? lv.SelectedItems[0].Text : null, retVal);
 
                return retVal;
            }
        }

        public IReadOnlyList<bool> CheckedItems
        {
            get
            {
                List<bool> retVal = new List<bool>();
 
                if (WindowsControl is ListView lv && true == Alive(lv))
                    retVal = OnUiRead(lv, () =>
                    {
                        List<bool> ticked = new List<bool>();
 
                        foreach (ListViewItem item in lv.Items)
                            ticked.Add(item.Checked);
 
                        return ticked;
                    }, retVal);
 
                return retVal.AsReadOnly();
            }
        }

        public IReadOnlyList<bool> SelectedItems
        {
            get
            {
                List<bool> retVal = new List<bool>();
 
                if (WindowsControl is ListView lv && true == Alive(lv))
                    retVal = OnUiRead(lv, () =>
                    {
                        List<bool> chosen = new List<bool>();
 
                        foreach (ListViewItem item in lv.Items)
                            chosen.Add(item.Selected);
 
                        return chosen;
                    }, retVal);
 
                return retVal.AsReadOnly();
            }
        }
    }

    public class GPALNumericUpDown : GPALControl, IAllowNumericUpDownControlSettings
    {
        private decimal _value = 0m;
        private decimal _minimum = 0m;
        private decimal _maximum = 100m;
        private decimal _increment = 1m;
        private int _decimalPlaces = 0;
 
        internal GPALNumericUpDown()
        {
            ControlType = FormControlType.NumericUpDown;
        }

        public IAllowNumericUpDownControlSettings WithValue(decimal value)
        {
            _value = value;
            return this;
        }

        public IAllowNumericUpDownControlSettings WithMinimum(decimal min)
        {
            _minimum = min;
            return this;
        }

        public IAllowNumericUpDownControlSettings WithMaximum(decimal max)
        {
            _maximum = max;
            return this;
        }

        public IAllowNumericUpDownControlSettings WithIncrement(decimal inc)
        {
            _increment = inc;
            return this;
        }

        public IAllowNumericUpDownControlSettings WithDecimalPlaces(int places)
        {
            _decimalPlaces = places;
            return this;
        }

        public decimal Value
        {
            get
            {
                decimal retVal = _value;
 
                if (WindowsControl is NumericUpDown nud && true == Alive(nud))
                    retVal = OnUiRead(nud, () => nud.Value, retVal);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is NumericUpDown nud && true == Alive(nud))
                {
                    OnUi(nud, () => nud.Value = value);
                }
                else
                {
                    _value = value;
                }
            }
        }

        public decimal Minimum => _minimum;
        public decimal Maximum => _maximum;
        public decimal Increment => _increment;
        public int DecimalPlaces => _decimalPlaces;
    }

    public class GPALDateTimePicker : GPALControl, IAllowDateTimePickerControlSettings
    {
        private DateTime _value = DateTime.Now;
        private DateTimePickerFormat _format = DateTimePickerFormat.Long;
        private string _customFormat = "";
 
        internal GPALDateTimePicker()
        {
            ControlType = FormControlType.DateTimePicker;
        }

        public IAllowDateTimePickerControlSettings WithValue(DateTime value)
        {
            _value = value;
            return this;
        }

        public IAllowDateTimePickerControlSettings WithFormat(DateTimePickerFormat format)
        {
            _format = format;
            return this;
        }

        public IAllowDateTimePickerControlSettings WithCustomFormat(string formatString)
        {
            _customFormat = formatString;
            return this;
        }

        public DateTime Value
        {
            get
            {
                DateTime retVal = _value;
 
                if (WindowsControl is DateTimePicker dtp && true == Alive(dtp))
                    retVal = OnUiRead(dtp, () => dtp.Value, retVal);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is DateTimePicker dtp && true == Alive(dtp))
                {
                    OnUi(dtp, () => dtp.Value = value);
                }
                else
                {
                    _value = value;
                }
            }
        }

        public DateTimePickerFormat Format => _format;
        public string CustomFormat => _customFormat;
    }

    public class GPALTreeView : GPALControl, IAllowTreeViewControlSettings
    {
        private bool _checkBoxes = false;
        private bool _showLines = true;
        private bool _showPlusMinus = true;
 
        internal GPALTreeView()
        {
            ControlType = FormControlType.TreeView;
        }

        public IAllowTreeViewControlSettings WithCheckBoxes(bool enable)
        {
            _checkBoxes = enable;
            return this;
        }

        public IAllowTreeViewControlSettings WithShowLines(bool show)
        {
            _showLines = show;
            return this;
        }

        public IAllowTreeViewControlSettings WithShowPlusMinus(bool show)
        {
            _showPlusMinus = show;
            return this;
        }

        public bool CheckBoxes => _checkBoxes;
        public bool ShowLines => _showLines;
        public bool ShowPlusMinus => _showPlusMinus;

        public void ClearNodes()
        {
            if (!(WindowsControl is TreeView tv) || false == Alive(tv)) return;
            OnUi(tv, () => tv.Nodes.Clear());
        }

        public GPALTreeNode SelectedNode
        {
            get
            {
                if (!(WindowsControl is TreeView tv) || false == Alive(tv)) return null;
 
                TreeNode node = null;
 
                OnUi(tv, () => node = tv.SelectedNode);
 
                return null != node ? new GPALTreeNode(node) : null;
            }
            set
            {
                if (!(WindowsControl is TreeView tv) || false == Alive(tv)) return;
 
                MethodInvoker select = () => tv.SelectedNode = value?.Node;
 
                OnUi(tv, select);
            }
        }

        public void BeginUpdate()
        {
            if (!(WindowsControl is TreeView tv) || false == Alive(tv)) return;
 
            OnUi(tv, () => tv.BeginUpdate());
        }

        public void EndUpdate()
        {
            if (!(WindowsControl is TreeView tv) || false == Alive(tv)) return;
 
            OnUi(tv, () => tv.EndUpdate());
        }

        public GPALTreeNode AddNode(string text)
        {
            if (!(WindowsControl is TreeView tv) || false == Alive(tv)) return null;
            TreeNode node = null;
            OnUi(tv, () => node = tv.Nodes.Add(text));
            return node != null ? new GPALTreeNode(node) : null;
        }
    }

    public class GPALTreeNode
    {
        private readonly TreeNode _node;
 
        internal GPALTreeNode(TreeNode node) { _node = node; }
 
        // the node this handle stands for, so the tree can hand one back and be given one
        internal TreeNode Node => _node;

        public string Text
        {
            get
            {
                TreeView tv = _node.TreeView;
                string retVal = null;
 
                GPALControl.OnUiOrHere(tv, () => retVal = _node.Text);
 
                return retVal;
            }
            set
            {
                TreeView tv = _node.TreeView;
 
                GPALControl.OnUiOrHere(tv, () => _node.Text = value);
            }
        }

        public object Tag
        {
            get { return _node.Tag; }
            set { _node.Tag = value; }
        }

        public void Select()
        {
            TreeView tv = _node.TreeView;
 
            if (null == tv) return;
 
            GPALControl.OnUiOrHere(tv, () => tv.SelectedNode = _node);
        }

        public void Collapse()
        {
            TreeView tv = _node.TreeView;
 
            GPALControl.OnUiOrHere(tv, () => _node.Collapse());
        }

        public GPALTreeNode AddChild(string text)
        {
            TreeNode child = null;
            TreeView tv = _node.TreeView;
            GPALControl.OnUiOrHere(tv, () => child = _node.Nodes.Add(text));
            return child != null ? new GPALTreeNode(child) : null;
        }
 

        public bool Enabled
        {
            get
            {
                return SystemColors.GrayText != _node.ForeColor;
            }
            set
            {
                TreeView tv = _node.TreeView;
 
                // the colour is the state. a TreeNode has no Enabled of its own, and keeping the answer on the
                // node rather than in a list beside it means it cannot drift from what is on screen
                MethodInvoker paint = () => _node.ForeColor = true == value ? SystemColors.WindowText : SystemColors.GrayText;
 
                GPALControl.OnUiOrHere(tv, paint);
            }
        }

        public void Expand()
        {
            TreeView tv = _node.TreeView;
            GPALControl.OnUiOrHere(tv, () => _node.Expand());
        }
    }

    public class FileSelectorEventArgs : EventArgs
    {
        public bool Cancelled { get; }
        public string SelectedPath { get; }
        public IReadOnlyList<string> SelectedPaths { get; }

        public FileSelectorEventArgs(bool cancelled, string selectedPath, string[] selectedPaths)
        {
            Cancelled = cancelled;
            SelectedPath = selectedPath ?? "";
            if (selectedPaths == null || selectedPaths.Length == 0)
            {
                SelectedPaths = Array.AsReadOnly(Array.Empty<string>());
            }
            else
            {
                SelectedPaths = Array.AsReadOnly(selectedPaths);
            }
        }
    }

    public class GPALFileSelector : GPALControl, IAllowFileSelectorControlSettings
    {
        internal string _title = "Select File/Folder";
        internal string _initialDirectory = "";
        internal string _filter = "All files (*.*)|*.*";
        internal bool _selectFolder = false;       // true = FolderBrowserDialog, false = OpenFileDialog
        internal bool _multiSelect = false;
        internal bool _compact = false;
        internal string _placeholder = "";
        internal string _selectedPath = "";
        internal readonly List<string> _selectedPaths = new List<string>();
 
        internal GPALFileSelector()
        {
            ControlType = FormControlType.FileSelector;
        }

        public IAllowFileSelectorControlSettings WithTitle(string title)
        {
            _title = string.IsNullOrWhiteSpace(title) ? "Select File/Folder" : title;
            return this;
        }

        public IAllowFileSelectorControlSettings WithInitialDirectory(string path)
        {
            _initialDirectory = path;
            return this;
        }

        public IAllowFileSelectorControlSettings WithFilter(string filter)
        {
            _filter = string.IsNullOrWhiteSpace(filter) ? "All files (*.*)|*.*" : filter;
            return this;
        }

        public IAllowFileSelectorControlSettings WithSelectFolder(bool folderMode)
        {
            _selectFolder = folderMode;
            return this;
        }

        public IAllowFileSelectorControlSettings WithMultiSelect(bool allowMulti)
        {
            _multiSelect = allowMulti;
            return this;
        }

        public IAllowFileSelectorControlSettings WithCompact(bool compact)
        {
            _compact = compact;
            return this;
        }

        public IAllowFileSelectorControlSettings WithPlaceholder(string placeholder)
        {
            _placeholder = placeholder ?? "";
            return this;
        }

        public IAllowFileSelectorControlSettings WithSelectedPath(string path)
        {
            _selectedPath = path ?? "";
 
            _selectedPaths.Clear();
 
            if (false == string.IsNullOrEmpty(_selectedPath))
                _selectedPaths.Add(_selectedPath);
 
            return this;
        }
 
        public string SelectedPath => _selectedPath;
        public IReadOnlyList<string> SelectedPaths => _selectedPaths.AsReadOnly();

        internal void UpdateSelection(string[] paths)
        {
            _selectedPaths.Clear();
            if (paths != null && paths.Length > 0)
            {
                _selectedPaths.AddRange(paths);
                _selectedPath = paths[0];
                SyncDisplay();
            }
            else
            {
                _selectedPath = "";
            }
        }
        internal void NotifySelection(bool cancelled, string[] paths)
        {
            UpdateSelection(paths);
 
            var args = new FileSelectorEventArgs(cancelled, SelectedPath, paths);
 
            foreach (var (evt, handler) in Callbacks)
            {
                ControlEventType target = evt == ControlEventType.Default ? ControlEventType.Change : evt;
 
                if (target == ControlEventType.Change ||
                    target == ControlEventType.Click ||
                    target == ControlEventType.Default)
                {
                    ((EventHandler)handler)?.Invoke(this, args);
                }
            }
        }
        public void Clear()
        {
            _selectedPath = "";
            _selectedPaths.Clear();
            if (WindowsControl is Control ctrl && true == Alive(ctrl))
            {
                PostToUi(ctrl, () => ctrl.Text = "");
            }
        }
 
        public void SetPath(string path)
        {
            _selectedPath = path ?? "";
            _selectedPaths.Clear();
            if (!string.IsNullOrEmpty(_selectedPath))
                _selectedPaths.Add(_selectedPath);
            if (WindowsControl is Control ctrl && true == Alive(ctrl))
            {
                PostToUi(ctrl, () => ctrl.Text = _selectedPath);
            }
        }
 
        private void SyncDisplay()
        {
            if (WindowsControl is Control ctrl && true == Alive(ctrl))
            {
                string display = _selectedPaths.Count > 0
                    ? string.Join("; ", _selectedPaths)
                    : "";
 
                PostToUi(ctrl, () => ctrl.Text = display);
            }
        }
    }
 
    #endregion <GPAL Controls>
}