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.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 IAllowControlSettings WithAlignment(ContentAlignment alignment)
        {
            throw new NotImplementedException();
        }

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

        public int Height { get; internal set; } = 0;
        private string _text;
        public string Text
        {
            get => _text;
            set
            {
                _text = value;
                if (WindowsControl is Control ctrl && true == Alive(ctrl))
                {
                    OnUi(ctrl, () => ctrl.Text = value);
                }
            }
        }

        public string Name { get; internal set; }
        public object Tag { get; internal set; }
        public dynamic WindowsControl { get; internal set; }
        public bool IsReady => WindowsControl != null;

        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;
        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
        {
            if (handler is EventHandler typed)
                Callbacks.Add((ControlEventType.Default, (EventHandler)((sender, args) => RunOnUiThread(typed, sender, args))));
            else
                Callbacks.Add((ControlEventType.Default, 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(EventHandler handler, object sender, EventArgs args)
        {
            System.Diagnostics.Stopwatch held = System.Diagnostics.Stopwatch.StartNew();
 
            EnterCallback();
 
            try
            {
                handler(sender, args);
            }
            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
        {
            if (handler is EventHandler typed)
            {
                EventHandler onItsOwnThread = (sender, args) =>
                {
                    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(typed, sender, args));
                };
 
                Callbacks.Add((ControlEventType.Default, onItsOwnThread));
            }
            else
            {
                // only EventHandler can be wrapped without knowing the signature, and attaching it on the UI
                // thread is what it would have done anyway. saying so beats a form that quietly still freezes
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"[{typeof(TDelegate).Name}] cannot be run in the background, so the handler for [{CallbackOwner}] stays on the UI thread", this, GPALObjectType.Other);
 
                Callbacks.Add((ControlEventType.Default, handler));
            }
 
            return this;
        }

        private void RunInBackground(EventHandler handler, object sender, EventArgs args)
        {
            EnterCallback();
 
            try
            {
                handler(sender, args);
            }
            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);
            }
        }

        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)
        {
            if (null != WindowsControl)
                ((TextBox)WindowsControl).Tag = tag;
            else
                this.Tag = tag;
            return this;
        }

        public IAllowControlSettings WithHeight(int height)
        {
            this.Height = height;
            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, IAllowControlSettingsEnabledAndDefault
    {
        internal bool IsDefault { get; set; }
        internal GPALButton()
        {
            ControlType = FormControlType.Button;
            IsDefault = false;
        }
        public bool Enabled
        {
            get
            {
                if (null != ((Button)this.WindowsControl))
                    return ((Button)this.WindowsControl).Enabled;
                else
                    return IsEnabled;
            }
            set
            {
                if (WindowsControl is Button btn && true == Alive(btn))
                {
                    OnUi(btn, () => btn.Enabled = value);
                }
                else
                    IsEnabled = value;
            }
        }

        public IAllowControlSettingsEnabledAndDefault Default
        {
            get
            {
                IsDefault = true;
                return this;
            }
        }

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

    public class GPALCheckbox : GPALControl, IAllowControlSettingsEnabledAndChecked
    {
        internal GPALCheckbox()
        {
            ControlType = FormControlType.Checkbox;
        }
        public IAllowControlSettings 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 bool Enabled
        {
            get
            {
                if (null != ((CheckBox)this.WindowsControl))
                    return ((CheckBox)this.WindowsControl).Enabled;
                else
                    return IsEnabled;
            }
            set
            {
                if (WindowsControl is CheckBox cbx && true == Alive(cbx))
                {
                    OnUi(cbx, () => cbx.Enabled = value);
                }
                else
                    IsEnabled = value;
            }
        }

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

    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 IAllowDataGridViewControlSettings WithReadOnly(bool readOnly)
        {
            base.ReadOnly = readOnly;
            return this;
        }

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

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

        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);
        }

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

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

    public class GPALInput : GPALControl, IAllowControlSettingsPlaceholderEnabledAndPassword
    {
        internal bool InputIsPassword { get; set; } = false;
        internal bool IsReadOnly { get; set; } = false;
        internal string PlaceHolder { get; set; }
        internal GPALInput()
        {
            ControlType = FormControlType.Input;
        }
        public bool Enabled
        {
            get
            {
                if (null != ((PlaceholderTextBox)this.WindowsControl))
                    return ((PlaceholderTextBox)this.WindowsControl).Enabled;
                else
                    return IsEnabled;
            }
            set
            {
                if (WindowsControl is PlaceholderTextBox ptbInput && true == Alive(ptbInput))
                {
                    OnUi(ptbInput, () => ptbInput.Enabled = value);
                }
                else
                    IsEnabled = value;
            }
        }

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

        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 IAllowControlSettings IsPassword
        {
            get
            {
                InputIsPassword = true;
                if (true == String.IsNullOrEmpty(PlaceHolder))
                    PlaceHolder = "Enter Password";
                return this;
            }
        }
        public IAllowControlSettings WithPlaceholder(string PlaceholderText)
        {
            PlaceHolder = PlaceholderText;
            if (WindowsControl is PlaceholderTextBox tb && true == Alive(tb))
                tb.PlaceholderText = PlaceholderText;
            return this;
        }
 
        public 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;
        }
    }

    // TODO: group box
    public class GPALRadioButton : GPALControl, IAllowControlSettingsEnabledAndChecked
    {
        internal GPALRadioButton()
        {
            ControlType = FormControlType.RadioButton;
        }
        public IAllowControlSettings 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 bool Enabled
        {
            get
            {
                if (null != ((RadioButton)this.WindowsControl))
                    return ((RadioButton)this.WindowsControl).Enabled;
                else
                    return IsEnabled;
            }
            set
            {
                if (WindowsControl is RadioButton rb2 && true == Alive(rb2))
                {
                    OnUi(rb2, () => rb2.Enabled = value);
                }
                else
                    IsEnabled = value;
            }
        }

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

    public class GPALTab : GPALControl, IAllowControlSettings
    {
        internal GPALTab()
        {
            ControlType = FormControlType.Tab;
        }
        public bool Enabled
        {
            get
            {
                // a GPALTab is one page, and its control is the TabPage. asking the TabControl would answer
                // for every tab at once
                return WindowsControl is TabPage page ? page.Enabled : IsEnabled;
            }
            set
            {
                IsEnabled = value;
 
                if (!(WindowsControl is TabPage page) || false == Alive(page)) return;
 
                OnUi(page, () => page.Enabled = value);
            }
        }

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

        public void Activate()
        {
            if (WindowsControl is TabPage tabPage && tabPage.Parent is TabControl 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;
        }
        public bool Enabled
        {
            get
            {
                if (null != ((TableLayoutPanel)this.WindowsControl))
                    return ((TableLayoutPanel)this.WindowsControl).Enabled;
                else
                    return IsEnabled;
            }
            set
            {
                if (null != ((TableLayoutPanel)this.WindowsControl))
                    ((TableLayoutPanel)this.WindowsControl).Enabled = value;
                else
                    IsEnabled = value;
            }
        }

        public TableLayoutPanelGrowStyle GrowStyle
        {
            get
            {
                if (null != ((TableLayoutPanel)this.WindowsControl))
                    return ((TableLayoutPanel)this.WindowsControl).GrowStyle;
                else
                    return GrowStyle;
            }
            set
            {
                if (null != ((TableLayoutPanel)this.WindowsControl))
                    ((TableLayoutPanel)this.WindowsControl).GrowStyle = value;
                else
                    GrowStyle = value;
            }
        }

        public int ColumnCount
        {
            get
            {
                if (null != ((TableLayoutPanel)this.WindowsControl))
                    return ((TableLayoutPanel)this.WindowsControl).ColumnCount;
                else
                    return ColumnCount;
            }
            set
            {
                if (null != ((TableLayoutPanel)this.WindowsControl))
                    ((TableLayoutPanel)this.WindowsControl).ColumnCount = value;
                else
                    ColumnCount = value;
            }
        }

        public int RowCount
        {
            get
            {
                if (null != ((TableLayoutPanel)this.WindowsControl))
                    return ((TableLayoutPanel)this.WindowsControl).RowCount;
                else
                    return RowCount;
            }
            set
            {
                if (null != ((TableLayoutPanel)this.WindowsControl))
                    ((TableLayoutPanel)this.WindowsControl).RowCount = value;
                else
                    RowCount = value;
            }
        }
 

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

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

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

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

    public class GPALTextArea : GPALControl, IAllowControlSettingsAndEnabled, IAllowPlaceholder, IAllowReadOnly
    {
        internal bool IsReadOnly { get; set; } = false;
        internal string PlaceHolder { get; set; }
 
        // lines wait here until the thread that owns the control is free to take them. see AppendLine
        private readonly ConcurrentQueue<string> pendingLines = new ConcurrentQueue<string>();
        private readonly object appendGate = new object();
        private bool waitingForHandle = false;
 
        internal GPALTextArea()
        {
            ControlType = FormControlType.TextArea;
        }
        public bool Enabled
        {
            get
            {
                if (null != ((PlaceholderTextBox)this.WindowsControl))
                    return ((PlaceholderTextBox)this.WindowsControl).Enabled;
                else
                    return IsEnabled;
            }
            set
            {
                if (WindowsControl is PlaceholderTextBox ptbArea && true == Alive(ptbArea))
                {
                    OnUi(ptbArea, () => ptbArea.Enabled = value);
                }
                else
                    IsEnabled = value;
            }
        }

        public IAllowControlSettings WithEnabled(bool enabled)
        {
            this.Enabled = enabled;
            return this;
        }
 
        public IAllowControlSettings WithPlaceholder(string PlaceholderText)
        {
            PlaceHolder = PlaceholderText;
            if (WindowsControl is PlaceholderTextBox tb && true == Alive(tb))
                tb.PlaceholderText = PlaceholderText;
            return this;
        }
 
        public 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)
        {
            // queued first and written from nowhere but the ui thread. AppendLine is called on whichever thread
            // published, and during a workflow that is a worker while the ui thread waits inside Run for it to
            // finish. A control belongs to the thread that made it, and asking that thread for anything while it
            // is blocked is where the run stops and never starts again
            pendingLines.Enqueue(text);
 
            Drain(maxLines);
        }

        private void Drain(int maxLines)
        {
            // a form on its way out still publishes, and posting to a control whose handle is gone makes windows
            // forms try to build another one. nothing to append to is not a failure, it is a closed form
            if (!(WindowsControl is PlaceholderTextBox tb) || false == Alive(tb)) return;
 
            // no handle means one of two opposite things: built and not yet shown, or shown and now closed.
            // disposal tells them apart, and the guard above already dealt with the closed one, so what is left is
            // a control waiting to be created, a tab nobody has opened. the lines wait in the queue, and the
            // control says when it has a handle rather than being touched from here to find out
            if (false == tb.IsHandleCreated)
            {
                lock (appendGate)
                {
                    if (false == waitingForHandle)
                    {
                        waitingForHandle = true;
                        tb.HandleCreated += (sender, args) => Drain(maxLines);
                    }
                }
 
                return;
            }
 
            MethodInvoker drain = () =>
            {
                // posted while the handle was there and run after it went. appending now rebuilds the handle
                if (false == Alive(tb) || false == tb.IsHandleCreated) return;
 
                while (true == pendingLines.TryDequeue(out string line))
                {
                    if (maxLines > 0 && tb.Lines.Length >= maxLines)
                    {
                        int keep = maxLines - 1;
                        string[] trimmed = new string[keep];
                        Array.Copy(tb.Lines, tb.Lines.Length - keep, trimmed, 0, keep);
                        tb.Text = string.Join("\r\n", trimmed);
                    }
                    if (tb.TextLength > 0) tb.AppendText("\r\n");
                    tb.AppendText(line);
                }
 
                tb.ScrollToCaret();
            };
            // posted rather than waited on. a workflow raised from a button runs on the ui thread, so anything
            // publishing from a worker thread while that runs would block here for as long as the workflow takes,
            // and the workflow is waiting for the same thread. the lines land when the ui is free again
            PostToUi(tb, drain);
        }

        public void Clear()
        {
            // what has not been shown yet is cleared as well, or a queue built up while a run held the ui thread
            // arrives afterwards and fills a box that was just emptied
            while (true == pendingLines.TryDequeue(out string dropped)) { }
 
            if (!(WindowsControl is PlaceholderTextBox 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);
        }

        public void ScrollToEnd()
        {
            if (!(WindowsControl is PlaceholderTextBox tb) || false == Alive(tb)) return;
            if (false == Alive(tb)) return;
 
            PostToUi(tb, () => tb.ScrollToCaret());
        }
    }

    public class GPALRichTextBox : GPALControl, IAllowRichTextBoxControlSettings
    {
        private string _text = string.Empty;
        internal bool IsReadOnly { get; set; } = true;
 
        internal GPALRichTextBox()
        {
            ControlType = FormControlType.RichTextBox;
        }

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

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

        public bool Enabled
        {
            get
            {
                if (WindowsControl is RichTextBox rtb && true == Alive(rtb))
                    return rtb.Enabled;
                else
                    return IsEnabled;
            }
            set
            {
                if (WindowsControl is RichTextBox rtb && true == Alive(rtb))
                {
                    OnUi(rtb, () => rtb.Enabled = value);
                }
                else
                {
                    IsEnabled = value;
                }
            }
        }

        public IAllowControlSettings WithEnabled(bool enabled = true)
        {
            this.Enabled = enabled;
            return this;
        }
 
        public 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);

        internal static void RenderMarkdown(RichTextBox rtb, string markdown)
        {
            rtb.Clear();
 
            Font baseFont = rtb.Font;
            Color baseColor = rtb.ForeColor;
            FontFamily codeFamily = new FontFamily("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 = new Font(baseFont.FontFamily, 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
                        ? new Font(codeFamily, baseFont.Size, FontStyle.Regular)
                        : new Font(baseFont.FontFamily, 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 bool Enabled
        {
            get
            {
                bool retVal = IsEnabled;
 
                if (WindowsControl is ComboBox cb && true == Alive(cb))
                    retVal = OnUiRead(cb, () => cb.Enabled, retVal);
 
                return retVal;
            }
            set
            {
                if (WindowsControl is ComboBox cb && true == Alive(cb))
                {
                    OnUi(cb, () => cb.Enabled = value);
                }
                else
                {
                    IsEnabled = value;
                }
            }
        }
 
        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 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)
                {
                    OnUi(strip, () => label.Text = _text);
                }
            }
        }
    }

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

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

        public 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)
        {
            if (!(WindowsControl is ListView lv) || false == Alive(lv)) return;
            var item = new ListViewItem(title);
            foreach (var s in subItems) item.SubItems.Add(s);
            OnUi(lv, () => lv.Items.Add(item));
        }
 
        public void SetColumnWidth(int index, int width)
        {
            if (!(WindowsControl is ListView lv) || false == Alive(lv)) return;
            if (index < 0 || index >= lv.Columns.Count) return;
            OnUi(lv, () => lv.Columns[index].Width = width);
        }

        public string SelectedText =>
            WindowsControl is ListView lv2 && lv2.SelectedItems.Count > 0
                ? lv2.SelectedItems[0].Text
                : null;
    }

    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 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))
            {
                OnUi(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))
            {
                OnUi(ctrl, () => ctrl.Text = _selectedPath);
            }
        }
 
        private void SyncDisplay()
        {
            if (WindowsControl is Control ctrl && true == Alive(ctrl))
            {
                string display = _selectedPaths.Count > 0
                    ? string.Join("; ", _selectedPaths)
                    : "";
 
                OnUi(ctrl, () => ctrl.Text = display);
            }
        }
    }
 
    #endregion <GPAL Controls>
}