GPALForm.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 OpenQA.Selenium;
using System;
using System.Collections.Generic;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
using System.Windows.Forms.DataVisualization.Charting;
using static GenerallyPositive.GPALForm.GPALForm;
using static GenerallyPositive.Enums;
using GenerallyPositive.GPALForm;
 
namespace GenerallyPositive.GPALForm
{
    public class GPALForm : IAllowFormSettingsAndActions, IAllowFormActionsAndFillIn, IAllowCallBack
    {
        public delegate CallIfStatus CallAfterFillInDelegate(GPALForm myForm, IGPALGrid<string> tokens, int tokenIdx);
 
        private readonly System.Windows.Forms.ToolTip _toolTip = new System.Windows.Forms.ToolTip
        {
            AutoPopDelay = 5000,
            InitialDelay = 500,
            ShowAlways = true
        };

        public dynamic ToGPALObject()
        {
            return this;
        }

        public string FormName
        {
            get
            {
                return FormSettings.myForm.FormName;
            }
            internal set
            {
                FormSettings.myForm.FormName = value;
            }
        }
 
        private FormSettings FormSettings { get; set; }
 
        internal GPALForm()
        {
            FormSettings = new FormSettings();
            FormSettings.myForm = new GPALFormForm()
            {
                ControlList = new List<GPALControl>(),
            };
 
            FormSettings.myForm.SuspendLayout();
            FormSettings.myForm.Left = FormSettings.left;
            FormSettings.myForm.Top = FormSettings.top;
            FormSettings.myForm.Width = FormSettings.width;
            FormSettings.myForm.Height = FormSettings.height;
            FormSettings.myForm.InitialSize = new Size(FormSettings.width, FormSettings.height);
 
            FormSettings.myForm.AutoSize = true;
 
            Size _initialPreferredSize = FormSettings.myForm.Size;
 
            FormSettings.TableLayoutPanel = new TableLayoutPanel()
            {
                //Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Bottom | AnchorStyles.Right,
                Dock = DockStyle.Fill,
                AutoSize = false,
                AutoScroll = true,
            };
            FormSettings.myForm.Controls.Add(FormSettings.TableLayoutPanel);
 
            System.Windows.Forms.Application.EnableVisualStyles();
        }
 
        #region <Settings>
        internal GPALFormForm Form
        {
            get
            {
                return FormSettings.myForm;
            }
        }
        internal List<GPALControl> ControlList
        {
            get
            {
                return FormSettings.myForm.ControlList;
            }
        }
        public IAllowFormSettingsAndActions WithWidth(int width)
        {
            FormSettings.width = width;
            FormSettings.myForm.Width = width;
            // ensure the right edge is on-screen, but the left edge could be off-screen if the form is too wide
            // todo - how to handle out of bounds settings?
            if (FormSettings.left > (Screen.PrimaryScreen.Bounds.Width - width))
                FormSettings.left = Screen.PrimaryScreen.Bounds.Width - width - 2;
 
            FormSettings.myForm.InitialSize = new Size(FormSettings.myForm.Width, FormSettings.myForm.Height);
 
            return this;
        }

        public IAllowFormSettingsAndActions WithButtonWidth(int width)
        {
            FormSettings.buttonWidth = width;
 
            foreach (GPALControl gPALControl in FormSettings.myForm.ControlList)
                if (gPALControl is GPALButton gPALButton
                    && 0 >= gPALButton.Width
                    && gPALButton.WindowsControl is Control windowsControl)
                {
                    if (0 < width)
                        ApplyWidth(width, windowsControl);
                    else
                        // no width is full width again. a button is added anchored left and right, so putting
                        // those back is what undoes a width this form was given earlier
                        GPALControl.OnUi(windowsControl, () =>
                            windowsControl.Anchor = windowsControl.Anchor | AnchorStyles.Left | AnchorStyles.Right);
                }
 
            return this;
        }

        public IAllowFormSettingsAndActions WithHeight(int height)
        {
            FormSettings.height = height;
            FormSettings.myForm.Height = height;
            // ensure the bottom is on-screen, but this could put the grab bar off-screen
            if (FormSettings.top > (Screen.PrimaryScreen.Bounds.Height - height))
                FormSettings.top = Screen.PrimaryScreen.Bounds.Height - height - 2;
            else
                FormSettings.top = (Screen.PrimaryScreen.Bounds.Height - height) / 2;  // center unless overridden by subsequent Top
 
            FormSettings.myForm.InitialSize = new Size(FormSettings.myForm.Width, FormSettings.myForm.Height);
 
            return this;
        }

        public IAllowFormSettingsAndActions WithTop(int top)
        {
            FormSettings.top = top;
            FormSettings.myForm.Top = top;
            return this;
        }

        public IAllowFormSettingsAndActions WithLeft(int left)
        {
            FormSettings.left = left;
            FormSettings.myForm.Left = left;
            return this;
        }

        public int Left => FormSettings.myForm.Left;
        public int Top => FormSettings.myForm.Top;
        public int Width => FormSettings.myForm.Width;
        public int Height => FormSettings.myForm.Height;
        public IAllowFormSettingsAndActions CallAfterFillIn(GPALForm.CallAfterFillInDelegate callAfterFillIn)
        {
            FormSettings.myForm.CallAfterFillIn = callAfterFillIn;
            return this;
        }
        #endregion <Settings>
        #region <Forms Actions>
        public IAllowFormSettingsAndActions WithFormControl(GPALControl gPALControl)
        {
            return gPALControl switch
            {
                GPALButton btn => AddButton(btn),
                GPALChart ch => AddChart(ch),
                GPALComboBox cb => AddComboBox(cb),
                GPALDataGridView dgv => AddDataGridView(dgv),
                GPALDateTimePicker dtp => AddDateTimePicker(dtp),
                GPALCheckbox chk => AddCheckbox(chk),
                GPALFileSelector fs => AddFileSelector(fs),
                GPALInput inp => AddInput(inp),
                GPALLabel lbl => AddLabel(lbl),
                GPALLinkLabel lnk => AddLinkLabel(lnk),
                GPALSpacer space => AddSpacer(space),
                GPALListView lv => AddListView(lv),
                GPALMenuBar mb => AddMenuBar(mb),
                GPALNumericUpDown nud => AddNumericUpDown(nud),
                GPALPicture pic => AddPicture(pic),
                GPALProgressBar pb => AddProgressBar(pb),
                GPALSlider sl => AddSlider(sl),
                GPALRadioButton rb => AddRadioButton(rb),
                GPALRichTextBox rtb => AddRichTextBox(rtb),
                GPALStatusStrip ss => AddStatusStrip(ss),
                GPALToolbar tb => AddToolbar(tb),
                GPALTab tab => AddTab(tab),
                GPALSplitter sp => AddSplitter(sp),
                GPALGroupBox gb => AddGroupBox(gb),
                GPALTableLayoutPanel tlp => AddTableLayoutPanel(tlp),
                GPALTextArea ta => AddTextArea(ta),
                GPALTreeView tv => AddTreeView(tv),
 
                _ => this   // or throw new NotSupportedException(...)
            };
        }

        public IAllowFormSettingsAndActions WithTitle(string title)
        {
            FormSettings.myForm.FormTitle = title;
            FormSettings.myForm.Text = title;
            return this;
        }

        public IAllowFormSettingsAndActions FillInFrom(GPALDatabase inputDatabase)
        {
            FormSettings.myForm.InputDatabase = inputDatabase;
            DatabaseHelper.TokenizeDatabase(inputDatabase);
            FormHelper.FillInWithTokens(this, new List<IGPALGrid<string>> { inputDatabase.Tokens }, WriteMode.Overwrite);
            return this;
        }

        public IAllowFormSettingsAndActions AppendFrom(GPALDatabase inputDatabase)
        {
            FormSettings.myForm.InputDatabase = inputDatabase;
            DatabaseHelper.TokenizeDatabase(inputDatabase);
            FormHelper.FillInWithTokens(this, new List<IGPALGrid<string>> { inputDatabase.Tokens }, WriteMode.Append);
            return this;
        }

        public IAllowFormSettingsAndActions InsertFrom(GPALDatabase inputDatabase)
        {
            FormSettings.myForm.InputDatabase = inputDatabase;
            DatabaseHelper.TokenizeDatabase(inputDatabase);
            FormHelper.FillInWithTokens(this, new List<IGPALGrid<string>> { inputDatabase.Tokens }, WriteMode.Insert);
            return this;
        }

        public IAllowFormSettingsAndActions FillInFrom(GPALFile inputFile)
        {
            FormSettings.myForm.InputFile = inputFile;
            if (false == FileHelper.TokenizeFile(inputFile))
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Unable to tokenize file [{inputFile.Filename}]. Continuing.", inputFile, GPALObjectType.GPALFile);
                return this;
            }
            FormHelper.FillInWithTokens(this, ((IGPALFileInternal)inputFile).TokenList, WriteMode.Overwrite);
            return this;
        }

        public IAllowFormSettingsAndActions AppendFrom(GPALFile inputFile)
        {
            FormSettings.myForm.InputFile = inputFile;
            if (false == FileHelper.TokenizeFile(inputFile))
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Unable to tokenize file [{inputFile.Filename}]. Continuing.", inputFile, GPALObjectType.GPALFile);
                return this;
            }
            FormHelper.FillInWithTokens(this, ((IGPALFileInternal)inputFile).TokenList, WriteMode.Append);
            return this;
        }

        public IAllowFormSettingsAndActions InsertFrom(GPALFile inputFile)
        {
            FormSettings.myForm.InputFile = inputFile;
            if (false == FileHelper.TokenizeFile(inputFile))
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Unable to tokenize file [{inputFile.Filename}]. Continuing.", inputFile, GPALObjectType.GPALFile);
                return this;
            }
            FormHelper.FillInWithTokens(this, ((IGPALFileInternal)inputFile).TokenList, WriteMode.Insert);
            return this;
        }

        public IAllowFormSettingsAndActions FillInFrom(IGPALGrid<string> inputGrid)
        {
            FormHelper.FillInWithTokens(this, new List<IGPALGrid<string>> { inputGrid }, WriteMode.Overwrite);
            return this;
        }

        public IAllowFormSettingsAndActions AppendFrom(IGPALGrid<string> inputGrid)
        {
            FormHelper.FillInWithTokens(this, new List<IGPALGrid<string>> { inputGrid }, WriteMode.Append);
            return this;
        }

        public IAllowFormSettingsAndActions InsertFrom(IGPALGrid<string> inputGrid)
        {
            FormHelper.FillInWithTokens(this, new List<IGPALGrid<string>> { inputGrid }, WriteMode.Insert);
            return this;
        }
        // a workflow raised from a button is still the form's guest, and a guest that fails should not take the
        // house down with it. windows forms funnels everything thrown on the ui thread through here, so this is
        // the one place to say so: publish it, leave the form standing, let whoever pressed the button read the
        // log tab and press it again
        private static bool workflowFailureHandled = false;
 
        private void KeepFormAliveOnWorkflowFailure()
        {
            if (true == workflowFailureHandled) return;
 
            workflowFailureHandled = true;
 
            // only the subscription. the mode cannot be set once a control exists on the thread, and by the time
            // a form is shown they all do. windows forms routes to a handler when one is attached, which is this
            System.Windows.Forms.Application.ThreadException += (sender, args) =>
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"The form kept going after [{args.Exception?.GetType().Name}]", null, GPALObjectType.GPALForm, args.Exception);
        }

        public IAllowFormActions ShowDialog()
        {
            KeepFormAliveOnWorkflowFailure();
            SizeForm();
            FormSettings.myForm.ResumeLayout();
            if (true == FormSettings.myForm.Visible)
                FormSettings.myForm.Hide();
            FormSettings.myForm.ShowDialog();
 
            return this;
        }

        public IAllowFormActionsAndFillIn Show()
        {
            KeepFormAliveOnWorkflowFailure();
            SizeForm();
            FormSettings.myForm.ResumeLayout();
            if (true == FormSettings.myForm.Visible)
                FormSettings.myForm.Hide();
            FormSettings.myForm.Show();
 
            return this;
        }

        public IAllowFormActions Hide()
        {
            FormSettings.myForm.Hide();
            return this;
        }
        #endregion <Forms Actions>
        #region Helpers
        private static void ApplyWidth(int width, Control control)
        {
            if (0 >= width)
                return;
 
            // marshalled, because a width can be changed while the form is up and the caller is not always the
            // thread that owns it
            GPALControl.OnUi(control, () =>
            {
                control.Width = width;
                control.Anchor = control.Anchor & ~(AnchorStyles.Left | AnchorStyles.Right);
            });
        }

        private void ApplyToolTip(GPALControl gpalControl, Control winControl)
        {
            if (!string.IsNullOrWhiteSpace(gpalControl.ToolTipText))
            {
                FormSettings.ToolTip.SetToolTip(winControl, gpalControl.ToolTipText);
                if (gpalControl.ToolTipAutoPopDelayMs != 5000)
                    FormSettings.ToolTip.AutoPopDelay = gpalControl.ToolTipAutoPopDelayMs;
            }
        }

        // put on a realized control whose definition carried a height, so the answer does not depend on the
        // control having been given a name as well
        internal const string SetHeightMarker = "gpal.height.set";

        private static bool HasASetHeight(Control control, HashSet<string> sized)
        {
            return true == sized.Contains(control.Name ?? "")
                || SetHeightMarker.Equals(control.Tag as string);
        }
 
        private static bool GrowsWithTheForm(Control control, HashSet<string> sized)
        {
            bool retVal = false;
 
            if (false == HasASetHeight(control, sized))
                // a container holds the rest of the form and has to take the height, or it collapses to its own
                // preferred size: a TabControl given AutoSize is a tab strip and nothing under it
                // TableLayoutPanel is not here. A nested one is a composite built to a fixed shape, such as the
                // input and browse button of a file selector, and stretching it leaves its contents at the top
                // of an empty area
                retVal = control is TabControl
                      || control is SplitContainer
                      // multiline only. a single line TextBox is also a TextBoxBase and shows no more text at
                      // any greater height
                      || (control is TextBoxBase textBox && true == textBox.Multiline)
                      || control is ListView
                      || control is TreeView
                      || control is DataGridView
                      || control is ListBox;
 
            return retVal;
        }

        private static void SettleRows(TableLayoutPanel panel, HashSet<string> sized)
        {
            if (null == panel) return;
 
            SettleInside(panel, sized);
 
            // A panel with explicit RowStyles is left as it was written, and so is a real grid: this stacks one
            // control per row in one column, which is not what a multi-column panel is for
            if (0 < panel.RowStyles.Count || 1 < panel.ColumnCount) return;
 
            // RowCount is not updated by Controls.Add, so it reads zero here
            Control[] inOrder = panel.Controls.Cast<Control>().ToArray();
 
            if (1 > inOrder.Length) return;
 
            panel.SuspendLayout();
 
            panel.ColumnCount = 1;
            panel.ColumnStyles.Clear();
            panel.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100f));
 
            panel.RowCount = inOrder.Length;
 
            for (int row = 0; row < inOrder.Length; row++)
            {
                panel.SetCellPosition(inOrder[row], new TableLayoutPanelCellPosition(0, row));
 
 
                // AutoSize sizes a row from the control PreferredSize, which for a SplitContainer, and for any
                // control given a height with WithHeight, is not the height it is meant to be. Those rows are set
                // to that height outright. Everything else keeps AutoSize, which is what a label or a button wants
                bool ownHeight = 0 < inOrder[row].Height
                             && (inOrder[row] is SplitContainer
                              || true == HasASetHeight(inOrder[row], sized));
 
                panel.RowStyles.Add(true == GrowsWithTheForm(inOrder[row], sized)
                                    ? new RowStyle(SizeType.Percent, 100f)
                                    : true == ownHeight
                                      // the margins are part of the row, or the control is clipped by exactly
                                      // that much and the layout compensates by leaving slack elsewhere
                                      ? new RowStyle(SizeType.Absolute, inOrder[row].Height
                                                                     + inOrder[row].Margin.Top
                                                                     + inOrder[row].Margin.Bottom)
                                      : new RowStyle(SizeType.AutoSize));
            }
 
 
            panel.ResumeLayout(true);
 
            settled.Add(panel);
 
            // AutoScroll decides from the preferred height, which comes out larger than the rows actually
            // drawn. Re-evaluated whenever the panel could have changed size and switched off whenever
            // everything fits, so a panel that is not overflowing cannot show a scrollbar.
            // HandleCreated as well as SizeChanged: this runs before the form is shown, when no panel has a
            // handle and nothing can be measured
            panel.HandleCreated += (sender, args) => ScrollOnlyWhenNeeded(panel);
            panel.SizeChanged += (sender, args) => ScrollOnlyWhenNeeded(panel);
            panel.VisibleChanged += (sender, args) => ScrollOnlyWhenNeeded(panel);
 
            ScrollOnlyWhenNeeded(panel);
        }
 
        // Walks every child of every kind. A tab panel sits under a TabPage, a splitter pane under a
        // SplitterPanel and a group box panel under the box, so anything looking only for TableLayoutPanel
        // children reaches none of them
        private static void SettleInside(Control parent, HashSet<string> sized)
        {
            foreach (Control child in parent.Controls)
                if (child is TableLayoutPanel nested)
                    SettleRows(nested, sized);
                else
                    SettleInside(child, sized);
        }
        // the panels this settled, and the only ones it may scroll. a panel that was skipped was skipped because
        // it is somebody own construction: the file selector is two columns holding one row, and giving that a
        // scrollbar draws one across the middle of a form
        private static readonly HashSet<TableLayoutPanel> settled = new HashSet<TableLayoutPanel>();
 
        // walks every panel this settled and takes the scroll decision again, once sizes are real
        private static void MeasureAgain(Control parent)
        {
            foreach (Control child in parent.Controls)
            {
                if (child is TableLayoutPanel panel && true == settled.Contains(panel))
                    ScrollOnlyWhenNeeded(panel);
 
                MeasureAgain(child);
            }
        }
 
        // guards the re-entry: turning AutoScroll on or off resizes the panel, which raises SizeChanged again
        private static readonly HashSet<TableLayoutPanel> measuring = new HashSet<TableLayoutPanel>();
 
        private static void ScrollOnlyWhenNeeded(TableLayoutPanel panel)
        {
            if (null == panel || false == panel.IsHandleCreated || true == measuring.Contains(panel)) return;
 
            measuring.Add(panel);
 
            try
            {
                // measured against the width that would be left once a scrollbar is showing, not the width now.
                // a panel a pixel over turns one on, that takes the width away, anything anchored gets narrower,
                // anything that wraps gets taller, and the overflow grows instead of staying at a pixel
                int narrower = panel.ClientSize.Width - SystemInformation.VerticalScrollBarWidth;
                int wanted = panel.GetPreferredSize(new Size(0 < narrower ? narrower : panel.ClientSize.Width, 0)).Height;
                int have = panel.ClientSize.Height;
                bool overflowing = wanted > have;
 
                //GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Panel [{panel.Parent?.Name}] wants [{wanted}] has [{have}] rows [{panel.RowCount}] scroll [{overflowing}]");
 
                // only a panel that is a tab or the form itself scrolls. a splitter pane or a group box panel
                // that scrolls puts its own pair of scrollbars inside a row, which is worse than the clipping it
                // is trying to avoid. a nested panel that does not fit needs its container made taller instead
                bool mayScroll = panel.Parent is TabPage || panel.Parent is Form;
 
                if (panel.AutoScroll != (overflowing && mayScroll))
                    panel.AutoScroll = overflowing && mayScroll;
 
                // the scrollable area is stated rather than left to be computed. AutoScroll works it out from the
                // panel preferred size, which comes out well over the rows it laid out, and the difference is
                // empty space you can scroll to and nothing can fill: rows do not stretch unless they are Percent
                panel.AutoScrollMinSize = true == (overflowing && mayScroll) ? new Size(0, wanted) : Size.Empty;
 
                // the rows were laid out before the panel had its final size, and nothing recomputes them on its
                // own: resizing the form by a single pixel is what forces the pass, so it is forced here instead
                panel.PerformLayout();
            }
            finally
            {
                measuring.Remove(panel);
            }
        }
 
        // Controls whose height was set with WithHeight, which keep it rather than growing
        private HashSet<string> ControlsWithASetHeight()
        {
            HashSet<string> retVal = new HashSet<string>();
 
            foreach (GPALControl entry in FormSettings.myForm.ControlList)
                if (0 < entry.Height && false == string.IsNullOrEmpty(entry.Name))
                    retVal.Add(entry.Name);
 
            return retVal;
        }

        private void SizeForm()
        {
            // apply explicit positioning regardless of whether width/height were set,
            // otherwise StartPosition defaults to WindowsDefaultLocation and Left/Top are ignored
            if (0 < FormSettings.top)
            {
                FormSettings.myForm.StartPosition = FormStartPosition.Manual;
                FormSettings.myForm.Top = FormSettings.top;
            }
            if (0 < FormSettings.left)
            {
                FormSettings.myForm.StartPosition = FormStartPosition.Manual;
                FormSettings.myForm.Left = FormSettings.left;
            }
 
            HashSet<string> sized = ControlsWithASetHeight();
 
            foreach (Control child in FormSettings.myForm.Controls)
                if (child is TableLayoutPanel root)
                    SettleRows(root, sized);
 
            if (0 == FormSettings.height)
                FitHeightToContent();
 
            // the panels are settled and measured before the form is shown, when neither it nor they have their
            // final size. Shown is the first moment they do, and taking the measurement again there is what
            // dragging the form by one pixel was doing by hand
            FormSettings.myForm.Shown += (sender, args) => MeasureAgain(FormSettings.myForm);
        }
 
        // the height a form with none of its own is laid out at, so its labels have a width to wrap to, before it
        // is measured and fitted
        private const int HeightToLayOutAt = 300;

        private void FitHeightToContent()
        {
            GPALFormForm form = FormSettings.myForm;
            TableLayoutPanel panel = form.Controls.OfType<TableLayoutPanel>().FirstOrDefault();
 
            if (null != panel)
            {
                if (HeightToLayOutAt > form.Height)
                    form.Height = HeightToLayOutAt;
 
                // the caller suspended layout and resumes it once this returns, so it is resumed for one pass here
                // and suspended again after
                form.ResumeLayout(true);
 
                int strips = form.Controls.Cast<Control>()
                    .Where(control => control != panel && (DockStyle.Top == control.Dock || DockStyle.Bottom == control.Dock))
                    .Sum(control => control.Height);
                int content = panel.GetPreferredSize(new Size(panel.ClientSize.Width, 0)).Height;
                int frame = form.Height - form.ClientSize.Height;
                int height = Math.Min(content + strips + frame, Screen.PrimaryScreen.WorkingArea.Height);
 
                form.InitialSize = new Size(form.Width, height);
                form.Height = height;
 
                form.SuspendLayout();
            }
        }
        #endregion Helpers
        #region Add Controls
        private IAllowFormSettingsAndActions AddButton(GPALButton gPALButton)
        {
            FormSettings.myForm.ControlList.Add(gPALButton);
            Button button = new Button
            {
                Name = gPALButton.Name,
                Text = gPALButton.Text,
                //                AutoSize = true,
                // No Bottom, so the button keeps its own height rather than stretching to fill its row. The
                // four-sided anchor is for the scrolling controls - grid, list, tree, text boxes - which show
                // more content at a greater height
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Enabled = gPALButton.Enabled,
                Height = 10 < gPALButton.Height ? gPALButton.Height : 20,
            };
           
            gPALButton.WindowsControl = button;
 
            ApplyWidth(0 < gPALButton.Width ? gPALButton.Width : FormSettings.buttonWidth, button);
 
            foreach (var (evt, handler) in gPALButton.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.DoubleClick:
                        button.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Default:
                    case ControlEventType.Click:
                        button.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(button);
 
            if (true == gPALButton.IsDefault)
            {
                FormSettings.myForm.AcceptButton = button;
                button.DialogResult = DialogResult.OK;
                button.TabIndex = 0;
            }
 
            if (!string.IsNullOrWhiteSpace(gPALButton.ToolTipText))
                ApplyToolTip(gPALButton, button);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddChart(GPALChart gPALChart)
        {
            FormSettings.myForm.ControlList.Add(gPALChart);
            // a control with no name has no AutomationId, and a control with no AutomationId cannot be named
            // by a workflow. The chart is built before it gets here, so this is where it gets its name
            ((Chart)gPALChart.WindowsControl).Name = gPALChart.Name;
            ((Chart)gPALChart.WindowsControl).Enabled = gPALChart.IsEnabled;
 
            FormSettings.TableLayoutPanel.Controls.Add((Chart)gPALChart.WindowsControl);
            ((Chart)gPALChart.WindowsControl).Height = 10 < gPALChart.Height ? gPALChart.Height : 150;
 
            Chart chart = gPALChart.WindowsControl;
 
            ApplyWidth(gPALChart.Width, chart);
 
            foreach (var (evt, handler) in gPALChart.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.DragDrop:
                        chart.DragDrop += (DragEventHandler)handler;
                        break;
 
                    case ControlEventType.DragEnter:
                        chart.DragEnter += (DragEventHandler)handler;
                        break;
 
                    case ControlEventType.DragLeave:
                        chart.DragLeave += (EventHandler)handler;
                        break;
 
                    case ControlEventType.DragOver:
                        chart.DragOver += (DragEventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        chart.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Default:
                    case ControlEventType.Click:
                        chart.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            if (!string.IsNullOrWhiteSpace(gPALChart.ToolTipText))
                ApplyToolTip(gPALChart, chart);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddCheckbox(GPALCheckbox gPALCheckbox)
        {
            FormSettings.myForm.ControlList.Add(gPALCheckbox);
            CheckBox checkBox = new CheckBox
            {
                Name = gPALCheckbox.Name,
                Text = gPALCheckbox.Text,
                AutoSize = true,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Checked = gPALCheckbox.Checked,
                Enabled = gPALCheckbox.Enabled,
                Height = 10 < gPALCheckbox.Height ? gPALCheckbox.Height : 20,
            };
            gPALCheckbox.WindowsControl = checkBox;
 
            ApplyWidth(gPALCheckbox.Width, checkBox);
 
            // has to be in place for proper presentation, user can also hook into this for their purposes
            checkBox.CheckedChanged += new EventHandler(delegate (Object sender, EventArgs a) { gPALCheckbox.Checked = ((CheckBox)sender).Checked; }); // copy changed text up to control
 
            foreach (var (evt, handler) in gPALCheckbox.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.CheckedChanged:
                        checkBox.CheckedChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        checkBox.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        checkBox.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(checkBox);
 
            if (!string.IsNullOrWhiteSpace(gPALCheckbox.ToolTipText))
                ApplyToolTip(gPALCheckbox, checkBox);
 
            return this;
        }
        // the first thing on the list that can actually be chosen, for when there is nothing to fall back to
        private static int FirstEnabledIndex(ComboBox combo, GPALComboBox gpalCombo)
        {
            int retVal = -1;
 
            for (int index = 0; index < combo.Items.Count && -1 == retVal; index++)
                if (false == gpalCombo.disabledItems.Contains(combo.Items[index].ToString()))
                    retVal = index;
 
            return retVal;
        }
 
        private IAllowFormSettingsAndActions AddComboBox(GPALComboBox gpalCombo)
        {
            FormSettings.myForm.ControlList.Add(gpalCombo);
 
            var combo = new ComboBox
            {
                Name = gpalCombo.Name,
                Enabled = gpalCombo.IsEnabled,
                DropDownStyle = ComboBoxStyle.DropDownList,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Height = 10 < gpalCombo.Height ? gpalCombo.Height : 20,
            };
 
            // populate items
            foreach (string item in gpalCombo.items)
            {
                combo.Items.Add(item);
            }
 
            // restore selection if set — by name takes priority, then by index
            if (!string.IsNullOrEmpty(gpalCombo.selectedItem))
            {
                int idx = combo.Items.IndexOf(gpalCombo.selectedItem);
                if (0 <= idx) combo.SelectedIndex = idx;
            }
            else if (0 <= gpalCombo.selectedIndex && gpalCombo.selectedIndex < combo.Items.Count)
            {
                combo.SelectedIndex = gpalCombo.selectedIndex;
            }
 
            // a disabled item is drawn greyed and refuses to be chosen. owner-draw is the only way windows
            // forms lets one entry of a dropdown say no, and it draws the ordinary way for everything else
            combo.DrawMode = DrawMode.OwnerDrawFixed;
 
            combo.DrawItem += (sender, args) =>
            {
                if (0 > args.Index) return;
 
                string text = combo.Items[args.Index].ToString();
                bool disabled = true == gpalCombo.disabledItems.Contains(text);
 
                // the highlight belongs to something choosable, so a disabled row keeps the plain background
                if (false == disabled)
                    args.DrawBackground();
                else
                    using (SolidBrush background = new SolidBrush(SystemColors.Window))
                        args.Graphics.FillRectangle(background, args.Bounds);
 
                using (SolidBrush foreground = new SolidBrush(disabled ? SystemColors.GrayText : args.ForeColor))
                    args.Graphics.DrawString(text, args.Font, foreground, args.Bounds);
 
                if (false == disabled) args.DrawFocusRectangle();
            };
 
            // put it back on the last thing that was allowed. SelectedIndexChanged fires for every route in,
            // including the keyboard and code, so this is the one place that catches them all
            combo.SelectedIndexChanged += (sender, args) =>
            {
                if (0 > combo.SelectedIndex) return;
 
                string text = combo.Items[combo.SelectedIndex].ToString();
 
                if (false == gpalCombo.disabledItems.Contains(text))
                {
                    gpalCombo.lastEnabledIndex = combo.SelectedIndex;
                    return;
                }
 
                GPAL.PublishSimpleEvent(Enums.GPALEventType.CAUTION, $"[{text}] does not apply to what is selected, so it cannot be chosen", null, Enums.GPALObjectType.GPALForm);
 
                combo.SelectedIndex = 0 <= gpalCombo.lastEnabledIndex && gpalCombo.lastEnabledIndex < combo.Items.Count
                    ? gpalCombo.lastEnabledIndex
                    : FirstEnabledIndex(combo, gpalCombo);
            };
 
            gpalCombo.lastEnabledIndex = combo.SelectedIndex;
 
            gpalCombo.WindowsControl = combo;
 
            ApplyWidth(gpalCombo.Width, combo);
 
            foreach (var (evt, handler) in gpalCombo.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.SelectedIndexChanged:
                        combo.SelectedIndexChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.ValueChanged:
                        combo.SelectedValueChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        combo.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            // Apply tooltip if set
            if (false == string.IsNullOrEmpty(gpalCombo.ToolTipText))
                ApplyToolTip(gpalCombo, combo);
 
            FormSettings.TableLayoutPanel.Controls.Add(combo);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddDataGridView(GPALDataGridView gPALDataGridView)
        {
            FormSettings.myForm.ControlList.Add(gPALDataGridView);
 
            DataGridView dgv = new DataGridView
            {
                Name = gPALDataGridView.Name,
                ReadOnly = gPALDataGridView.ReadOnly,
                AutoGenerateColumns = gPALDataGridView.AutoGenerateColumns,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Bottom | AnchorStyles.Right,
                Enabled = gPALDataGridView.IsEnabled,
                AllowUserToAddRows = false,   // usually not wanted in dashboards
                RowHeadersVisible = false,    // optional – cleaner look
                AutoSize = true,
                Height = 10 < gPALDataGridView.Height ? gPALDataGridView.Height : 20,
            };
 
            // Add explicit columns if supplied
            foreach (string colName in gPALDataGridView.ColumnNames)
            {
                dgv.Columns.Add(colName, colName);
            }
 
            gPALDataGridView.WindowsControl = dgv;
 
            ApplyWidth(gPALDataGridView.Width, dgv);
 
            // Wire callbacks (same pattern as before)
            foreach (var (evt, handler) in gPALDataGridView.Callbacks)
            {
                if (handler == null) continue;
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.CellValueChanged:
                    case ControlEventType.Change:
                        dgv.CellValueChanged += (DataGridViewCellEventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        dgv.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        dgv.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            // Populate from grid if already set during fluent chain
            gPALDataGridView.SyncGridToControl();   // ← important line
            gPALDataGridView.ApplyColumnWidths();
            gPALDataGridView.ApplyWrap();
 
            FormSettings.TableLayoutPanel.Controls.Add(dgv);
 
            // the last column takes the width the others leave, and a control with no handle yet reports no
            // width to take it from. asked again on resize so the row keeps ending at the edge of the control
            if (true == gPALDataGridView.LastColumnFills)
            {
                void fillLastColumn(object s, EventArgs e) => gPALDataGridView.FillLastColumn();
 
                dgv.Resize += fillLastColumn;
                dgv.HandleCreated += fillLastColumn;
 
                // rows arriving or leaving is what shows and hides the vertical scrollbar, and that changes
                // the width the last column has to take. neither of those raises a resize
                dgv.RowsAdded += (s, e) => gPALDataGridView.FillLastColumn();
                dgv.RowsRemoved += (s, e) => gPALDataGridView.FillLastColumn();
            }
 
            if (!string.IsNullOrWhiteSpace(gPALDataGridView.ToolTipText))
                ApplyToolTip(gPALDataGridView, dgv);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddDateTimePicker(GPALDateTimePicker gPALDateTimePicker)
        {
            FormSettings.myForm.ControlList.Add(gPALDateTimePicker);
 
            DateTimePicker dtp = new DateTimePicker
            {
                Name = gPALDateTimePicker.Name,
                Value = gPALDateTimePicker.Value,
                Format = gPALDateTimePicker.Format,
                CustomFormat = gPALDateTimePicker.CustomFormat,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Enabled = gPALDateTimePicker.IsEnabled,
                Height = 10 < gPALDateTimePicker.Height ? gPALDateTimePicker.Height : 10,
            };
 
            gPALDateTimePicker.WindowsControl = dtp;
 
            ApplyWidth(gPALDateTimePicker.Width, dtp);
 
            foreach (var (evt, handler) in gPALDateTimePicker.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.ValueChanged:
                    case ControlEventType.Change:
                        dtp.ValueChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        dtp.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(dtp);
 
            if (!string.IsNullOrWhiteSpace(gPALDateTimePicker.ToolTipText))
                ApplyToolTip(gPALDateTimePicker, dtp);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddFileSelector(GPALFileSelector gPALFileSelector)
        {
            FormSettings.myForm.ControlList.Add(gPALFileSelector);
 
            if (gPALFileSelector._compact)
                return AddFileSelectorCompact(gPALFileSelector);
 
            Button browseButton = new Button
            {
                Name = gPALFileSelector.Name + "_Browse",
                Text = "Browse...",
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Width = 80,
                Enabled = gPALFileSelector.IsEnabled
            };
 
            TextBox displayBox = new TextBox
            {
                Name = gPALFileSelector.Name + "_Path",
                ReadOnly = true,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                // the path WithSelectedPath started it on, which is the whole point of naming one: a form opens
                // on the folders it works with rather than on a box telling the user to go and find them again
                Text = true == string.IsNullOrWhiteSpace(gPALFileSelector.SelectedPath)
                     ? "(click Browse to select)"
                     : gPALFileSelector.SelectedPath,
                Enabled = gPALFileSelector.IsEnabled
            };
 
            TableLayoutPanel container = new TableLayoutPanel
            {
                ColumnCount = 2,
                RowCount = 1,
                Dock = DockStyle.Top,          // full width, hugs a single row of content (no tall default panel gap)
                // same reason as the compact selector below: auto-sizing would measure the percent column from
                // the path sitting in the box, and a long one puts a horizontal scrollbar on the whole form
                Height = Math.Max(displayBox.PreferredHeight, browseButton.Height) + 4,
                Margin = new Padding(0)
            };
            container.RowStyles.Add(new RowStyle(SizeType.Percent, 100));
            container.ColumnStyles.Add(new ColumnStyle(SizeType.Absolute, 90));
            container.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100));
            container.Controls.Add(browseButton, 0, 0);
            container.Controls.Add(displayBox, 1, 0);
 
            gPALFileSelector.WindowsControl = container;
 
            // Default, Change and Click are delivered by NotifySelection when the dialog closes, with the
            // FileSelectorEventArgs saying what was picked and whether it was cancelled. Wiring them here as
            // well would run the handler a second time with a plain EventArgs, because choosing a path sets
            // the box's text. TextChanged is the one event the box itself owns
            foreach (var (evt, handler) in gPALFileSelector.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                if (ControlEventType.TextChanged == evt)
                    displayBox.TextChanged += (EventHandler)handler;
            }
 
 
            browseButton.Click += (s, e) =>
            {
                string[] selected = OpenBrowseDialog(gPALFileSelector);
                bool cancelled = selected == null || selected.Length == 0;
                gPALFileSelector.NotifySelection(cancelled, selected);
                displayBox.Text = cancelled ? "(selection cancelled)" : string.Join("; ", selected);
            };
 
            FormSettings.TableLayoutPanel.Controls.Add(container);
 
            if (!string.IsNullOrWhiteSpace(gPALFileSelector.ToolTipText))
                ApplyToolTip(gPALFileSelector, container);
 
            return this;
        }
 
        private IAllowFormSettingsAndActions AddFileSelectorCompact(GPALFileSelector gPALFileSelector)
        {
            PlaceholderTextBox textBox = new PlaceholderTextBox
            {
                Name            = gPALFileSelector.Name + "_Path",
                Anchor          = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Enabled         = gPALFileSelector.IsEnabled,
                PlaceholderText = gPALFileSelector._placeholder,
                // after the placeholder, so the path replaces it rather than being taken for one
                Text            = gPALFileSelector.SelectedPath
            };
 
            Button dotButton = new Button
            {
                Name    = gPALFileSelector.Name + "_Browse",
                Text    = "...",
                Width   = 28,
                Anchor  = AnchorStyles.Top | AnchorStyles.Right,
                Enabled = gPALFileSelector.IsEnabled
            };
 
            TableLayoutPanel container = new TableLayoutPanel
            {
                Name = gPALFileSelector.Name,
                ColumnCount = 2,
                RowCount    = 1,
                Dock        = DockStyle.Top,   // full width, hugs a single row of content (no tall default panel gap)
                // no AutoSize. docking top already takes the width from the form, while auto-sizing measures the
                // percent column from what is in it, so a long path in the box asks the form to be wider than it
                // is and leaves a horizontal scrollbar that resizing never clears
                Height      = Math.Max(textBox.PreferredHeight, dotButton.Height) + 4,
                Margin      = new Padding(0)
            };
            container.RowStyles.Add(new RowStyle(SizeType.Percent, 100));
            container.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100));
            container.ColumnStyles.Add(new ColumnStyle(SizeType.Absolute, 32));
            container.Controls.Add(textBox,   0, 0);
            container.Controls.Add(dotButton, 1, 0);
 
            // WindowsControl points to the text box so SyncDisplay() and .Text access work naturally
            gPALFileSelector.WindowsControl = textBox;
 
            // Default, Change and Click are delivered by NotifySelection when the dialog closes, with the
            // FileSelectorEventArgs saying what was picked and whether it was cancelled. Wiring them here as
            // well would run the handler a second time with a plain EventArgs, because choosing a path sets
            // the box's text. TextChanged is the one event the box itself owns
            foreach (var (evt, handler) in gPALFileSelector.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                if (ControlEventType.TextChanged == evt)
                    textBox.TextChanged += (EventHandler)handler;
            }
 
 
            textBox.TextChanged += (s, e) => gPALFileSelector._selectedPath = textBox.Text;
 
            dotButton.Click += (s, e) =>
            {
                string[] selected = OpenBrowseDialog(gPALFileSelector);
                bool cancelled = selected == null || selected.Length == 0;
                if (!cancelled)
                    textBox.Text = selected[0];
                gPALFileSelector.NotifySelection(cancelled, selected);
            };
 
            FormSettings.TableLayoutPanel.Controls.Add(container);
 
            if (!string.IsNullOrWhiteSpace(gPALFileSelector.ToolTipText))
                ApplyToolTip(gPALFileSelector, container);
 
            return this;
        }
 
        private static string[] OpenBrowseDialog(GPALFileSelector gPALFileSelector)
        {
            if (gPALFileSelector._selectFolder)
            {
                using (FolderBrowserDialog fbd = new FolderBrowserDialog())
                {
                    fbd.Description  = gPALFileSelector._title;
                    fbd.SelectedPath = gPALFileSelector._initialDirectory;
                    return fbd.ShowDialog() == DialogResult.OK ? new[] { fbd.SelectedPath } : null;
                }
            }
            else
            {
                using (OpenFileDialog ofd = new OpenFileDialog())
                {
                    ofd.Title           = gPALFileSelector._title;
                    ofd.InitialDirectory = gPALFileSelector._initialDirectory;
                    ofd.Filter          = gPALFileSelector._filter;
                    ofd.Multiselect     = gPALFileSelector._multiSelect;
                    return ofd.ShowDialog() == DialogResult.OK ? ofd.FileNames : null;
                }
            }
        }
        private IAllowFormSettingsAndActions AddInput(GPALInput gPALInput)
        {
            FormSettings.myForm.ControlList.Add(gPALInput);
            PlaceholderTextBox input = new PlaceholderTextBox
            {
                Name = gPALInput.Name,
                Text = gPALInput.Text,
                AutoSize = true,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Enabled = gPALInput.Enabled,
                Height = 10 < gPALInput.Height ? gPALInput.Height : 20,
            };
 
            if (!string.IsNullOrEmpty(gPALInput.PlaceHolder))
                input.PlaceholderText = gPALInput.PlaceHolder;
 
            if (true == gPALInput.InputIsPassword)
                input.PasswordChar = '\u25CF';  // bullet
 
            if (true == gPALInput.IsReadOnly)
                input.ReadOnly = true;
 
            gPALInput.WindowsControl = input;
 
            ApplyWidth(gPALInput.Width, input);
 
            input.Text = gPALInput.Text;   // somehow text is getting truncated to one char from above
 
            input.TextChanged += new EventHandler(delegate (Object sender, EventArgs a) { gPALInput.Text = ((TextBox)sender).Text; }); // copy changed text up to control
 
            foreach (var (evt, handler) in gPALInput.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.TextChanged:
                        input.TextChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        input.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        input.Click += (EventHandler)handler;
                        break;
 
                    case ControlEventType.KeyDown:
                        input.KeyDown += (KeyEventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(input);
 
            if (!string.IsNullOrWhiteSpace(gPALInput.ToolTipText))
                ApplyToolTip(gPALInput, input);
 
            return this;
        }
        // narrower than this and the label has not been laid out yet
        private const int MinimumWidthToMeasure = 60;
 
        private void FitLabelHeight(Label label)
        {
            // a label being laid out has a width of a few pixels before it is given its real one, and measuring
            // against that wraps one line of text onto three. the height that produces is then what everything
            // measuring this label adds up, so nothing is fitted until there is a width worth fitting to
            if (MinimumWidthToMeasure < label.Width)
            {
                Size measured = TextRenderer.MeasureText(label.Text, label.Font, new Size(label.Width, int.MaxValue),
                    TextFormatFlags.WordBreak | TextFormatFlags.TextBoxControl);
 
                int wanted = 18 > measured.Height ? 18 : measured.Height;
 
                if (label.Height != wanted)
                    label.Height = wanted;
            }
        }

        private IAllowFormSettingsAndActions AddSpacer(GPALSpacer gPALSpacer)
        {
            FormSettings.myForm.ControlList.Add(gPALSpacer);
            Panel spacer = new Panel
            {
                Name = gPALSpacer.Name,
                Height = gPALSpacer.Height,
                Margin = Padding.Empty,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
            };
 
            gPALSpacer.WindowsControl = spacer;
 
            FormSettings.TableLayoutPanel.Controls.Add(spacer);
 
            return this;
        }

        private IAllowFormSettingsAndActions AddLinkLabel(GPALLinkLabel gPALLinkLabel)
        {
            FormSettings.myForm.ControlList.Add(gPALLinkLabel);
            LinkLabel link = new LinkLabel
            {
                Name = gPALLinkLabel.Name,
                Enabled = gPALLinkLabel.IsEnabled,
                Text = gPALLinkLabel.Text,
                TextAlign = gPALLinkLabel.TextAlignment,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                AutoSize = false,
            };
            // the size a label uses, and regular rather than bold, so it reads as a link beside the labels
            link.Font = new Font(gPALLinkLabel.FontType.FontFamily, 10f, FontStyle.Regular);
            link.Height = 18 < gPALLinkLabel.Height ? gPALLinkLabel.Height : 18;
 
            // sized to its text as the width changes, the same as a label, unless a height was asked for
            if (18 >= gPALLinkLabel.Height)
                link.SizeChanged += (sender, args) => FitLabelHeight(link);
 
            link.LinkClicked += (sender, args) => gPALLinkLabel.Open();
 
            gPALLinkLabel.WindowsControl = link;
 
            ApplyWidth(gPALLinkLabel.Width, link);
 
            foreach (var (evt, handler) in gPALLinkLabel.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.DoubleClick:
                        link.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Default:
                    case ControlEventType.Click:
                        link.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(link);
 
            if (!string.IsNullOrWhiteSpace(gPALLinkLabel.ToolTipText))
                ApplyToolTip(gPALLinkLabel, link);
 
            return this;
        }
 
        private IAllowFormSettingsAndActions AddLabel(GPALLabel gPALLabel)
        {
            FormSettings.myForm.ControlList.Add(gPALLabel);
            Label label = new Label
            {
                Name = gPALLabel.Name,
                Enabled = gPALLabel.IsEnabled,
                Text = gPALLabel.Text,
                Font = gPALLabel.FontType,
                TextAlign = gPALLabel.TextAlignment,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
            };
            label.Font = new Font(label.Font.FontFamily, 10f, FontStyle.Bold);
 
            label.AutoSize = false;
            label.Height = 18 < gPALLabel.Height ? gPALLabel.Height : 18;
 
            // a Label wraps its text and then clips every line below the first, which is how the end of a long
            // caption goes missing. no height was asked for, so the label takes the height its text needs at
            // whatever width the layout gives it, and takes it again each time that width changes
            if (18 >= gPALLabel.Height)
                label.SizeChanged += (sender, args) => FitLabelHeight(label);
 
            gPALLabel.WindowsControl = label;
 
            ApplyWidth(gPALLabel.Width, label);
 
            foreach (var (evt, handler) in gPALLabel.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.DoubleClick:
                        label.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Default:
                    case ControlEventType.Click:
                        label.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(label);
 
            if (!string.IsNullOrWhiteSpace(gPALLabel.ToolTipText))
                ApplyToolTip(gPALLabel, label);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddListView(GPALListView gPALListView)
        {
            FormSettings.myForm.ControlList.Add(gPALListView);
 
            ListView listView = new ListView
            {
                Name = gPALListView.Name,
                View = gPALListView.ViewMode,
                FullRowSelect = gPALListView.FullRowSelect,
                MultiSelect = gPALListView.MultiSelect,
                CheckBoxes = gPALListView.checkBoxes,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Bottom | AnchorStyles.Right,
                Enabled = gPALListView.IsEnabled,
                Height = 10 < gPALListView.Height ? gPALListView.Height: 150,
            };
 
            // Add columns
            foreach (string header in gPALListView.Columns)
            {
                listView.Columns.Add(header, -2, HorizontalAlignment.Left);  // auto-size
            }
 
            gPALListView.WindowsControl = listView;
 
            ApplyWidth(gPALListView.Width, listView);
            gPALListView.ApplyColumnWidths();
 
            // a greyed row is not a selectable one. ListView has no cancellable selection event, so the
            // selection is taken back off as soon as it lands
            listView.ItemSelectionChanged += (sender, args) =>
            {
                if (true == args.IsSelected && SystemColors.GrayText == args.Item.ForeColor)
                    args.Item.Selected = false;
            };
 
            foreach (var (evt, handler) in gPALListView.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.SelectedIndexChanged:
                    case ControlEventType.Change:
                        listView.SelectedIndexChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        listView.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        listView.Click += (EventHandler)handler;
                        break;
 
                    // checking a row is not selecting one, and a list with checkboxes is usually asking
                    // about the checks rather than the highlight
                    case ControlEventType.ItemChecked:
                        listView.ItemChecked += (ItemCheckedEventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(listView);
 
            if (gPALListView.Sortable)
            {
                var comparer = new ListViewItemComparer();
                listView.ListViewItemSorter = comparer;
                listView.ColumnClick += (s, e) =>
                {
                    if (comparer.Column == e.Column)
                        comparer.Order = comparer.Order == SortOrder.Ascending
                            ? SortOrder.Descending : SortOrder.Ascending;
                    else
                    {
                        comparer.Column = e.Column;
                        comparer.Order  = SortOrder.Ascending;
                    }
                    listView.Sort();
                };
            }
 
            if (gPALListView.ColumnWeights.Count > 0)
            {
                var weights = gPALListView.ColumnWeights;
                double total = 0;
                foreach (var w in weights) total += w;
                if (total <= 0) total = 1;
 
                void applyWeights(object s, EventArgs e)
                {
                    int available = listView.ClientSize.Width - SystemInformation.VerticalScrollBarWidth;
                    if (available <= 0) return;
                    for (int i = 0; i < weights.Count && i < listView.Columns.Count; i++)
                        listView.Columns[i].Width = (int)(available * weights[i] / total);
                }
 
                listView.Resize += applyWeights;
                listView.HandleCreated += applyWeights;
            }
 
            // the columns are worked out whole, once the control can measure itself and again when it
            // changes size. A control with no handle yet reports no width to divide up, and a list on a tab
            // nobody has opened has no handle until that tab is first shown
            if (true == gPALListView.LastColumnFills)
            {
                void layOutColumns(object s, EventArgs e) => gPALListView.LayOutColumns();
 
                listView.Resize += layOutColumns;
                listView.HandleCreated += layOutColumns;
            }
 
            if (!string.IsNullOrWhiteSpace(gPALListView.ToolTipText))
                ApplyToolTip(gPALListView, listView);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddNumericUpDown(GPALNumericUpDown gPALNumericUpDown)
        {
            FormSettings.myForm.ControlList.Add(gPALNumericUpDown);
 
            NumericUpDown nud = new NumericUpDown
            {
                Name = gPALNumericUpDown.Name,
                Value = gPALNumericUpDown.Value,
                Minimum = gPALNumericUpDown.Minimum,
                Maximum = gPALNumericUpDown.Maximum,
                Increment = gPALNumericUpDown.Increment,
                DecimalPlaces = gPALNumericUpDown.DecimalPlaces,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Enabled = gPALNumericUpDown.IsEnabled,
                Height = 10 < gPALNumericUpDown.Height ? gPALNumericUpDown.Height : 20,
            };
 
            gPALNumericUpDown.WindowsControl = nud;
 
            ApplyWidth(gPALNumericUpDown.Width, nud);
 
            foreach (var (evt, handler) in gPALNumericUpDown.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.ValueChanged:
                    case ControlEventType.Change:
                        nud.ValueChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        nud.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(nud);
 
            if (!string.IsNullOrWhiteSpace(gPALNumericUpDown.ToolTipText))
                ApplyToolTip(gPALNumericUpDown, nud);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddPicture(GPALPicture gPALPicture)
        {
            FormSettings.myForm.ControlList.Add(gPALPicture);
 
            PictureBox pictureBox = new PictureBox
            {
                Name = gPALPicture.Name,
                Enabled = gPALPicture.IsEnabled,
                Image = gPALPicture.Image,
                SizeMode = gPALPicture.SizeMode,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Height = 10 < gPALPicture.Height ? gPALPicture.Height : 150,
            };
 
            gPALPicture.WindowsControl = pictureBox;
 
            ApplyWidth(gPALPicture.Width, pictureBox);
 
            foreach (var (evt, handler) in gPALPicture.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.Click:
                        pictureBox.Click += (EventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        pictureBox.DoubleClick += (EventHandler)handler;
                        break;
 
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(pictureBox);
 
            if (!string.IsNullOrWhiteSpace(gPALPicture.ToolTipText))
                ApplyToolTip(gPALPicture, pictureBox);
 
            return this;
        }

        private IAllowFormSettingsAndActions AddSlider(GPALSlider gPALSlider)
        {
            FormSettings.myForm.ControlList.Add(gPALSlider);
 
            TrackBar slider = new TrackBar
            {
                Name = gPALSlider.Name,
                Minimum = gPALSlider.Minimum,
                Maximum = gPALSlider.Maximum,
                TickFrequency = 1 > gPALSlider.TickFrequency ? 1 : gPALSlider.TickFrequency,
                Orientation = gPALSlider.Orientation,
                Value = gPALSlider.Value,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Enabled = gPALSlider.IsEnabled,
                Height = 10 < gPALSlider.Height ? gPALSlider.Height : 45,
            };
 
            gPALSlider.WindowsControl = slider;
 
            ApplyWidth(gPALSlider.Width, slider);
 
            foreach (var (evt, handler) in gPALSlider.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.ValueChanged:
                    case ControlEventType.Change:
                        slider.ValueChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Scroll:
                        slider.Scroll += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        slider.Click += (EventHandler)handler;
                        break;
 
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(slider);
 
            if (!string.IsNullOrWhiteSpace(gPALSlider.ToolTipText))
                ApplyToolTip(gPALSlider, slider);
 
            return this;
        }

        private IAllowFormSettingsAndActions AddProgressBar(GPALProgressBar gPALProgressBar)
        {
            FormSettings.myForm.ControlList.Add(gPALProgressBar);
 
            ProgressBar progressBar = new ProgressBar
            {
                Name = gPALProgressBar.Name,
                Minimum = gPALProgressBar.Minimum,
                Maximum = gPALProgressBar.Maximum,
                Value = gPALProgressBar.Value,
                Style = gPALProgressBar.Style,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Enabled = gPALProgressBar.IsEnabled,
                Height = 10 < gPALProgressBar.Height ? gPALProgressBar.Height : 20,
            };
 
            gPALProgressBar.WindowsControl = progressBar;
 
            ApplyWidth(gPALProgressBar.Width, progressBar);
 
            foreach (var (evt, handler) in gPALProgressBar.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.Click:
                        progressBar.Click += (EventHandler)handler;
                        break;
 
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(progressBar);
 
            if (!string.IsNullOrWhiteSpace(gPALProgressBar.ToolTipText))
                ApplyToolTip(gPALProgressBar, progressBar);
 
            return this;
        }

        private IAllowFormSettingsAndActions AddRadioButton(GPALRadioButton gPALRadioButton)
        {
            FormSettings.myForm.ControlList.Add(gPALRadioButton);
            RadioButton radioButton = new RadioButton
            {
                Name = gPALRadioButton.Name,
                Text = gPALRadioButton.Text,
                AutoSize = true,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right,
                Checked = gPALRadioButton.Checked,
                Enabled = gPALRadioButton.Enabled,
                Height = 10 < gPALRadioButton.Height ? gPALRadioButton.Height : 20,
            };
            gPALRadioButton.WindowsControl = radioButton;
 
            ApplyWidth(gPALRadioButton.Width, radioButton);
            radioButton.CheckedChanged += new EventHandler(delegate (Object sender, EventArgs a) { gPALRadioButton.Checked = ((RadioButton)sender).Checked; }); // copy changed text up to control
 
            foreach (var (evt, handler) in gPALRadioButton.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.CheckedChanged:
                        radioButton.CheckedChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        radioButton.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(radioButton);
 
            if (!string.IsNullOrWhiteSpace(gPALRadioButton.ToolTipText))
                ApplyToolTip(gPALRadioButton, radioButton);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddStatusStrip(GPALStatusStrip gPALStatusStrip)
        {
            FormSettings.myForm.ControlList.Add(gPALStatusStrip);
 
            StatusStrip statusStrip = new StatusStrip
            {
                Name = gPALStatusStrip.Name,
                Dock = DockStyle.Bottom,
                SizingGrip = false,
                Enabled = gPALStatusStrip.IsEnabled,
                Height = 10 < gPALStatusStrip.Height ? gPALStatusStrip.Height : 20,
            };
 
            ToolStripStatusLabel statusLabel = new ToolStripStatusLabel
            {
                Text = gPALStatusStrip.Text,
                Spring = true,
                TextAlign = ContentAlignment.MiddleLeft,
                Height = 10 < gPALStatusStrip.Height ? gPALStatusStrip.Height : 20,
            };
 
            statusStrip.Items.Add(statusLabel);
 
            gPALStatusStrip.WindowsControl = statusStrip;
 
            foreach (var (evt, handler) in gPALStatusStrip.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Click:
                    case ControlEventType.Default:
                        statusStrip.ItemClicked += (sender, e) => ((EventHandler)handler)(sender, e);
                        break;
 
                        // ignore unsupported
                }
            }
 
            // StatusStrip is added directly to the form (not TableLayoutPanel)
            FormSettings.myForm.Controls.Add(statusStrip);
 
            if (!string.IsNullOrWhiteSpace(gPALStatusStrip.ToolTipText))
                ApplyToolTip(gPALStatusStrip, statusStrip);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddMenuBar(GPALMenuBar gPALMenuBar)
        {
            FormSettings.myForm.ControlList.Add(gPALMenuBar);
 
            MenuStrip menuStrip = new MenuStrip
            {
                Name = gPALMenuBar.Name,
                Enabled = gPALMenuBar.IsEnabled,
            };
 
            var topMenus = new System.Collections.Generic.Dictionary<string, ToolStripMenuItem>();
            foreach (var (topMenu, item, isSeparator) in gPALMenuBar.menuEntries)
            {
                string menuKey = string.IsNullOrWhiteSpace(topMenu) ? "" : topMenu;
                if (!topMenus.TryGetValue(menuKey, out ToolStripMenuItem topItem))
                {
                    topItem = new ToolStripMenuItem(menuKey);
                    topMenus[menuKey] = topItem;
                    menuStrip.Items.Add(topItem);
                }
 
                if (isSeparator)
                {
                    topItem.DropDownItems.Add(new ToolStripSeparator());
                    continue;
                }
 
                ToolStripMenuItem menuItem = new ToolStripMenuItem(item.Text);
                if (item.Image != null)
                    menuItem.Image = item.Image;
                if (item.ShortCutKey != System.Windows.Forms.Keys.None)
                {
                    menuItem.ShortcutKeys = item.ShortCutKey;
                    menuItem.ShowShortcutKeys = true;
                }
                // ForEvent was destructured and thrown away, so every handler became a Click whatever the
                // workflow asked for. Click is what a menu item does, so it stays the default
                foreach (var (evt, handler) in item.Callbacks)
                {
                    if (null == handler) continue; // skip invalid
 
                    switch (evt)
                    {
                        case ControlEventType.Default:
                        case ControlEventType.Click:
                            menuItem.Click += (EventHandler)handler;
                            break;
 
                        case ControlEventType.DoubleClick:
                            menuItem.DoubleClick += (EventHandler)handler;
                            break;
                            // ignore unsupported
                    }
                }
                if (!string.IsNullOrWhiteSpace(item.ToolTipText))
                    menuItem.ToolTipText = item.ToolTipText;
 
                // what WithEnabled said before the form existed, applied now that the item does
                menuItem.Enabled = item.IsEnabled;
                item.WindowsControl = menuItem;
                topItem.DropDownItems.Add(menuItem);
            }
 
            gPALMenuBar.WindowsControl = menuStrip;
 
            // MenuStrip docks to the top of the form (not the TableLayoutPanel)
            FormSettings.myForm.Controls.Add(menuStrip);
            FormSettings.myForm.MainMenuStrip = menuStrip;
 
            // A top-docked MenuStrip must sit above any top-docked toolbar. Docked siblings fill from the
            // edge in reverse child-index order, so pushing the menu to the highest index keeps it outermost.
            FormSettings.myForm.Controls.SetChildIndex(menuStrip, FormSettings.myForm.Controls.Count - 1);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddToolbar(GPALToolbar gPALToolbar)
        {
            FormSettings.myForm.ControlList.Add(gPALToolbar);
 
            ToolStrip toolStrip = new ToolStrip
            {
                Name = gPALToolbar.Name,
                Enabled = gPALToolbar.IsEnabled,
            };
 
            foreach (var (item, isSeparator) in gPALToolbar.toolbarEntries)
            {
                if (isSeparator)
                {
                    toolStrip.Items.Add(new ToolStripSeparator());
                    continue;
                }
 
                ToolStripButton button = new ToolStripButton(item.Text);
                if (item.Image != null)
                {
                    button.Image = item.Image;
                    button.DisplayStyle = string.IsNullOrWhiteSpace(item.Text)
                        ? ToolStripItemDisplayStyle.Image
                        : ToolStripItemDisplayStyle.ImageAndText;
                }
                else
                    button.DisplayStyle = ToolStripItemDisplayStyle.Text;
 
                // the same as the menu bar: the event asked for is honoured rather than assumed to be Click
                foreach (var (evt, handler) in item.Callbacks)
                {
                    if (null == handler) continue; // skip invalid
 
                    switch (evt)
                    {
                        case ControlEventType.Default:
                        case ControlEventType.Click:
                            button.Click += (EventHandler)handler;
                            break;
 
                        case ControlEventType.DoubleClick:
                            button.DoubleClick += (EventHandler)handler;
                            break;
                            // ignore unsupported
                    }
                }
                if (!string.IsNullOrWhiteSpace(item.ToolTipText))
                    button.ToolTipText = item.ToolTipText;
 
                button.Enabled = item.IsEnabled;
                item.WindowsControl = button;
                toolStrip.Items.Add(button);
            }
 
            gPALToolbar.WindowsControl = toolStrip;
 
            // ToolStrip docks to the top of the form (not the TableLayoutPanel), below any MenuStrip.
            FormSettings.myForm.Controls.Add(toolStrip);
            if (FormSettings.myForm.MainMenuStrip != null)
                FormSettings.myForm.Controls.SetChildIndex(FormSettings.myForm.MainMenuStrip, FormSettings.myForm.Controls.Count - 1);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddTab(GPALTab gPALTab)
        {
            if (null == FormSettings.TabControl)
            {
                FormSettings.TabControl = new TabControl
                {
                    Name = "tabControl",
                    AutoSize = false,
                    //Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right | AnchorStyles.Bottom,
                    Dock = DockStyle.Fill,
                    Multiline = true,
 
                };
 
                // a disabled TabPage greys its contents and is still selectable, so the tab stays reachable
                // and lands on a page nothing can be done with. refusing the switch is what disables a tab
                FormSettings.TabControl.Selecting += (sender, args) =>
                {
                    // nothing selected yet means the pages are still being added, and refusing that would
                    // leave the control showing no tab at all
                    if (null == FormSettings.TabControl.SelectedTab) return;
 
                    if (null != args.TabPage && false == args.TabPage.Enabled) args.Cancel = true;
                };
 
                FormSettings.TableLayoutPanel.Controls.Add(FormSettings.TabControl);
            }
 
            TabPage tabPage = new TabPage
            {
                Name = gPALTab.Name,
                Text = gPALTab.Text,
                AutoSize = false,
                //Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right | AnchorStyles.Bottom,
                Dock = DockStyle.Fill,
                Enabled = gPALTab.Enabled
            };
 
            TableLayoutPanel tmpTableLayoutPanel = new TableLayoutPanel
            {
                //Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Bottom | AnchorStyles.Right,
                Dock = DockStyle.Fill,
                AutoSize = false,
 
                // the same as the form's own panel. without it a tab holding more than fits simply hides the
                // rest, with no scrollbar to say so, and the controls at the bottom may as well not be there
                AutoScroll = true
            };
 
            gPALTab.WindowsControl = tabPage;
 
            FormSettings.myForm.ControlList.Add(gPALTab);
 
            foreach (var (evt, handler) in gPALTab.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Scroll:
                        tabPage.Scroll += (ScrollEventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        // the page's own click, which is the blank area around the controls on it. rarely what
                        // anyone means by clicking a tab, which is why it has to be asked for by name
                        tabPage.Click += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Default:
                    case ControlEventType.SelectedIndexChanged:
                    case ControlEventType.Change:
                        // being the tab on show is what a tab is for, so it is the one you get without saying.
                        // a TabPage has no event for it: the control that owns the pages has one, and it names
                        // the page it moved to, so each tab hears only about itself
                        FormSettings.TabControl.Selected += (sender, args) =>
                        {
                            if (args.TabPage == tabPage)
                                ((EventHandler)handler)(gPALTab, args);
                        };
                        break;
                        // ignore unsupported
                }
            }
 
            tabPage.Controls.Add(tmpTableLayoutPanel);
            FormSettings.TabControl.Controls.Add(tabPage);
            FormSettings.TableLayoutPanel = tmpTableLayoutPanel;
 
            if (!string.IsNullOrWhiteSpace(gPALTab.ToolTipText))
                ApplyToolTip(gPALTab, tabPage);
 
            return this;
        }
 
        private IAllowFormSettingsAndActions AddSplitter(GPALSplitter gPALSplitter)
        {
            FormSettings.myForm.ControlList.Add(gPALSplitter);
 
            SplitContainer sc = new SplitContainer
            {
                Name = gPALSplitter.Name,
                Enabled = gPALSplitter.IsEnabled,
                // a vertical bar gives left and right panes, a horizontal one top and bottom
                Orientation = true == gPALSplitter.IsHorizontalSplit ? Orientation.Vertical : Orientation.Horizontal,
                // anchored rather than docked, the same as every other control GPAL adds. A docked control in a
                // TableLayoutPanel cell does not keep its own height: the cell sizes it, and the cell is measured
                // from PreferredSize, which for a SplitContainer ignores the height set on it. Anchoring left and
                // right still gives full width. The height is measured once the panes are filled, below, unless
                // .WithHeight already said what it should be. With no height of its own the splitter's row takes
                // the spare height of the form, and anchoring the bottom as well is what lets it fill that row
                // down to whatever sits below it, the way a list view does
                Anchor = 10 < gPALSplitter.Height
                    ? AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right
                    : AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right | AnchorStyles.Bottom,
                Height = 10 < gPALSplitter.Height ? gPALSplitter.Height : 0,
                AutoScaleMode = AutoScaleMode.Inherit,
                // the height is what says this is a band of a stated size rather than a container that takes
                // what is left. Reading that off the control's name meant an unnamed splitter grew instead
                Tag = 10 < gPALSplitter.Height ? SetHeightMarker : null
            };
 
            if (true == gPALSplitter.IsPercentage)
            {
                double pct = gPALSplitter.Percentage;
 
                // a proportion has to be reapplied as the form resizes, where a pixel distance stays put
                sc.SizeChanged += (s, e) =>
                {
                    int along = true == gPALSplitter.IsHorizontalSplit ? sc.Width : sc.Height;
 
                    if (along > sc.Panel1MinSize + sc.Panel2MinSize + sc.SplitterWidth)
                        sc.SplitterDistance = (int)(along * pct);
                };
            }
            else
                sc.SplitterDistance = gPALSplitter.Dimension;
 
            gPALSplitter.WindowsControl = sc;
 
            // where the user dragged the divider to is the one thing a workflow wants from a splitter, so that
            // is what a handler with no event named answers
            foreach (var (evt, handler) in gPALSplitter.Callbacks)
            {
                if (null == handler) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.SplitterMoved:
                        sc.SplitterMoved += (SplitterEventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        sc.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        sc.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            TableLayoutPanel firstPane = MakeSplitPaneTlp();
            TableLayoutPanel secondPane = MakeSplitPaneTlp();
 
            sc.Panel1.Controls.Add(firstPane);
            sc.Panel2.Controls.Add(secondPane);
            FormSettings.TableLayoutPanel.Controls.Add(sc);
 
            FillContainer(gPALSplitter.FormControls, firstPane, secondPane, gPALSplitter.Name);
 
 
            // a SplitContainer cannot size itself to what is inside it, so it is measured here instead of being
            // given a number someone guessed. Side by side panes are as tall as the taller one; stacked panes are
            // as tall as both plus the bar. .WithHeight overrides all of it
            if (10 >= gPALSplitter.Height)
            {
                // asking a pane for its PreferredSize hands back the height it already has, because it is docked to
                // fill the pane it is in, so it can only ever agree with the splitter it was measured from. what is
                // actually wanted is the height of the controls in it, which is what this adds up
                Func<TableLayoutPanel, int> contentHeight = pane =>
                {
                    int total = pane.Padding.Top + pane.Padding.Bottom;
 
                    foreach (Control child in pane.Controls)
                        total += child.Height + child.Margin.Bottom;
 
                    return total;
                };
 
 
                sc.Height = true == gPALSplitter.IsHorizontalSplit
                    ? Math.Max(contentHeight(firstPane), contentHeight(secondPane))
                    : contentHeight(firstPane) + contentHeight(secondPane) + sc.SplitterWidth;
            }
 
            if (!string.IsNullOrWhiteSpace(gPALSplitter.ToolTipText))
                ApplyToolTip(gPALSplitter, sc);
 
            return this;
        }
 
        // what a GroupBox pads by on its own, kept here because the bottom is adjusted from it
        private const int GroupBoxPadding = 3;
 
        // how much further the bottom is padded so the last control's border clears the box's border
        private const int GroupBoxBottomClearance = 2;

        private IAllowFormSettingsAndActions AddGroupBox(GPALGroupBox gPALGroupBox)
        {
            FormSettings.myForm.ControlList.Add(gPALGroupBox);
 
            GroupBox gb = new GroupBox
            {
                Name = gPALGroupBox.Name,
                Text = gPALGroupBox.Text,
                Enabled = gPALGroupBox.IsEnabled,
                // full width and only as tall as what is inside. Docking it to fill hands its size to the parent,
                // which is what stops a box growing to show its own controls.
                // NOTE: DockStyle is not a flags enum, so Top | Bottom is Left rather than both
                Dock = DockStyle.Top,
                AutoSize = true,
                AutoSizeMode = AutoSizeMode.GrowAndShrink,
                // the box is measured from the panel docked inside it, and that measurement lands short: the
                // bottom border of the last control ends up under the box's own border. the default padding
                // plus this is what puts that border back where it can be seen
                Padding = new Padding(GroupBoxPadding, GroupBoxPadding, GroupBoxPadding, GroupBoxPadding + GroupBoxBottomClearance),
            };
 
            // the panel inside has to measure its contents too, or the box is asked to grow around something that
            // never reports a size. A splitter pane is the opposite case and fills, so this is not MakeSplitPaneTlp
            TableLayoutPanel inside = new TableLayoutPanel
            {
                Dock = DockStyle.Top,
                //AutoSize = true,
                AutoSizeMode = AutoSizeMode.GrowAndShrink,
                ColumnCount = 1,
            };
 
            inside.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100f));
            gb.Controls.Add(inside);
            FormSettings.TableLayoutPanel.Controls.Add(gb);
 
            gPALGroupBox.WindowsControl = gb;
 
            FillContainer(gPALGroupBox.FormControls, inside, null, gPALGroupBox.Name);
 
            if (!string.IsNullOrWhiteSpace(gPALGroupBox.ToolTipText))
                ApplyToolTip(gPALGroupBox, gb);
 
            return this;
        }

        private void FillContainer(List<object> formControls, TableLayoutPanel firstPane, TableLayoutPanel secondPane, string name)
        {
            TableLayoutPanel outerPanel = FormSettings.TableLayoutPanel;
            TabControl outerTabControl = FormSettings.TabControl;
            TableLayoutPanel current = firstPane;
            bool markerSeen = false;
 
            FormSettings.TabControl = null;
 
            foreach (object formControl in formControls)
            {
                if (formControl is GPALSpliter)
                {
                    if (null == secondPane)
                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"[{name}] has no second pane, so the pane marker does nothing. Everything added stays in the one panel.");
                    else if (true == markerSeen)
                        GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"[{name}] has more than one pane marker and a splitter has only two panes, so everything after the first marker stays in the second.");
                    else
                    {
                        current = secondPane;
                        markerSeen = true;
                    }
 
                    continue;
                }
 
                FormSettings.TableLayoutPanel = current;
                FormSettings.TabControl = null;
                WithFormControl((GPALControl)formControl);
            }
 
            FormSettings.TableLayoutPanel = outerPanel;
            FormSettings.TabControl = outerTabControl;
        }
 
        private TableLayoutPanel MakeSplitPaneTlp()
        {
            var tlp = new TableLayoutPanel
            {
                Dock = DockStyle.Fill,
                AutoSize = false,
                ColumnCount = 1,
            };
            tlp.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100f));
            return tlp;
        }

        private IAllowFormSettingsAndActions AddTableLayoutPanel(GPALTableLayoutPanel gPALTableLayoutPanel)
        {
            FormSettings.myForm.ControlList.Add(gPALTableLayoutPanel);
            TableLayoutPanel tableLayoutPanel = new TableLayoutPanel
            {
                Name = gPALTableLayoutPanel.Name,
                GrowStyle = gPALTableLayoutPanel.GrowStyle,
                AutoScroll = false,
                ColumnCount = gPALTableLayoutPanel.ColumnCount,
                RowCount = gPALTableLayoutPanel.RowCount,
                Enabled = gPALTableLayoutPanel.IsEnabled,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right
                // todo : more settings
            };
 
            // the control every other Add sets and this one did not, so the panel was built and then dropped:
            // nothing on screen, and every later property read fell down the not-yet-realized path
            gPALTableLayoutPanel.WindowsControl = tableLayoutPanel;
 
            FormSettings.TableLayoutPanel.Controls.Add(tableLayoutPanel);
 
            if (!string.IsNullOrWhiteSpace(gPALTableLayoutPanel.ToolTipText))
                ApplyToolTip(gPALTableLayoutPanel, tableLayoutPanel);
 
            return this;
        }

        private IAllowFormSettingsAndActions AddTextArea(GPALTextArea gPALTextArea)
        {
            FormSettings.myForm.ControlList.Add(gPALTextArea);
            PlaceholderTextBox textBox = new PlaceholderTextBox
            {
                Name = gPALTextArea.Name,
                Text = gPALTextArea.Text,
                Multiline = true,
                WordWrap = true,
                ScrollBars = ScrollBars.Both,
                Height = 10 < gPALTextArea.Height ? gPALTextArea.Height : 150,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Bottom | AnchorStyles.Right,
                Enabled = gPALTextArea.Enabled
            };
            if (true == gPALTextArea.IsReadOnly)
                textBox.ReadOnly = true;
 
            if (!string.IsNullOrEmpty(gPALTextArea.PlaceHolder))
                textBox.PlaceholderText = gPALTextArea.PlaceHolder;
 
            gPALTextArea.WindowsControl = textBox;
 
            ApplyWidth(gPALTextArea.Width, textBox);
            textBox.Text = gPALTextArea.Text;   // somehow text is getting truncated to one char from above
 
            textBox.TextChanged += new EventHandler(delegate (Object sender, EventArgs a) { gPALTextArea.Text = ((TextBox)sender).Text; }); // copy changed text up to control
 
            foreach (var (evt, handler) in gPALTextArea.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.TextChanged:
                        textBox.TextChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        textBox.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(textBox);
 
            if (!string.IsNullOrWhiteSpace(gPALTextArea.ToolTipText))
                ApplyToolTip(gPALTextArea, textBox);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddRichTextBox(GPALRichTextBox gPALRichTextBox)
        {
            FormSettings.myForm.ControlList.Add(gPALRichTextBox);
            RichTextBox richTextBox = new RichTextBox
            {
                Name = gPALRichTextBox.Name,
                Multiline = true,
                WordWrap = true,
                ReadOnly = gPALRichTextBox.IsReadOnly,
                ScrollBars = RichTextBoxScrollBars.Both,
                Height = 10 < gPALRichTextBox.Height ? gPALRichTextBox.Height : 150,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Bottom | AnchorStyles.Right,
                Enabled = gPALRichTextBox.Enabled
            };
            gPALRichTextBox.WindowsControl = richTextBox;
 
            ApplyWidth(gPALRichTextBox.Width, richTextBox);
            GPALRichTextBox.RenderMarkdown(richTextBox, gPALRichTextBox.Text);
 
            // the control's text is the rendered Markdown, so nothing is copied back up here: Text holds the
            // source the workflow gave and RenderMarkdown is what puts it on screen
            foreach (var (evt, handler) in gPALRichTextBox.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.TextChanged:
                        richTextBox.TextChanged += (EventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        richTextBox.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        richTextBox.Click += (EventHandler)handler;
                        break;
 
                    case ControlEventType.KeyDown:
                        richTextBox.KeyDown += (KeyEventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(richTextBox);
 
            if (!string.IsNullOrWhiteSpace(gPALRichTextBox.ToolTipText))
                ApplyToolTip(gPALRichTextBox, richTextBox);
 
            return this;
        }
        private IAllowFormSettingsAndActions AddTreeView(GPALTreeView gPALTreeView)
        {
            FormSettings.myForm.ControlList.Add(gPALTreeView);
 
            TreeView tv = new TreeView
            {
                Name = gPALTreeView.Name,
                CheckBoxes = gPALTreeView.CheckBoxes,
                ShowLines = gPALTreeView.ShowLines,
                ShowPlusMinus = gPALTreeView.ShowPlusMinus,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Bottom | AnchorStyles.Right,
                Enabled = gPALTreeView.IsEnabled,
                Height = 10 < gPALTreeView.Height ? gPALTreeView.Height : 150,
            };
 
            // BeforeSelect can refuse outright, so a greyed node never becomes the selected one
            tv.BeforeSelect += (sender, args) =>
            {
                if (null != args.Node && SystemColors.GrayText == args.Node.ForeColor) args.Cancel = true;
            };
 
            gPALTreeView.WindowsControl = tv;
 
            ApplyWidth(gPALTreeView.Width, tv);
 
            foreach (var (evt, handler) in gPALTreeView.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    case ControlEventType.Default:
                    case ControlEventType.AfterSelect:
                    case ControlEventType.Change:
                        tv.AfterSelect += (TreeViewEventHandler)handler;
                        break;
 
                    case ControlEventType.DoubleClick:
                        tv.DoubleClick += (EventHandler)handler;
                        break;
 
                    case ControlEventType.Click:
                        tv.Click += (EventHandler)handler;
                        break;
                        // ignore unsupported
                }
            }
 
            FormSettings.TableLayoutPanel.Controls.Add(tv);
 
            if (!string.IsNullOrWhiteSpace(gPALTreeView.ToolTipText))
                ApplyToolTip(gPALTreeView, tv);
 
            return this;
        }
        #endregion <private>
    }
 
    internal class ListViewItemComparer : System.Collections.IComparer
    {
        public int       Column { get; set; } = 0;
        public SortOrder Order  { get; set; } = SortOrder.Ascending;
 
        public int Compare(object x, object y)
        {
            var lx = (ListViewItem)x;
            var ly = (ListViewItem)y;
 
            string sx = Column == 0 ? lx.Text
                : Column < lx.SubItems.Count ? lx.SubItems[Column].Text : string.Empty;
            string sy = Column == 0 ? ly.Text
                : Column < ly.SubItems.Count ? ly.SubItems[Column].Text : string.Empty;
 
            int result;
 
            // Numeric (strip currency/percent symbols and commas)
            string nx = sx.Replace(",", "").Replace("$", "").Replace("%", "").Trim();
            string ny = sy.Replace(",", "").Replace("$", "").Replace("%", "").Trim();
            if (double.TryParse(nx, out double dx) && double.TryParse(ny, out double dy))
                result = dx.CompareTo(dy);
            // Date
            else if (System.DateTime.TryParse(sx, out System.DateTime dtx) &&
                     System.DateTime.TryParse(sy, out System.DateTime dty))
                result = dtx.CompareTo(dty);
            // String
            else
                result = string.Compare(sx, sy, StringComparison.OrdinalIgnoreCase);
 
            return Order == SortOrder.Ascending ? result : -result;
        }
    }
}