FormHelper.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using System.Runtime.InteropServices;
using System.Text;
using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;
using System.Windows.Forms;
using static GenerallyPositive.Enums;
using static GenerallyPositive.GPALForm.GPALForm;
using HWND = System.IntPtr;
 
namespace GenerallyPositive.GPALForm
{
    internal class FormHelper
    {
        public static void FillInFrom(GPALControl controlEntry, string useText, WriteMode writeMode)
        {
            Control control = controlEntry.WindowsControl as Control;
 
            if (null == control)
                GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                    $"Control [{controlEntry.Name}] is not on a form yet, so nothing was written to it",
                    null, GPALObjectType.GPALForm);
            else if (FormControlType.Input != controlEntry.ControlType
                  && FormControlType.TextArea != controlEntry.ControlType)
                GPAL.PublishSimpleEvent(GPALEventType.WARNING,
                    $"A [{controlEntry.ControlType}] does not take text, so nothing was written to [{controlEntry.Name}]",
                    null, GPALObjectType.GPALForm);
            else
                GPALControl.OnUi(control, () => control.Text = TextFor(control, useText, writeMode));
        }

        private static string TextFor(Control control, string useText, WriteMode writeMode)
        {
            string current = control.Text ?? string.Empty;
            string retVal = useText;
 
            if (WriteMode.Append == writeMode)
                retVal = current + useText;
            else if (WriteMode.Insert == writeMode)
            {
                // a text box knows where the caret is, anything else has no caret to speak of and takes it at the end
                int at = control is TextBoxBase box ? box.SelectionStart : current.Length;
 
                retVal = current.Insert(Math.Min(Math.Max(at, 0), current.Length), useText);
            }
 
            return retVal;
        }
        public static void FillInWithTokens(GPALForm myForm, List<IGPALGrid<string>> tokenList, WriteMode writeMode)
        {
            foreach (IGPALGrid<string> tokens in tokenList)
            {
                // iterate over every row of tokens, filling in the form's editable controls a row at a time
                for (int tokenIdx = 0; tokenIdx < tokens.Count(); tokenIdx++)
                {
                    int elementIdx = 0;
                    List<string> currentRow = tokens[tokenIdx];
 
                    foreach (string token in currentRow)                                            // iterate over tokens, filling in the corresponding input/textarea webelement
                    {
                        bool textFilled = false;
 
                        while (false == textFilled && elementIdx < myForm.ControlList.Count)
                        {
                            switch (myForm.ControlList[elementIdx].ControlType)
                            {
                                case FormControlType.TextArea:
                                case FormControlType.Input:
                                    myForm.Form.SwitchToTab(myForm.ControlList[elementIdx]);    // bring the control's tab into view so the change is visible as it happens
                                    FillInFrom(myForm.ControlList[elementIdx], token, writeMode);
                                    textFilled = true;
                                    break;
 
                                default:
                                    break;
                            }
                            elementIdx++;
                        }
 
                        // detect if we have too many tokens to consume and publish an information event [entirely possible this scenario is fine]
                        if (elementIdx == myForm.ControlList.Count && false == textFilled)
                            GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Unused token: [{token}]", myForm, GPALObjectType.GPALForm);
                    }
 
                    // detect if we do not have enough tokens for all the form fields [entirely possible this scenario is fine]
                    while (elementIdx < myForm.ControlList.Count)
                    {
                        switch (myForm.ControlList[elementIdx].ControlType)
                        {
                            case FormControlType.TextArea:
                            case FormControlType.Input:
                                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No token for control: [{myForm.ControlList[elementIdx].Name}]", myForm, GPALObjectType.GPALForm);
                                break;
 
                            default:
                                break;
                        }
                        elementIdx++;
                    }
 
                    // CAVEAT: Handled/NotHandled are both ignored here, the handler can request to exit by returning CallIfStatus.Terminate
                    if (null != myForm.Form.CallAfterFillIn)
                    {
                        CallIfStatus handled = myForm.Form.CallAfterFillIn(myForm, tokens, tokenIdx);
 
                        if (CallIfStatus.Terminate == handled)
                        {
                            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"CallAfterFillIn handler [{myForm.Form.CallAfterFillIn.GetInvocationList()[0].Method.Name}] requested program termination.", myForm, GPALObjectType.GPALForm);
                            throw new GPALException($"{GPAL.MyMethodName()}: CallAfterFillIn handler [{myForm.Form.CallAfterFillIn.GetInvocationList()[0].Method.Name}] requested program termination.");
                        }
                    }
                }
            }
        }
        public static HWND WaitForWindow(string windowTitle, int waitTimeInSeconds = 10)
        {
            return WaitForWindowGeneric(windowTitle, false, waitTimeInSeconds);
        }
 
        public static HWND WaitForWindowRegex(string windowTitleRegex, int waitTimeInSeconds)
        {
            return WaitForWindowGeneric(windowTitleRegex, true, waitTimeInSeconds);
        }
 
        public static HWND WaitForWindowGeneric(string waitForTitle, bool useRegex, int waitTimeInSeconds)
        {
            bool found = false;
            HWND retHWND = IntPtr.Zero;
 
            for (int cnt = 0; cnt < waitTimeInSeconds && false == found; cnt++)
            {
                Thread.Sleep(1000); // best to sleep first and give a second more for the window to appear
                IDictionary<HWND, string> windows = GetOpenWindows();
                foreach (var entry in windows)
                {
                    if (true == useRegex)
                    {
                        MatchCollection mc = Regex.Matches(entry.Value, waitForTitle);
                        if (0 < mc.Count)
                        {
                            found = true;
                            retHWND = entry.Key;
                            break;
                        }
                    }
                    else
                    {
                        if (true == waitForTitle.Equals(entry.Value))
                        {
                            found = true;
                            retHWND = entry.Key;
                            break;
                        }
                    }
                }
            }
            return retHWND;
        }

        public static HWND WaitForCommonDialog(int processId, int waitTimeInSeconds = 10)
        {
            HWND retHWND = IntPtr.Zero;
            Stopwatch waited = Stopwatch.StartNew();
 
            // what was already on screen before the waiting started. A dialog that was there before anything
            // was asked for is not the answer to what was asked for: a reminder, a prompt from another program,
            // whatever the user left open. #32770 is the class of every one of them, so the class alone cannot
            // tell them apart and the moment it appeared is what does
            var before = new HashSet<HWND>(CommonDialogsOf(0));
 
            while (IntPtr.Zero == retHWND && waited.ElapsedMilliseconds < waitTimeInSeconds * 1000)
            {
                List<HWND> appeared = new List<HWND>();
 
                // a dialog qualifies two ways: it turned up while we were waiting, or it was already there and
                // is shaped like a file dialog. The second is what catches one that opened between the click
                // and the first look, which is every download after the first once the browser is warm
                foreach (HWND window in CommonDialogsOf(0))
                    if (false == before.Contains(window) || true == LooksLikeAFileDialog(window))
                        appeared.Add(window);
 
                // among the new ones, the one belonging to the process that was asked about
                foreach (HWND window in appeared)
                {
                    GetWindowThreadProcessId(window, out int owner);
 
                    if (IntPtr.Zero == retHWND && owner == processId)
                        retHWND = window;
                }
 
                // and failing that, whichever new one turned up. The owning process is a preference because a
                // browser launched through a driver, or one that relaunched itself, owns its windows from a
                // process nobody here was ever handed
                if (IntPtr.Zero == retHWND && 0 < appeared.Count)
                {
                    GetWindowThreadProcessId(appeared[0], out int owner);
 
                    GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"A common dialog appeared belonging to process [{owner}] rather than [{processId}], and is taken as the one that was waited for.", null, GPALObjectType.None);
 
                    retHWND = appeared[0];
                }
 
                if (IntPtr.Zero == retHWND)
                    Thread.Sleep(250);
            }
 
            if (IntPtr.Zero == retHWND)
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"No common dialog for process [{processId}] in [{waitTimeInSeconds}]s. {VisibleWindows()}", null, GPALObjectType.None);
 
            return retHWND;
        }

        public static string TitleOf(HWND window)
        {
            var title = new StringBuilder(256);
 
            GetWindowText(window, title, title.Capacity);
 
            return title.ToString();
        }

        public static string VisibleWindows()
        {
            var seen = new List<string>();
 
            EnumWindows(delegate (HWND hWnd, int lParam)
            {
                if (true == IsWindowVisible(hWnd))
                {
                    var className = new StringBuilder(256);
                    var title = new StringBuilder(256);
 
                    GetClassName(hWnd, className, className.Capacity);
                    GetWindowText(hWnd, title, title.Capacity);
                    GetWindowThreadProcessId(hWnd, out int owner);
 
                    if (0 < className.Length)
                        seen.Add($"[{className}] '{title}' (process {owner})");
                }
 
                return true;
 
            }, 0);
 
            return 0 == seen.Count ? "No visible windows were found at all." : $"What is on screen: {string.Join(" | ", seen)}";
        }

        public static List<HWND> CommonDialogsOf(int processId)
        {
            var found = new List<HWND>();
 
            EnumWindows(delegate (HWND hWnd, int lParam)
            {
                if (true == IsWindowVisible(hWnd))
                {
                    var className = new StringBuilder(64);
 
                    GetClassName(hWnd, className, className.Capacity);
 
                    if (COMMON_DIALOG_CLASS == className.ToString())
                    {
                        GetWindowThreadProcessId(hWnd, out int owner);
 
                        if (0 == processId || owner == processId)
                            found.Add(hWnd);
                    }
                }
 
                return true;
 
            }, 0);
 
            return found;
        }

        public static bool LooksLikeAFileDialog(HWND dialog)
        {
            bool accept = false;
            bool typing = false;
 
            EnumChildWindows(dialog, delegate (HWND child, int lParam)
            {
                if (ACCEPT_CONTROL_ID == GetDlgCtrlID(child))
                    accept = true;
 
                var className = new StringBuilder(64);
 
                GetClassName(child, className, className.Capacity);
 
                string name = className.ToString();
 
                if ("Edit" == name || true == name.StartsWith("ComboBox"))
                    typing = true;
 
                return true;
 
            }, 0);
 
            return true == accept && true == typing;
        }
 
        // the class every Open, Save As and folder picker has carried since Windows 3
        private const string COMMON_DIALOG_CLASS = "#32770";
 
        // IDOK, the accept button on any dialog that has one
        private const int ACCEPT_CONTROL_ID = 1;
 
        [DllImport("USER32.DLL")]
        private static extern bool EnumChildWindows(HWND parent, EnumWindowsProc enumFunc, int lParam);
 
        [DllImport("USER32.DLL")]
        private static extern int GetDlgCtrlID(HWND hWnd);
 
        [DllImport("USER32.DLL")]
        private static extern int GetClassName(HWND hWnd, StringBuilder lpClassName, int nMaxCount);
 
        [DllImport("USER32.DLL")]
        private static extern int GetWindowThreadProcessId(HWND hWnd, out int processId);
 
        // https://stackoverflow.com/questions/7268302/get-the-titles-of-all-open-windows
        public static IDictionary<HWND, string> GetOpenWindows()
        {
            HWND shellWindow = GetShellWindow();
            Dictionary<HWND, string> windows = new Dictionary<HWND, string>();
 
            EnumWindows(delegate (HWND hWnd, int lParam)
            {
                if (hWnd == shellWindow) return true;
                if (!IsWindowVisible(hWnd)) return true;
 
                int length = GetWindowTextLength(hWnd);
                if (length == 0) return true;
 
                StringBuilder builder = new StringBuilder(length);
                GetWindowText(hWnd, builder, length + 1);
 
                windows[hWnd] = builder.ToString();
                return true;
 
            }, 0);
 
            return windows;
        }
 
        private delegate bool EnumWindowsProc(HWND hWnd, int lParam);
 
        [DllImport("USER32.DLL")]
        private static extern bool EnumWindows(EnumWindowsProc enumFunc, int lParam);
 
        [DllImport("USER32.DLL")]
        private static extern int GetWindowText(HWND hWnd, StringBuilder lpString, int nMaxCount);
 
        [DllImport("USER32.DLL")]
        private static extern int GetWindowTextLength(HWND hWnd);
 
        [DllImport("USER32.DLL")]
        private static extern bool IsWindowVisible(HWND hWnd);
 
        [DllImport("USER32.DLL")]
        private static extern IntPtr GetShellWindow();
    }
}