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 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),
                GPALListView lv => AddListView(lv),
                GPALMenuBar mb => AddMenuBar(mb),
                GPALNumericUpDown nud => AddNumericUpDown(nud),
                GPALProgressBar pb => AddProgressBar(pb),
                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 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;
            }
        }
        private void SizeForm()
        {
            int tmpHeight = 30;
 
            if (0 == FormSettings.height)
            {
                foreach (GPALControl controlEntry in FormSettings.myForm.ControlList)
                {
                    switch (controlEntry.ControlType)
                    {
                        case FormControlType.TextArea:
                        case FormControlType.RichTextBox:
                            tmpHeight += 54;
                            break;
 
                        default:
                            tmpHeight += 30;
                            break;
                    }
                }
                FormSettings.height = tmpHeight;
 
                if (0 < FormSettings.width)
                    FormSettings.myForm.Width = FormSettings.width;
                if (0 < FormSettings.height)
                    FormSettings.myForm.Height = FormSettings.height;
            }
 
            // 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;
            }
        }
        #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,
                Anchor = AnchorStyles.Top | AnchorStyles.Left | AnchorStyles.Right | AnchorStyles.Bottom,
                Enabled = gPALButton.Enabled,
                Height = 10 < gPALButton.Height ? gPALButton.Height : 20,
            };
           
            gPALButton.WindowsControl = 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);
            FormSettings.TableLayoutPanel.Controls.Add((Chart)gPALChart.WindowsControl);
            ((Chart)gPALChart.WindowsControl).Height = 10 < gPALChart.Height ? gPALChart.Height : 150;
 
            Chart chart = gPALChart.WindowsControl;
 
            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;
 
            // 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
            {
                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;
 
            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;
 
            // 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
 
            FormSettings.TableLayoutPanel.Controls.Add(dgv);
 
            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;
 
            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,
                Text = "(click Browse to select)",
                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;
 
            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
            };
 
            Button dotButton = new Button
            {
                Name    = gPALFileSelector.Name + "_Browse",
                Text    = "...",
                Width   = 28,
                Anchor  = AnchorStyles.Top | AnchorStyles.Right,
                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)
                // 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;
 
            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;
 
            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;
        }
        private void FitLabelHeight(Label label)
        {
            if (0 < 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 AddLabel(GPALLabel gPALLabel)
        {
            FormSettings.myForm.ControlList.Add(gPALLabel);
            Label label = new Label
            {
                Name = gPALLabel.Name,
                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;
 
            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
            }
 
            // 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;
            };
 
            gPALListView.WindowsControl = listView;
 
            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;
            }
 
            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;
 
            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 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;
 
            foreach (var (evt, handler) in gPALProgressBar.Callbacks)
            {
                if (handler == null) continue; // skip invalid
 
                switch (evt)
                {
                    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;
            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;
                }
                foreach (var (evt, handler) in item.Callbacks)
                    if (handler is EventHandler clickHandler)
                        menuItem.Click += clickHandler;
                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;
 
                foreach (var (evt, handler) in item.Callbacks)
                    if (handler is EventHandler clickHandler)
                        button.Click += clickHandler;
                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
            {
                // a vertical bar gives left and right panes, a horizontal one top and bottom
                Orientation = true == gPALSplitter.IsHorizontalSplit ? Orientation.Vertical : Orientation.Horizontal,
                // full width, and only as tall as its contents need. Docking it to fill would leave it with
                // whatever height its row happened to give it and then it clips what is inside. The height is
                // measured once the panes are filled, below, unless .WithHeight already said what it should be
                Dock = DockStyle.Top,
                Height = 10 < gPALSplitter.Height ? gPALSplitter.Height : 0,
                AutoScaleMode = AutoScaleMode.Inherit
            };
 
            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;
 
            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.Top + 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;
        }

        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 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.WARNING, $"[{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.WARNING, $"[{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
                // todo : more settings
            };
 
            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;
            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;
            GPALRichTextBox.RenderMarkdown(richTextBox, gPALRichTextBox.Text);
 
            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;
 
            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;
        }
    }
}