Application.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.
// =============================================================================
 
//extern alias mUIA;
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using System.Windows.Automation;
using GenerallyPositive.Browser;
using GenerallyPositive.GPALForm;
using static GenerallyPositive.Enums;
// an Application has a HiddenDesktop property now, which hides the static class of the same name, so the
// class is reached through an alias. The browser side does this for the same reason
using Desktops = GenerallyPositive.Browser.HiddenDesktop;
 
namespace GenerallyPositive.Application
{
    public class Application
        : IApplication
    {
        public delegate CallIfStatus CallIfDelegate(Application application, List<IGPALAutomationElement> foundElements, List<IGPALAutomationElement> matchedElements, Selector selector, bool matchedAll);
        public delegate CallIfStatus CallAfterFillInDelegate(Application application, IGPALGrid<string> tokens, int tokenIdx);
 
        #region <Working Variables>
        internal ApplicationSettings applicationSettings { get; set; }
        private dynamic persistenceList;
        internal UnitOfWork CurrentUOW { get; set; }  = null;
        private UnitOfWork persistentUOW = null;
        #endregion <Working Variables>
        public Application ToGPALObject()
        {
            return this;
        }

        internal Application()
        {
            CurrentUOW = new UnitOfWork();
            persistentUOW = new UnitOfWork();
            persistenceList = new List<UnitOfWork>
            {
                persistentUOW
            };
            applicationSettings = new ApplicationSettings(this);
        }
        #region <Private>
        private bool CheckWaitFor()
        {
            bool matchFound = true;
            List<GPALAutomationElement> foundElements = null;
 
            // an earlier action on this same unit of work already waited these selectors in successfully, so
            // waiting again is redundant - nothing can have moved under us, since any selector added after an
            // action starts a fresh unit of work. the action still resolves its own elements either way.
            if (null != CurrentUOW.WaitForSatisfied)
            {
                GPAL.PublishSimpleEvent(GPALEventType.DEBUG, $"Selectors for this unit of work already found at [{CurrentUOW.WaitForSatisfied:HH:mm:ss.fff}], skipping redundant wait.", this, GPALObjectType.Application);
                return true;
            }
 
            if (WaitTime.Never < CurrentUOW.WaitForInMs)
            {
                // we are waiting on selector(s)
                foundElements = ElementHelper.WaitFor(this, CurrentUOW.WaitForInMs, out matchFound);
 
                if (0 < foundElements?.Count)
                    CurrentUOW.WaitForSatisfied = DateTime.Now;
            }
 
            return matchFound;
        }
        private bool InAction(bool checkWaitFor)
        {
            ApplicationHelper.TopProcess(this.Process); // ensure the browser window is on top, can use selenium or hardware (mouse click) topping. firefox will only top with hardware
 
            CurrentUOW.ActionCalled = true;
 
            SelectorListMaintenanceSweep(CurrentUOW); // purge any nodes marked 'deleteme' before iterating list
            SelectorListMaintenanceSweep(persistentUOW); // purge any nodes marked 'deleteme' before iterating list
            CheckPersistentSelectors(); // check if there are persistent selectors to deal with
 
            // TODO: CAVEAT: WaitFor will call the CallIf handlers, which might result in unexpected behavior?
            if (true == checkWaitFor)
                CheckWaitFor();
 
            // always attempt the gated action, same as the browser side. WaitFor only holds the workflow until
            // something turns up, it is not a match test - and the action does its own element lookup anyway,
            // so a genuinely missing element surfaces there where it gets logged and can be debugged, rather
            // than the action being silently skipped here.
            return true;
        }
        private static void SelectorListMaintenanceSweep(dynamic CurrentUOW)
        {
            for (int idx = 0; idx < CurrentUOW.WithSelectorList.Count; idx++)
                if (true == CurrentUOW.WithSelectorList[idx].DeleteMe)
                    CurrentUOW.WithSelectorList.RemoveAt(idx);
 
            for (int idx = 0; idx < CurrentUOW.InSelectorList.Count; idx++)
                if (true == CurrentUOW.InSelectorList[idx].DeleteMe)
                    CurrentUOW.InSelectorList.RemoveAt(idx);
        }
        private void CheckPersistentSelectors()
        {
            // all we have to do is walk the list, try to find the element and the callif callbacks will do the work
            if (0 < (persistentUOW.WithSelectorList?.Count ?? 0))
                foreach (Selector selector in persistentUOW.WithSelectorList)
                    ElementHelper.FindElements(this, persistentUOW, selector, out bool matchedAll, out List<GPALAutomationElement> elems);
        }
        #endregion <Private>
        #region <Application Actions>
        public IAllowAllApplicationAndAllSelector Maximize
        {
            get
            {
                if (null != Process)
                    ApplicationHelper.ShowWindow(Process.MainWindowHandle, 3);    // 1= SW_NORMAL - show normal, 3 = max, 2 = min
                return this;
            }
        }

        public IAllowAllApplicationAndAllSelector Minimize
        {
            get
            {
                ApplicationHelper.ShowWindow(Process.MainWindowHandle, 2);    // 1= SW_NORMAL - show normal, 3 = max, 2 = min
                return this;
            }
        }

        public IAllowAllApplicationAndAllSelector Restore
        {
            get
            {
                ApplicationHelper.ShowWindow(Process.MainWindowHandle, 1);    // 1= SW_NORMAL - show normal, 3 = max, 2 = min
                return this;
            }
        }

        public IAllowAllApplicationAndAllSelector ResizeWindow(int width, int height)
        {
            if (true == InAction(true))
                ApplicationHelper.ResizeWindow(ApplicationSettings.LastWindowHandle, width, height);
            return this;
        }

        public IAllowAllApplicationAndAllSelector MoveWindow(int x, int y)
        {
            if (true == InAction(true))
                ApplicationHelper.MoveWindow(ApplicationSettings.LastWindowHandle, x, y);
            return this;
        }

        public IAllowSelectorActionOrAnySelector AppendFrom(GPALDatabase inputDatabase)
        {
            DatabaseHelper.TokenizeDatabase(CurrentUOW, inputDatabase);
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, inputDatabase.Tokens, WriteMode.Append);
            return this;
        }

        public IAllowSelectorActionOrAnySelector AppendFrom(GPALFile inputFile)
        {
            ((IGPALFileInternal)inputFile).TokenList = FileHelper.TokenizeFile(CurrentUOW, inputFile);
            
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, ((IGPALFileInternal)inputFile).TokenList, WriteMode.Append);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector AppendFrom(IGPALGrid<string> inputGrid)
        {
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, inputGrid, WriteMode.Append);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector AppendFrom(string textToUse)
        {
            if (true == InAction(true))
                ElementHelper.FillInFrom(this, textToUse, WriteMode.Append);
            return this;
        }

        public IAllowAllExceptParameters Open([Directory()] string applicationPath)
        {
            IntPtr processHandle = IntPtr.Zero;
            Process[] processes;
            StringBuilder parameters = new StringBuilder();
            bool first = true;
 
            foreach (string parameter in applicationSettings.Parameters)
            {
                if (false == first)
                    parameters.Append(" ");
                else
                    first = false;
                parameters.Append(parameter);
            }
 
            if (null != Process)
            {
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "Unable to Open/control more than one program. Please use another Application.", this, GPALObjectType.Application);
                return this;
            }
 
            ApplicationPath = applicationPath;
 
            // a hidden desktop has none of this program's windows on it, so attaching to a copy already
            // running would attach to one on the desktop the user is working on, which is the one thing the
            // whole feature is for avoiding
            if (true == applicationSettings.HiddenDesktop)
            {
                applicationSettings.NewInstance = true;
 
                if (false == Desktops.Ensure(applicationSettings.HiddenDesktopName))
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Windows would not make the desktop [{applicationSettings.HiddenDesktopName}], so [{applicationPath}] runs on the one you are looking at.", this, GPALObjectType.Application);
 
                    applicationSettings.HiddenDesktop = false;
                }
                else if (false == applicationSettings.HiddenDesktopReported)
                {
                    applicationSettings.HiddenDesktopReported = true;
 
                    GPAL.PublishSimpleEvent(GPALEventType.INFO, $"[{applicationPath}] runs on [{applicationSettings.HiddenDesktopName}], where UIAutomation drives it and hardware input cannot reach it. Peek at the desktop to watch it or to use hardware there.", this, GPALObjectType.Application);
                }
            }
 
            // CAVEAT: see if process is open and attach to it? not sure this is what we want
            // maybe we should just launch a new instance?
            try
            {
                processes = Process.GetProcessesByName(Path.GetFileNameWithoutExtension(applicationPath));
                bool attached = false;
 
                // WithNewInstance says launch regardless, for a program that is always running and whose
                // existing window is not the one the workflow asked for
                if (false == applicationSettings.NewInstance && null != processes && 0 < processes.Length)
                {
                    // An already-running instance should have a window quickly; probe each briefly and
                    // skip windowless/background matches rather than blocking for the full timeout.
                    foreach (Process process in processes)
                    {
                        applicationSettings.Process = process;
                        AutomationElement existingRoot = WaitForRootAutomationElement(process, 2000);
                        if (null != existingRoot)
                        {
                            applicationSettings.RootAutomationElement = existingRoot;
                            processHandle = process.MainWindowHandle;
                            attached = true;
                            break;
                        }
                    }
                }
 
                if (false == attached)
                {
                    applicationSettings.Process = true == applicationSettings.HiddenDesktop
                        ? StartOnHiddenDesktop(applicationPath, parameters.ToString())
                        : Process.Start(applicationPath, parameters.ToString());
 
                    // Do not guess with a fixed sleep: poll until the main window exists and its root
                    // automation element is actually retrievable, up to WaitForWindowTimeout seconds.
                    AutomationElement root = WaitForRootAutomationElement(applicationSettings.Process,
                        Math.Max(1, applicationSettings.WaitForWindowTimeout) * 1000);
 
                    if (null != root)
                    {
                        applicationSettings.RootAutomationElement = root;
                        processHandle = applicationSettings.Process.MainWindowHandle;
                    }
                    // a launcher hands its work to something already running and exits, so it never has a window
                    // of its own to take. explorer.exe passes the folder to the shell and quits, and the window
                    // that opens belongs to the shell. Nothing is wrong, but the window has to be found by name
                    else if (true == applicationSettings.Process?.HasExited)
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"[{applicationPath}] exited as soon as it started, which is what a launcher does. Use WaitForWindow or WaitForWindowRegex to settle on the window it opened.", this, GPALObjectType.Application);
                    else
                    {
                        string msg = $"Timed out after [{applicationSettings.WaitForWindowTimeout}]s waiting for the main window / root automation element of [{applicationPath}]{(true == applicationSettings.HiddenDesktop ? $" on [{applicationSettings.HiddenDesktopName}]" : string.Empty)}.";
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, msg, this, GPALObjectType.Application);
                        throw new GPALException(msg);
                    }
                }
            }
            catch (Exception ex)
            {
                GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Unable to launch [{applicationPath}].", this, GPALObjectType.Application, ex);
                return this;
            }
 
            if (null == applicationSettings.Process)
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Unable to launch [{applicationPath}].", this, GPALObjectType.Application);
            else
            {
                // a launcher that has already exited has no window to bring forward, and asking about one is an
                // exception rather than an answer. A program on a hidden desktop is not brought forward at all,
                // since bringing a window forward is the taking of focus the desktop exists to avoid
                if (false == applicationSettings.Process.HasExited && false == applicationSettings.HiddenDesktop)
                    ApplicationHelper.TopProcess(applicationSettings.Process);
 
                if (true == applicationSettings.HiddenDesktop && false == applicationSettings.HiddenDesktopChecked)
                {
                    applicationSettings.HiddenDesktopChecked = true;
 
                    if (false == Desktops.HasWindows(applicationSettings.HiddenDesktopName, 10_000))
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Nothing arrived on [{applicationSettings.HiddenDesktopName}], so this program is on the desktop you are working on.", this, GPALObjectType.Application);
                }
 
                CurrentUOW.ActionCalled = true;
            }
 
            return this;
        }

        private AutomationElement WaitForRootAutomationElement(Process process, int timeoutMs)
        {
            if (null == process)
                return null;
 
            Stopwatch stopwatch = Stopwatch.StartNew();
 
            // Let a GUI app pump its message loop and create its window. This throws immediately for a
            // process with no message loop (e.g. a console app), so it never wastes the timeout on those.
            try { process.WaitForInputIdle(timeoutMs); } catch { /* no message loop; fall through to polling */ }
 
            while (stopwatch.ElapsedMilliseconds < timeoutMs)
            {
                try
                {
                    process.Refresh();
 
                    // a program on a hidden desktop has no window as far as this desktop is concerned, because
                    // MainWindowHandle enumerates the desktop asking rather than the one the window is on
                    IntPtr handle = true == applicationSettings.HiddenDesktop
                                  ? Desktops.MainWindowOf(applicationSettings.HiddenDesktopName, process.Id)
                                  : process.MainWindowHandle;
                    if (IntPtr.Zero != handle)
                    {
                        AutomationElement root = AutomationElement.FromHandle(handle);
                        if (null != root)
                            return root;
                    }
                }
                catch
                {
                    // Window/handle not ready yet (or transiently invalid); keep polling until timeout.
                }
 
                Thread.Sleep(100);
            }
 
            return null;
        }
        public void Close()
        {
            // Process.Close releases our handle to the program. It does not close the program, which is what
            // this is called for and what it never did. CloseMainWindow asks the window to close the way a
            // person clicking the X asks, so the application runs whatever it does on the way out. A program
            // that will not go, because it is asking whether to save or has nothing to ask, is ended instead
            if (null != Process && false == HasGone(Process))
            {
                // CloseMainWindow looks for the window on this desktop and finds nothing when the program is on
                // a hidden one, so the window there is asked directly and the program still closes itself
                if (true == ApplicationSettings.HiddenDesktop)
                    Desktops.CloseWindowsOf(ApplicationSettings.HiddenDesktopName, Process.Id);
                else
                    Process.CloseMainWindow();
 
                if (false == Process.WaitForExit(CLOSING_MS))
                {
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"[{ApplicationPath}] did not close within [{CLOSING_MS / 1000}]s of being asked, so it is being ended.", this, GPALObjectType.Application);
 
                    Process.Kill();
                }
            }
 
            Process?.Close();
            Process = null;
        }
 
        // how long a program is given to close itself before it is ended
        private const int CLOSING_MS = 5000;

        private Process StartOnHiddenDesktop(string applicationPath, string parameters)
        {
            Native.STARTUPINFO startup = new Native.STARTUPINFO
            {
                cb = (uint)System.Runtime.InteropServices.Marshal.SizeOf<Native.STARTUPINFO>(),
                lpDesktop = Desktops.StartupNameFor(applicationSettings.HiddenDesktopName)
            };
 
            string quoted = "\"" + applicationPath + "\"";
            string commandLine = true == string.IsNullOrWhiteSpace(parameters) ? quoted : quoted + " " + parameters;
 
            if (false == Native.CreateProcess(null, commandLine, IntPtr.Zero, IntPtr.Zero, false, 0, IntPtr.Zero,
                                              Path.GetDirectoryName(applicationPath), ref startup, out Native.PROCESS_INFORMATION started))
                throw new System.ComponentModel.Win32Exception(System.Runtime.InteropServices.Marshal.GetLastWin32Error(), $"Could not start [{applicationPath}] on [{applicationSettings.HiddenDesktopName}]");
 
            Process retVal = Process.GetProcessById((int)started.dwProcessId);
 
            Native.CloseHandle(started.hProcess);
            Native.CloseHandle(started.hThread);
 
            return retVal;
        }
 
        private static bool HasGone(Process process)
        {
            bool retVal = true;
 
            try
            {
                retVal = process.HasExited;
            }
            catch (InvalidOperationException)
            {
                // no program was ever attached to this, so there is nothing to close
            }
 
            return retVal;
        }
        public IAllowSelectorActionOrAnySelector FillInFrom(GPALDatabase inputDatabase)
        {
            DatabaseHelper.TokenizeDatabase(CurrentUOW, inputDatabase);
 
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, CurrentUOW.InputDatabase.Tokens, WriteMode.Overwrite);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector FillInFrom(GPALFile inputFile)
        {
            ((IGPALFileInternal)inputFile).TokenList = FileHelper.TokenizeFile(CurrentUOW, inputFile);
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, ((IGPALFileInternal)CurrentUOW.InputFile).TokenList, WriteMode.Overwrite);
            return this;
        }

        public IAllowSelectorActionOrAnySelector FillInFrom(IGPALGrid<string> inputGrid)
        {
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, (IGPALGrid<string>)inputGrid, WriteMode.Overwrite);
            return this;
        }

        public IAllowSelectorActionOrAnySelector FillInFrom(string textToUse)
        {
            if (true == InAction(true))
                ElementHelper.FillInFrom(this, textToUse, WriteMode.Overwrite);
            return this;
        }

        public IAllowSelectorActionOrAnySelector Focus(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.Focus(this);
            return this;
        }

        public IAllowSelectorActionOrAnySelector Hover(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.Hover(this, CurrentUOW);
            return this;
        }

        public IAllowSelectorActionOrAnySelector InsertFrom(string textToUse)
        {
            if (true == InAction(true))
                ElementHelper.FillInFrom(this, textToUse, WriteMode.Insert);
            return this;
        }

        public IAllowSelectorActionOrAnySelector InsertFrom(GPALDatabase inputDatabase)
        {
            DatabaseHelper.TokenizeDatabase(CurrentUOW, inputDatabase);
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, CurrentUOW.InputDatabase.Tokens, WriteMode.Insert);
            return this;
        }

        public IAllowSelectorActionOrAnySelector InsertFrom(IGPALGrid<string> inputGrid)
        {
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, (IGPALGrid<string>)inputGrid, WriteMode.Insert);
            return this;
        }

        public IAllowSelectorActionOrAnySelector InsertFrom(GPALFile inputFile)
        {
            ((IGPALFileInternal)inputFile).TokenList = FileHelper.TokenizeFile(CurrentUOW, inputFile);
            if (true == InAction(true))
                ApplicationHelper.FillInWithTokens(this, ((IGPALFileInternal)CurrentUOW.InputFile).TokenList, WriteMode.Insert);
            return this;
        }

        public IAllowSelectorActionOrAnySelector LeftClick(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.LeftClick(this);
            return this;
        }

        public IAllowSelectorActionOrAnySelector LeftClick(Enums.ModifierKeys modifierKeys)
        {
            if (true == InAction(true))
                ElementHelper.LeftClick(this, modifierKeys);
            return this;
        }

        public IAllowSelectorActionOrAnySelector LeftDoubleClick(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.GenericClick(this, ClickType.LeftDoubleClick);
            return this;
        }

        public IAllowSelectorActionOrAnySelector MiddleClick(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.GenericClick(this, ClickType.MiddleClick);
            return this;
        }

        public IAllowSelectorActionOrAnySelector MoveTo(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.MoveTo(this);
            return this;
        }

        public IAllowSelectorActionOrAnySelector LeftClickAndOpen(GPALFile file)
        {
            return ClickAndAnswer(file);
        }

        public IAllowSelectorActionOrAnySelector LeftClickAndSave(GPALFile file)
        {
            ClearTheWay(file);
 
            return ClickAndAnswer(file);
        }

        private void ClearTheWay(GPALFile file)
        {
            foreach (string name in file?.Filenames ?? new List<string>())
                if (true == System.IO.File.Exists(name))
                {
                    GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Deleting [{name}] before saving over it, so the dialog has nothing to ask about", this, GPALObjectType.Application);
 
                    System.IO.File.Delete(name);
                }
        }

        private IAllowSelectorActionOrAnySelector ClickAndAnswer(GPALFile file)
        {
            if (true == InAction(true))
            {
                ElementHelper.LeftClick(this, ModifierKeys.NONE);
 
                FileDialogHelper.Answer(this, file, ApplicationSettings.WaitForWindowTimeout);
            }
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector AnswerFileDialog(GPALFile file)
        {
            if (true == InAction(true))
                FileDialogHelper.Answer(this, file, ApplicationSettings.WaitForWindowTimeout);
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector DragAndDrop(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.DragAndDrop(this);
            return this;
        }

        public IAllowSelectorActionOrAnySelector DragAndDrop(ModifierKeys modifierKeys)
        {
            if (true == InAction(true))
                ElementHelper.DragAndDrop(this, modifierKeys);
            return this;
        }

        public IAllowSelectorActionOrAnySelector PressModifierKey(ModifierKeys modifierKeys)
        {
            HardwareHelper.PressModifierKey(modifierKeys);
            return this;
        }

        public IAllowSelectorActionOrAnySelector ReleaseModifierKey(ModifierKeys modifierKeys)
        {
            HardwareHelper.ReleaseModifierKeys(modifierKeys);
            return this;
        }

        public IAllowSelectorActionOrAnySelector SendKey(byte VKCode)
        {
            if (true == InAction(true))
            {
                HardwareHelper.SendKey(VKCode);
 
                // the keystroke is sent, not taken. Whatever comes next waits for the application to have read
                // it, so a chain of sends arrives in the order it was written
                ElementHelper.SettleInput(this);
            }
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector SendString(string textToSend)
        {
            HardwareHelper.SendString(textToSend, GPAL.TypingDelay);
 
            ElementHelper.SettleInput(this);
 
            return this;
        }

        public IAllowAllActionAndAnySelector SwitchToTab(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.SwitchToTab(this);
            return this;
        }

        public IAllowAllActionAndAnySelector SetRange(double rangeValue)
        {
            if (true == InAction(true))
                ElementHelper.SetRange(this, rangeValue);
            return this;
        }

        public IAllowSelectorActionOrAnySelector RightClick(Selector selector = null)
        {
            if (null != selector) WithSelector(selector);
            if (true == InAction(true))
                ElementHelper.GenericClick(this, ClickType.RightClick);
            return this;
        }

        public IAllowAfterWaitForAndSizeControl WaitFor(int timeoutInTicks)
        {
            // we are done waiting on any selectors since we performed an action
            // so, we just wait/sleep
            if (true == CurrentUOW.ActionCalled)
                Thread.Sleep(timeoutInTicks);
            else
                CurrentUOW.WaitForInMs = timeoutInTicks;
 
            return this;
        }

        public IAllowAfterWaitForAndSizeControl WaitForWindow(string windowTitle)
        {
            if (true == InAction(true))
                SettleOnWindow(true == ApplicationSettings.HiddenDesktop
                    ? Desktops.WaitForWindowOn(ApplicationSettings.HiddenDesktopName, title => windowTitle.Equals(title), ApplicationSettings.WaitForWindowTimeout)
                    : FormHelper.WaitForWindow(windowTitle, ApplicationSettings.WaitForWindowTimeout));
            return this;
        }

        public IAllowAfterWaitForAndSizeControl WaitForWindowRegex(string windowTitleRegex)
        {
            if (true == InAction(true))
                SettleOnWindow(true == ApplicationSettings.HiddenDesktop
                    ? Desktops.WaitForWindowOn(ApplicationSettings.HiddenDesktopName, title => 0 < System.Text.RegularExpressions.Regex.Matches(title, windowTitleRegex).Count, ApplicationSettings.WaitForWindowTimeout)
                    : FormHelper.WaitForWindowRegex(windowTitleRegex, ApplicationSettings.WaitForWindowTimeout));
            return this;
        }

        private void SettleOnWindow(IntPtr windowHandle)
        {
            ApplicationSettings.LastWindowHandle = windowHandle;
 
            if (IntPtr.Zero != windowHandle)
            {
                AutomationElement window = AutomationElement.FromHandle(windowHandle);
 
                if (null != window)
                    ApplicationSettings.RootAutomationElement = window;
            }
        }
        public IAllowSelectorActionOrAnySelector ScrollHorizontalSmall(int iterations = 1)
        {
            if (true == InAction(true))
            {
                for (; 0 < iterations; iterations--)
                    ElementHelper.Scroll(this, ScrollAmount.SmallIncrement, ScrollTypes.Increments, ScrollTypes.Horizontal);
 
                for (; 0 > iterations; iterations++)
                    ElementHelper.Scroll(this, ScrollAmount.SmallDecrement, ScrollTypes.Increments, ScrollTypes.Horizontal);
            }
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollHorizontalLarge(int iterations = 1)
        {
            if (true == InAction(true))
            {
                for (; 0 < iterations; iterations--)
                    ElementHelper.Scroll(this, ScrollAmount.LargeIncrement, ScrollTypes.Increments, ScrollTypes.Horizontal);
 
                for (; 0 > iterations; iterations++)
                    ElementHelper.Scroll(this, ScrollAmount.LargeDecrement, ScrollTypes.Increments, ScrollTypes.Horizontal);
            }
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollHorizontalPercent(int percent)
        {
            if (true == InAction(true))
                ElementHelper.Scroll(this, InRange(percent), ScrollTypes.Percent, ScrollTypes.Horizontal);
 
            return this;
        }

        private int InRange(int percent)
        {
            int retVal = 0 > percent ? 0 : (100 < percent ? 100 : percent);
 
            if (retVal != percent)
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"A scroll percentage is 0 to 100, so [{percent}] was taken as [{retVal}]", this, GPALObjectType.Application);
 
            return retVal;
        }
        public IAllowSelectorActionOrAnySelector ScrollVerticalSmall(int iterations = 1)
        {
            if (true == InAction(true))
            {
                for (; 0 < iterations; iterations--)    // + = down
                    ElementHelper.Scroll(this, ScrollAmount.SmallIncrement, ScrollTypes.Increments, ScrollTypes.Vertical);
 
                for (; 0 > iterations; iterations++)    // - = up
                    ElementHelper.Scroll(this, ScrollAmount.SmallDecrement, ScrollTypes.Increments, ScrollTypes.Vertical);
            }
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollVerticalLarge(int iterations = 1)
        {
            if (true == InAction(true))
            {
                for (; 0 < iterations; iterations--)
                    ElementHelper.Scroll(this, ScrollAmount.LargeIncrement, ScrollTypes.Increments, ScrollTypes.Vertical);
 
                for (; 0 > iterations; iterations++)
                    ElementHelper.Scroll(this, ScrollAmount.LargeDecrement, ScrollTypes.Increments, ScrollTypes.Vertical);
            }
 
            return this;
        }

        public IAllowSelectorActionOrAnySelector ScrollVerticalPercent(int percent)
        {
            if (true == InAction(true))
                ElementHelper.Scroll(this, InRange(percent), ScrollTypes.Percent, ScrollTypes.Vertical);
 
            return this;
        }
        #endregion <Application Actions>
        #region <Helpers>
        public void RemoveCallIfHandlerEverywhere(Application.CallIfDelegate func)
        {
            CurrentUOW.AppCallIfFound.Remove(func);
            CurrentUOW.AppCallIfNotFound.Remove(func);
 
            // TODO: do the same for inselectorlist
            foreach (Selector selector in CurrentUOW.WithSelectorList)
            {
                selector.SelectorSettings.AppCallIfFound.Remove(func);
                selector.SelectorSettings.AppCallIfNotFound.Remove(func);
            }
 
            foreach (Selector selector in CurrentUOW.InSelectorList)
            {
                selector.SelectorSettings.AppCallIfFound.Remove(func);
                selector.SelectorSettings.AppCallIfNotFound.Remove(func);
            }
 
            persistentUOW.AppCallIfFound.Remove(func);
            persistentUOW.AppCallIfNotFound.Remove(func);
 
            foreach (Selector selector in persistentUOW.WithSelectorList)
            {
                selector.SelectorSettings.AppCallIfFound.Remove(func);
                selector.SelectorSettings.AppCallIfNotFound.Remove(func);
            }
        }
        #endregion <Helpers>
        #region <Application Settings>
        public IAllowApplicationSettingsOrOpen WithName(string appName)
        {
            Name = appName;
            return this;
        }

        public IAllowPersistentCallBack PersistentCallIfFound(CallIfDelegate persistentCallIfFound)
        {
            persistentUOW.AppCallIfFound.Add(persistentCallIfFound);
 
            return this;
        }

        public IAllowPersistentCallBack PersistentCallIfNotFound(CallIfDelegate persistentCallIfNotFound)
        {
            persistentUOW.AppCallIfNotFound.Add(persistentCallIfNotFound);
 
            return this;
        }

        public IAllowPersistence WithPersistentSelector(Selector selector)
        {
            // when would we ever add another persistent uow?
            // normal uow is once action is called, any withselector is on the next uow, but persistents don't act like this
            if (true == CurrentUOW.ActionCalled)
            {
                persistentUOW = new UnitOfWork();
                persistenceList.Add(persistentUOW);
            }
 
            selector.Application = this;
            //persistentUOW.SelectorType = SelectorType.WithSelector;
            persistentUOW.WithSelectorList.Add(selector);
            return this;
        }

        public IAllowSelectorActionOrAnySelector WithSelector(Selector selector)
        {
            selector.ElementsFoundAndMatchedCount = 0;  // in case it is reused
            selector.DeleteMe = false;                  // Remove() latches this on and nothing else clears it, so a reused selector would be swept on its next unit of work
            selector.RemovedMethods.Clear();            // a handler that took itself out of play in an earlier workflow is back in play for this one
 
            if (true == CurrentUOW.ActionCalled)
            {
                CurrentUOW = new UnitOfWork();
            }
 
            // clone so if this selector is reused, each UOW list will be unique and we won't change the selector by changing the browser it is associated with
            // NOTE: cloning disassociates with actual program selector, so we can't set any queryable properties on Selector like 'ElementsFoundAndMatchedCount'
            // ApplicationSettings.MySelector = new Selector(this, selector);    // MySelector temp hold for other browser syntax
            ApplicationSettings.MySelector = selector;
 
            CurrentUOW.WithSelectorList.Add(ApplicationSettings.MySelector);
 
            return this;
        }
        // TODO: How to deal with tokens. To consume a row for each row, but to also repeat the same token down the page?
        public IAllowAfterAnySelectorExceptWithAll WithAllThatMatch(int rowCount = int.MaxValue)
        {
            CurrentUOW.WithAllThatMatch = rowCount;
            return this;
        }
 
        #region <GetGrid / SaveTo / Pagination>
        // ─────────────────────────────────────────────────────────────────────────────────────
        // Data extraction out of a desktop application, mirroring the Browser GetGrid API.
        // A single selector that resolves to a UIA grid/table control is read structurally via
        // GridPattern/TablePattern; otherwise each selector is a column and repeating matches are
        // the rows (the WithAllThatMatch model). Missing cells use GPAL.ErrorPlaceholder. The
        // result lands in CurrentUOW.RetGrid so SaveTo*/pagination reuse the shared, engine-neutral
        // helpers (FileHelper.SaveToDelimited, GPAL.Converter) exactly as the Browser side does.
        // ─────────────────────────────────────────────────────────────────────────────────────
        public IAllowWithHeaderOrFileActions GetGrid(ref IGPALGrid<string> returnGrid)
        {
            // reading the grid is an action, the same as it is on the browser side, so the unit of work is
            // finished with and the next WithSelector starts a new one. GetGridCalled is a separate thing: it
            // tells WithHeader that the headers following it belong to this grid, and both it and SaveTo read
            // the grid off this same unit of work
            CurrentUOW.ActionCalled = true;
            CurrentUOW.GetGridCalled = true;
            CurrentUOW.RetGrid.Clear();
 
            if (!TryGetGridFromControl())
                GetGridFromSelectors();
 
            // Do not take ownership of a grid the caller passed in:
            //  - null in -> hand them GPAL's internal grid.
            //  - grid in -> add our rows into THEIR grid and keep their reference so repeated GetGrid calls accumulate.
            if (null == returnGrid)
                returnGrid = (IGPALGrid<string>)CurrentUOW.RetGrid;
            else
                returnGrid.Add((IGPALGrid<string>)CurrentUOW.RetGrid);
 
            return this;
        }
 
        // Table-native: a single selector that resolves to a control exposing the UIA GridPattern
        // is read cell-by-cell via GetItem(row, col); TablePattern column headers become the header
        // row. Returns false when this is not a grid control so the selector-column path runs.
        private bool TryGetGridFromControl()
        {
            if (1 != CurrentUOW.WithSelectorList.Count
                || SelectorType.Selector != CurrentUOW.WithSelectorList[0].selectorSettings.SelectorType)
                return false;
 
            Selector sel = CurrentUOW.WithSelectorList[0];
            bool matchedAll; List<GPALAutomationElement> matched;
            var found = ElementHelper.FindElements(this, CurrentUOW, sel, out matchedAll, out matched);
            AutomationElement ae = (null != found && found.Count > 0) ? found[0].Ae : null;
            object gpObj;
            if (null == ae || !ae.TryGetCurrentPattern(GridPattern.Pattern, out gpObj))
                return false;
 
            GridPattern grid = (GridPattern)gpObj;
            int rows = grid.Current.RowCount;
            int cols = grid.Current.ColumnCount;
 
            List<string> headers = null;
            object tpObj;
            if (ae.TryGetCurrentPattern(TablePattern.Pattern, out tpObj))
            {
                AutomationElement[] colHeaders = ((TablePattern)tpObj).Current.GetColumnHeaders();
                if (null != colHeaders && colHeaders.Length > 0)
                {
                    headers = new List<string>();
 
                    // Name first, then the text. A column header's name IS its text: Explorer's are
                    // SplitButtons named Name, Date modified, Type and Size, and they offer a value pattern
                    // that answers empty, so asking for the text got four blank names
                    foreach (AutomationElement h in colHeaders)
                        headers.Add(true == string.IsNullOrWhiteSpace(h.Current.Name) ? (h.GetText() ?? string.Empty) : h.Current.Name);
                }
            }
 
            // a control can name its columns without offering TablePattern. A list view puts them in a Header
            // element with a HeaderItem for each column, which is the shape a person sees at the top of the
            // control, and those names are as much the column names as a pattern's would be
            if (null == headers)
                headers = ColumnHeadersUnder(ae);
 
            int cap = (int.MaxValue == CurrentUOW.WithAllThatMatch)
                        ? int.MaxValue : CurrentUOW.WithAllThatMatch;
 
            for (int r = 0; r < rows && CurrentUOW.RetGrid.Count() < cap; r++)
            {
                var row = new List<string>(cols);
                for (int c = 0; c < cols; c++)
                {
                    string text;
                    try
                    {
                        AutomationElement cell = grid.GetItem(r, c);
                        text = (null != cell) ? (cell.GetText() ?? string.Empty) : GPAL.ErrorPlaceholder;
                    }
                    catch
                    {
                        text = GPAL.ErrorPlaceholder;
                    }
                    row.Add(text);
                }
                CurrentUOW.RetGrid.AddRow(row);
            }
 
            if (null != headers && headers.Count > 0)
            {
                CurrentUOW.ControlHeaderList = headers;
 
                if (null == CurrentUOW.HeaderList || 0 == CurrentUOW.HeaderList.Count)
                    CurrentUOW.HeaderList = headers;
            }
 
            // what the control called its columns, kept on the application so a workflow can read it after the
            // grid rather than finding out from the saved file
            ColumnNames = null == headers ? new List<string>() : new List<string>(headers);
 
            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"GetGrid: [{sel.Name}] resolved to a UIA grid ([{rows}] x [{cols}]).", this, GPALObjectType.Application);
            return true;
        }

        private static List<string> ColumnHeadersUnder(AutomationElement element)
        {
            List<string> retVal = null;
 
            AutomationElement header = element.FindFirst(TreeScope.Descendants,
                new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Header));
 
            if (null != header)
            {
                // whatever the header holds, not only HeaderItems. Explorer's columns are SplitButtons, and a
                // list view that names its columns names them whatever control type it draws them with
                AutomationElementCollection items = header.FindAll(TreeScope.Children, Condition.TrueCondition);
 
                if (0 < items.Count)
                {
                    retVal = new List<string>();
 
                    foreach (AutomationElement item in items)
                        retVal.Add(true == string.IsNullOrWhiteSpace(item.Current.Name) ? (item.GetText() ?? string.Empty) : item.Current.Name);
                }
            }
 
            return retVal;
        }
 
        // Column-per-selector extraction: each selector is a column, repeating matches are the rows.
        // Mirrors the Browser column-zip (pad short columns, dedup rows, honor WithAllThatMatch and
        // multi-page paging) but reads cells with the UIA .Ae.GetText() the app side already uses.
        private void GetGridFromSelectors()
        {
            var names = new List<string>();
            foreach (Selector s in CurrentUOW.WithSelectorList)
                names.Add(s.Name);
 
            var seenRows = new HashSet<string>();
            bool capReached = false;
            int cap = (int.MaxValue == CurrentUOW.WithAllThatMatch)
                        ? int.MaxValue : CurrentUOW.WithAllThatMatch;
 
            for (int page = 0; page < CurrentUOW.PageCount && !capReached; page++)
            {
                var columns = new List<List<string>>();
                int maxRows = 0;
 
                foreach (Selector sel in CurrentUOW.WithSelectorList)
                {
                    var col = new List<string>();
                    if (SelectorType.Selector == sel.selectorSettings.SelectorType)
                    {
                        bool matchedAll; List<GPALAutomationElement> matched;
                        var found = ElementHelper.FindElements(this, CurrentUOW, sel, out matchedAll, out matched);
                        List<GPALAutomationElement> elems =
                            (!matchedAll && null != matched && matched.Count > 0)
                                ? matched
                                : (null != found ? found.ToList() : new List<GPALAutomationElement>());
                        foreach (GPALAutomationElement e in elems)
                            col.Add((null != e.Ae) ? (e.Ae.GetText() ?? string.Empty) : GPAL.ErrorPlaceholder);
                    }
                    else if (SelectorType.Data == sel.selectorSettings.SelectorType)
                        col.Add(sel.SelectorPath);
                    else if (SelectorType.DataFunc == sel.selectorSettings.SelectorType)
                        col.Add(sel.selectorSettings.DataFunction());
 
                    columns.Add(col);
                    if (col.Count > maxRows) maxRows = col.Count;
                }
 
                // pad short columns so every row has a cell per column
                for (int i = 0; i < columns.Count; i++)
                    while (columns[i].Count < maxRows)
                        columns[i].Add($"{GPAL.ErrorPlaceholder} : {names[i]}");
 
                for (int r = 0; r < maxRows && !capReached; r++)
                {
                    var row = new List<string>(columns.Count);
                    for (int c = 0; c < columns.Count; c++)
                        row.Add(columns[c][r]);
 
                    string key = string.Join("", row);
                    if (!seenRows.Add(key))
                        continue;   // duplicate row from a prior page/scroll pass
                    CurrentUOW.RetGrid.AddRow(row);
                    if (CurrentUOW.RetGrid.Count() >= cap)
                        capReached = true;
                }
 
                if (!capReached && page < CurrentUOW.PageCount - 1)
                    if (!ApplicationHelper.GotoNextPage(this))
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.INFO, $"GetGrid: no next page after page [{page + 1}].", this, GPALObjectType.Application);
                        break;
                    }
            }
 
            if (null == CurrentUOW.HeaderList || 0 == CurrentUOW.HeaderList.Count)
                CurrentUOW.HeaderList = names;
        }

        public IAllowWithHeaderOrFileActions WithHeader(string header)
        {
            if (true == CurrentUOW.GetGridCalled)
            {
                CurrentUOW.GetGridCalled = false;
                CurrentUOW.HeaderList.Clear();
            }
            CurrentUOW.HeaderList.Add(header);
            return this;
        }

        public IAllowWithHeaderOrFileActions WithGridToSave(IGPALGrid<string> gridToSave)
        {
            if (true == CurrentUOW.ActionCalled)
                CurrentUOW = new UnitOfWork();
 
            CurrentUOW.RetGrid = gridToSave;
 
            return this;
        }

        public IAllowWithPagesAndGridActions WithNextPageButton(Selector selector)
        {
            CurrentUOW.NextPageButton = selector;
            return this;
        }

        public IAllowWithPagesAndGridActions WithInfiniteScroll
        {
            get
            {
                CurrentUOW.InfiniteScroll = true;
                return this;
            }
        }

        public IAllowGetGridAndFillInFrom WithPages(int numberOfPages)
        {
            CurrentUOW.PageCount = numberOfPages;
            return this;
        }
 
        // Resolve the output column names for a grid save, handed to the Converter as column metadata
        // (WithColumnNames), NOT injected as a data row. Precedence, highest first, with a short higher list
        // topped up from the next level down:
        //   1. CurrentUOW.HeaderList  - the workflow's .WithHeader columns (override)
        //   2. the output GPALFile's ColumnList - the file's own columns (wildcard/.Next replication of the
        //      first entry happens at expansion time, so entry 0 is representative here)
        //   3. selector names - the ultimate global, always defined
        //   4. the control's own column names, e.g. a UIA TablePattern's headers
        //   5. generated column1..columnN - so the list is never narrower than the widest row, because a
        //      column with no name must never mean a column with no data
        // The result is then made unique: the writer keys cells by column name, so a repeated name would
        // collapse those columns into one holding the last value.
        // Whether the names are written is governed by the output file's FirstLineIsColumnNames.
        private List<string> ResolveHeaderColumns(GPALFile file)
        {
            List<string> selectorNames = CurrentUOW.WithSelectorList?.Where(s => null != s.Name).Select(s => s.Name).ToList()
                ?? new List<string>();
 
            List<string> fileColumns = new List<string>();
            IGPALGrid<string> columnList = ((IGPALFileInternal)file).FileSettings.ColumnList;
            if (null != columnList && 0 < columnList.Count() && null != columnList[0])
                fileColumns = new List<string>(columnList[0]);
 
            List<string> resolved = (null != CurrentUOW.HeaderList && 0 < CurrentUOW.HeaderList.Count)
                ? new List<string>(CurrentUOW.HeaderList)
                : new List<string>();
            for (int i = resolved.Count; i < fileColumns.Count; i++)
                resolved.Add(fileColumns[i]);
            for (int i = resolved.Count; i < selectorNames.Count; i++)
                resolved.Add(selectorNames[i]);
 
            // a name the control gave for itself beats a made up one, and WithHeader clears HeaderList, so the
            // control's names are kept apart and read from here
            List<string> controlHeaders = CurrentUOW.ControlHeaderList ?? new List<string>();
 
            for (int i = resolved.Count; i < controlHeaders.Count; i++)
                resolved.Add(controlHeaders[i]);
 
            // the converter writes the columns it has names for, so a name list shorter than the data would
            // drop everything past the end of it. Data is never trimmed to fit the names, the names are made
            // up to fit the data, so every cell reaches the file whatever was named
            int widest = 0;
 
            if (null != CurrentUOW.RetGrid)
                foreach (List<string> row in CurrentUOW.RetGrid)
                    if (null != row && widest < row.Count)
                        widest = row.Count;
 
            for (int i = resolved.Count; i < widest; i++)
                resolved.Add($"column{i + 1}");
 
            return UniqueColumns(resolved);
        }

        private static List<string> UniqueColumns(List<string> columns)
        {
            var used = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
            var result = new List<string>();
 
            for (int i = 0; i < columns.Count; i++)
            {
                string name = true == string.IsNullOrWhiteSpace(columns[i]) ? $"column{i + 1}" : columns[i].Trim();
                string candidate = name;
                int repeat = 1;
 
                while (false == used.Add(candidate))
                {
                    repeat++;
                    candidate = $"{name}{repeat}";
                }
 
                result.Add(candidate);
            }
 
            return result;
        }

        public IAllowAllActionAndAnySelector SaveTo(GPALFile file)
        {
            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Saving [{CurrentUOW.RetGrid?.Rows ?? 0}] rows of window data to [{file?.Filename}].", this, GPALObjectType.Application);
 
            var converter = GPAL.Converter.WithInput(CurrentUOW.RetGrid).WithColumnNames(ResolveHeaderColumns(file));
            // Naming headers via WithHeader is clear intent to write them; declare it so the output emits a
            // header row unless the output file explicitly turns it off (WithFirstLineIsColumnNames(false)).
            if (null != CurrentUOW.HeaderList && 0 < CurrentUOW.HeaderList.Count)
                converter.WithFirstLineHasColumnNames(true);
            converter.SaveTo(file);
            return this;
        }

        public IAllowAllActionAndAnySelector AppendTo(GPALFile file)
        {
            GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Appending [{CurrentUOW.RetGrid?.Rows ?? 0}] rows of window data to [{file?.Filename}].", this, GPALObjectType.Application);
 
            GPAL.Converter.WithInput(CurrentUOW.RetGrid).WithColumnNames(ResolveHeaderColumns(file)).AppendTo(file);
            return this;
        }
        #endregion <GetGrid / SaveTo / Pagination>
        public IAllowAfterWaitForAndSizeControl WithWaitForWindowTimeout(int waitTimeInSeconds)
        {
            ApplicationSettings.WaitForWindowTimeout = waitTimeInSeconds;
            return this;
        }

        public IAllowApplicationSettingsOrOpen WithParameter(string parameter)
        {
            ApplicationSettings.Parameters.Add(parameter);
            return this;
        }

        public IAllowApplicationSettingsOrOpen WithUseHardware(bool trueFalse)
        {
            ApplicationSettings.UseHardware = trueFalse;
            return this;
        }

        public IAllowApplicationSettingsOrOpen WithNewInstance(bool trueFalse)
        {
            ApplicationSettings.NewInstance = trueFalse;
            return this;
        }

        public IAllowApplicationSettingsOrOpen WithHiddenDesktop(bool hiddenDesktop)
        {
            ApplicationSettings.HiddenDesktop = hiddenDesktop;
 
            // a program that asks for a hidden desktop without saying which is asking for one of its own, so it
            // gets a name nothing else will be handed. two programs sharing is what naming one is for
            if (true == hiddenDesktop)
                ApplicationSettings.HiddenDesktopName = Desktops.NextName();
 
            return this;
        }

        public IAllowApplicationSettingsOrOpen WithHiddenDesktop(string desktopName)
        {
            ApplicationSettings.HiddenDesktop = true;
 
            // calling this at all is asking for a hidden desktop. a name that turned out to be nothing is a
            // desktop of this program's own, the same as asking without a name. not wanting one is not calling
            ApplicationSettings.HiddenDesktopName = true == string.IsNullOrWhiteSpace(desktopName)
                                                  ? Desktops.NextName()
                                                  : desktopName;
 
            return this;
        }

        public IAllowAfterAnySelector CallIfFound(Application.CallIfDelegate callIfFoundDelegate)
        {
            CurrentUOW.AppCallIfFound.Add(callIfFoundDelegate);
            return this;
        }

        public IAllowAfterAnySelector CallIfNotFound(Application.CallIfDelegate callIfNotFoundDelegate)
        {
            CurrentUOW.AppCallIfNotFound.Add(callIfNotFoundDelegate);
            return this;
        }

        public IAllowAfterAnySelector CallAfterFillIn(CallAfterFillInDelegate callAfterFillIn)
        {
            CurrentUOW.AppCallAfterFillIn = callAfterFillIn;
            return this;
        }

        public bool IsEndOfPage()
        {
            bool retVal = true;
            ScrollPattern view = ScrollableView();
 
            if (null != view)
            {
                ScrollPattern.ScrollPatternInformation at = view.Current;
 
                // a control that stops scrolling reports NoScroll, -1, rather than a position
                retVal = false == at.VerticallyScrollable || 100 <= Math.Round(at.VerticalScrollPercent);
            }
 
            return retVal;
        }

        internal ScrollPattern ScrollableView()
        {
            ScrollPattern retVal = null;
            AutomationElement root = RootAutomationElement;
 
            if (null != root)
            {
                AutomationElement focused = AutomationElement.FocusedElement;
 
                if (null != focused && focused.Current.ProcessId != root.Current.ProcessId)
                    focused = null;
 
                // the raw view, since WinForms leaves whole controls out of the control view
                for (AutomationElement at = focused; null != at && null == retVal; at = TreeWalker.RawViewWalker.GetParent(at))
                    if (true == at.TryGetCurrentPattern(ScrollPattern.Pattern, out object pattern) && true == ((ScrollPattern)pattern).Current.VerticallyScrollable)
                        retVal = (ScrollPattern)pattern;
 
                if (null == retVal)
                {
                    AutomationElement first = root.FindFirst(TreeScope.Subtree, new AndCondition(
                        new PropertyCondition(AutomationElement.IsScrollPatternAvailableProperty, true),
                        new PropertyCondition(ScrollPattern.VerticallyScrollableProperty, true)));
 
                    if (null != first)
                        retVal = (ScrollPattern)first.GetCurrentPattern(ScrollPattern.Pattern);
                }
            }
 
            return retVal;
        }
 
        #region <Getters/Setters>
        public IHiddenDesktop HiddenDesktop => true == ApplicationSettings.HiddenDesktop
            ? new GPALHiddenDesktop(ApplicationSettings.HiddenDesktopName)
            : null;

        public IReadOnlyList<string> ColumnNames { get; private set; } = new List<string>();
        public Process Process
        {
            get
            {
                return applicationSettings.Process;
            }
            internal set
            {
                applicationSettings.Process = value;
            }
        }

        public object ManagedRootAutomationElement
        {
            get
            {
                return applicationSettings.ManagedRootAutomationElement;
            }
 
            internal set
            {
                applicationSettings.ManagedRootAutomationElement = value;
            }
        }

        public AutomationElement RootAutomationElement
        {
            get
            {
                return applicationSettings.RootAutomationElement;
            }
 
            internal set
            {
                applicationSettings.RootAutomationElement = value;
            }
        }

        public string Name
        {
            get
            {
                return ApplicationSettings.Name;
            }
 
            internal set
            {
                ApplicationSettings.Name = value;
            }
        }

        public string ApplicationPath
        {
            get
            {
                return applicationSettings.ApplicationPath;
            }
            internal set
            {
                applicationSettings.ApplicationPath = value;
            }
        }

        internal ApplicationSettings ApplicationSettings
        {
            get 
            { 
                return applicationSettings; 
            }
        }
        #endregion <Getters/Setters>
        #endregion <Application Settings>
    }
}