FileDialogHelper.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.Runtime.InteropServices;
using System.Threading;
using System.Windows.Automation;
using static GenerallyPositive.Enums;
using Desktops = GenerallyPositive.Browser.HiddenDesktop;
 
namespace GenerallyPositive.Application
{
    internal static class FileDialogHelper
    {
        // the file name field and the accept button. 1148 is the id the field usually carries, on itself or on
        // the combo box hosting it, and 1152 is the one it carries in some Save dialogs. None of them is
        // relied on alone
        private const string FILE_NAME_ID = "1148";
        private const string FILE_NAME_ALTERNATE_ID = "1152";
        private const string FILE_NAME_HOST_ID = "FileNameControlHost";
        private const string ACCEPT_ID = "1";
 
        // how many of a window's buttons the "what is this dialog" message lists before it stops
        private const int BUTTONS_LISTED = 8;
 
        // the Win32 class every dialog button is, whatever UIAutomation decides to call the control
        private const string BUTTON_CLASS = "Button";
 
        // IDCANCEL, the id a common dialog's Cancel button carries the way accept carries 1
        private const string CANCEL_ID = "2";

        [DllImport("user32.dll")]
        private static extern bool IsWindow(IntPtr hWnd);
 
        private const int BETWEEN_LOOKS = 250;
 
        // how long a dialog is given to go away once it has been accepted. A dialog that took what it was
        // given closes at once, so this is only ever spent on one that did not, and spending ten seconds
        // deciding that is ten seconds of a workflow looking like it has hung
        private const int SETTLING_MS = 5000;
 
        // how often to ask whether the dialog has closed, which is one cheap call to Windows
        private const int BETWEEN_CLOSING_LOOKS = 50;
 

        internal static bool Answer(Application application, GPALFile file, int waitSeconds)
        {
            bool retVal = false;
 
            AutomationElement dialog = WaitForDialog(application, waitSeconds);
 
            if (null == dialog)
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"No file dialog appeared within [{waitSeconds}]s, so there was nothing to answer. {WindowsSeen(application)}", application, GPALObjectType.Application);
            else if (null == file || 0 == file.Count)
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "A file dialog appeared but no file was named to answer it with.", application, GPALObjectType.Application);
            else
            {
                AutomationElement field = FileNameField(dialog);
 
                if (null != field)
                    retVal = AnswerByField(application, dialog, field, file);
                else
                    retVal = AnswerByTree(application, dialog, file);
            }
 
            // a dialog that was not answered is still on screen and still modal, so everything the workflow
            // does next goes into it: a click lands on whatever the dialog has at those coordinates and a
            // keystroke goes to its file name field. Cancelling leaves the application usable and leaves the
            // failure as just a failure
            if (false == retVal && null != dialog)
                Cancel(application, dialog);
 
            return retVal;
        }

        private static AutomationElement WaitForDialog(Application application, int waitSeconds)
        {
            AutomationElement retVal = null;
            Stopwatch waited = Stopwatch.StartNew();
 
            while (null == retVal && waited.ElapsedMilliseconds < waitSeconds * 1000)
            {
                retVal = FirstWindowWhere(application, LooksLikeADialog);
 
                if (null == retVal)
                    Thread.Sleep(BETWEEN_LOOKS);
            }
 
            return retVal;
        }

        private static AutomationElement FirstWindowWhere(Application application, Func<AutomationElement, bool> matches)
        {
            AutomationElement retVal = null;
            var isWindow = new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Window);
 
            if (null != application?.RootAutomationElement)
            {
                retVal = FirstWindowUnder(application.RootAutomationElement, TreeScope.Children, isWindow, matches);
 
                if (null == retVal)
                    retVal = FirstWindowUnder(application.RootAutomationElement, TreeScope.Descendants, isWindow, matches);
            }
 
            if (null == retVal)
                foreach (AutomationElement top in TopLevelWindows(application))
                    if (true == matches(top))
                    {
                        retVal = top;
                        break;
                    }
 
            return retVal;
        }

        private static List<AutomationElement> TopLevelWindows(Application application)
        {
            List<AutomationElement> retVal = new List<AutomationElement>();
 
            if (false == application.applicationSettings.HiddenDesktop)
            {
                var isWindow = new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Window);
 
                foreach (AutomationElement window in AutomationElement.RootElement.FindAll(TreeScope.Children, isWindow))
                    retVal.Add(window);
            }
            else
                foreach (IntPtr handle in Desktops.WindowsOn(application.applicationSettings.HiddenDesktopName))
                {
                    AutomationElement onDesktop = AutomationElement.FromHandle(handle);
 
                    if (null != onDesktop)
                        retVal.Add(onDesktop);
                }
 
            return retVal;
        }

        private static AutomationElement FirstWindowUnder(AutomationElement under, TreeScope scope, Condition isWindow, Func<AutomationElement, bool> matches)
        {
            AutomationElement retVal = null;
 
            try
            {
                foreach (AutomationElement window in under.FindAll(scope, isWindow))
                    if (null == retVal && true == matches(window))
                        retVal = window;
            }
            catch (Exception)
            {
                // a window that closed while the tree was being read is not the one being waited for
            }
 
            return retVal;
        }

        private static Condition AcceptCondition()
        {
            return ButtonCondition(ACCEPT_ID);
        }

        private static Condition ButtonCondition(string id)
        {
            return new AndCondition(
                new PropertyCondition(AutomationElement.AutomationIdProperty, id),
                new OrCondition(
                    new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Button),
                    new PropertyCondition(AutomationElement.ClassNameProperty, BUTTON_CLASS)));
        }

        private static AutomationElement AcceptButton(AutomationElement window)
        {
            return ButtonWithId(window, ACCEPT_ID);
        }

        private static AutomationElement ButtonWithId(AutomationElement window, string id)
        {
            AutomationElement retVal = window.FindFirst(TreeScope.Descendants, ButtonCondition(id));
 
            if (null == retVal)
            {
                System.Collections.Generic.List<AutomationElement> raw = ElementHelper.RawMatches(window, ButtonCondition(id), false);
 
                retVal = 0 < raw.Count ? raw[0] : null;
            }
 
            return retVal;
        }

        private static bool LooksLikeADialog(AutomationElement window)
        {
            bool retVal = false;
 
            AutomationElement accept = AcceptButton(window);
 
            if (null != accept)
                retVal = null != FileNameField(window)
                      || null != window.FindFirst(TreeScope.Descendants, new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Tree));
 
            return retVal;
        }

        private static string WindowsSeen(Application application)
        {
            var seen = new List<string>();
 
            if (null != application?.RootAutomationElement)
            {
                Describe(seen, "under the application", application.RootAutomationElement, TreeScope.Children);
                Describe(seen, "deeper in the application", application.RootAutomationElement, TreeScope.Descendants);
            }
 
            foreach (AutomationElement top in TopLevelWindows(application))
                Describe(seen, true == application.applicationSettings.HiddenDesktop
                    ? $"on [{application.applicationSettings.HiddenDesktopName}]"
                    : "on the desktop", top, TreeScope.Element);
 
            return 0 == seen.Count ? "No windows were found in any of the places a dialog is looked for." : $"Windows looked at: {string.Join(" | ", seen)}";
        }

        private static void Describe(List<string> seen, string where, AutomationElement under, TreeScope scope)
        {
            try
            {
                // a window is asked about itself when the scope is the element, because a top level window on a
                // hidden desktop does not always call itself a Window and a diagnostic that lists nothing is
                // worse than one that lists something unexpected
                AutomationElementCollection windows = TreeScope.Element == scope
                    ? under.FindAll(scope, Condition.TrueCondition)
                    : under.FindAll(scope, new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Window));
 
                foreach (AutomationElement window in windows)
                {
                    bool accept = null != AcceptButton(window);
 
                    int edits = window.FindAll(TreeScope.Descendants,
                        new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Edit)).Count;
 
                    bool named = null != window.FindFirst(TreeScope.Descendants, new AndCondition(
                        new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Edit),
                        new PropertyCondition(AutomationElement.AutomationIdProperty, FILE_NAME_ID)));
 
                    bool tree = null != window.FindFirst(TreeScope.Descendants,
                        new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Tree));
 
                    seen.Add($"{where}: [{window.Current.ClassName}] '{window.Current.Name}' accept button {(true == accept ? "yes" : $"NO, its buttons are {ButtonsIn(window)}")}, field {FILE_NAME_ID} {(true == named ? "yes" : "NO")}, edits [{edits}], tree {(true == tree ? "yes" : "no")}");
                }
            }
            catch (Exception)
            {
                // a window that closed while the list was being read is not the one being waited for
            }
        }

        private static string ButtonsIn(AutomationElement window)
        {
            var named = new System.Collections.Generic.List<string>();
 
            AutomationElementCollection buttons = window.FindAll(TreeScope.Descendants,
                new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Button));
 
            for (int button = 0; button < buttons.Count && named.Count < BUTTONS_LISTED; button++)
                named.Add($"[{buttons[button].Current.AutomationId}] '{buttons[button].Current.Name}'");
 
            if (BUTTONS_LISTED <= named.Count && BUTTONS_LISTED < buttons.Count)
                named.Add($"and [{buttons.Count - BUTTONS_LISTED}] more");
 
            return 0 == named.Count ? "none in the control view" : string.Join(" ", named);
        }

        private static AutomationElement FileNameField(AutomationElement dialog)
        {
            var isEdit = new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Edit);
 
            // by its id, directly
            AutomationElement retVal = dialog.FindFirst(TreeScope.Descendants, new AndCondition(isEdit,
                new PropertyCondition(AutomationElement.AutomationIdProperty, FILE_NAME_ID)));
 
            // by its id, on the combo box that hosts it
            if (null == retVal)
            {
                AutomationElement host = dialog.FindFirst(TreeScope.Descendants, new AndCondition(
                    new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.ComboBox),
                    new OrCondition(
                        new PropertyCondition(AutomationElement.AutomationIdProperty, FILE_NAME_ID),
                        new PropertyCondition(AutomationElement.AutomationIdProperty, FILE_NAME_HOST_ID))));
 
                if (null != host)
                    retVal = host.FindFirst(TreeScope.Descendants, isEdit);
            }
 
            // the other id the field has answered to
            if (null == retVal)
                retVal = dialog.FindFirst(TreeScope.Descendants, new AndCondition(isEdit,
                    new PropertyCondition(AutomationElement.AutomationIdProperty, FILE_NAME_ALTERNATE_ID)));
 
            // and by where it sits, which no version or language changes
            if (null == retVal)
                retVal = FieldBesideTheButton(dialog, isEdit);
 
            return retVal;
        }

        private static AutomationElement FieldBesideTheButton(AutomationElement dialog, Condition isEdit)
        {
            AutomationElement retVal = null;
 
            AutomationElement accept = dialog.FindFirst(TreeScope.Descendants, new AndCondition(
                new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Button),
                new PropertyCondition(AutomationElement.AutomationIdProperty, ACCEPT_ID)));
 
            if (null != accept)
            {
                System.Windows.Rect button = accept.Current.BoundingRectangle;
                double nearest = double.MaxValue;
 
                foreach (AutomationElement edit in dialog.FindAll(TreeScope.Descendants, isEdit))
                {
                    // it has to be writable, on screen, and to the left of the button rather than above or
                    // below it. The address bar and the search box are on a different line and lose on that
                    if (false == edit.Current.IsOffscreen
                        && true == edit.Current.IsEnabled
                        && true == edit.TryGetCurrentPattern(ValuePattern.Pattern, out object unused))
                    {
                        System.Windows.Rect field = edit.Current.BoundingRectangle;
                        double apart = Math.Abs((field.Top + field.Height / 2) - (button.Top + button.Height / 2));
 
                        if (field.Left < button.Left && apart < button.Height && apart < nearest)
                        {
                            nearest = apart;
                            retVal = edit;
                        }
                    }
                }
            }
 
            return retVal;
        }

        private static bool AnswerByField(Application application, AutomationElement dialog, AutomationElement field, GPALFile file)
        {
            bool retVal = false;
 
            // one file goes in as it is. Several are quoted and separated by spaces, which is the form a dialog
            // set to allow more than one reads, and quoting a single path with a space in it changes nothing
            var names = new List<string>();
 
            foreach (string name in file.Filenames)
                names.Add(1 == file.Count ? name : $"\"{name}\"");
 
            string answer = string.Join(" ", names);
 
            if (true == field.TryGetCurrentPattern(ValuePattern.Pattern, out object valuePattern))
            {
                ((ValuePattern)valuePattern).SetValue(answer);
 
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Answered the file dialog with [{answer}]", application, GPALObjectType.Application);
 
                retVal = Accept(application, dialog);
            }
            else
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "The file dialog's file name field cannot be written to, so the path could not be put in it.", application, GPALObjectType.Application);
 
            return retVal;
        }

        private static bool AnswerByTree(Application application, AutomationElement dialog, GPALFile file)
        {
            bool retVal = false;
 
            AutomationElement tree = dialog.FindFirst(TreeScope.Descendants,
                new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.Tree));
 
            if (null == tree)
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"The dialog has neither a file name field nor a folder tree, so it is not a common file dialog this can answer. {ElementHelper.WhatIsThere(dialog)}", application, GPALObjectType.Application);
            else
            {
                AutomationElement current = tree;
                string reached = string.Empty;
 
                foreach (string segment in file.Filename.Split(new char[] { '\\' }, StringSplitOptions.RemoveEmptyEntries))
                {
                    AutomationElement next = ChildNamed(current, segment);
 
                    if (null == next)
                    {
                        GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"The folder tree has no [{segment}] under [{(true == string.IsNullOrEmpty(reached) ? "the root" : reached)}], so [{file.Filename}] cannot be reached. {ElementHelper.WhatIsThere(current)}", application, GPALObjectType.Application);
                        current = null;
                        break;
                    }
 
                    Expand(next);
 
                    current = next;
                    reached = segment;
                }
 
                if (null != current)
                {
                    Select(current);
 
                    GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Walked the folder tree to [{file.Filename}]", application, GPALObjectType.Application);
 
                    retVal = Accept(application, dialog);
                }
            }
 
            return retVal;
        }

        private static AutomationElement ChildNamed(AutomationElement parent, string segment)
        {
            AutomationElement retVal = parent.FindFirst(TreeScope.Children, new AndCondition(
                new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.TreeItem),
                new PropertyCondition(AutomationElement.NameProperty, segment)));
 
            if (null == retVal)
                foreach (AutomationElement child in parent.FindAll(TreeScope.Children,
                    new PropertyCondition(AutomationElement.ControlTypeProperty, ControlType.TreeItem)))
                {
                    string name = child.Current.Name ?? string.Empty;
 
                    if (null == retVal && (true == name.EndsWith($"({segment})") || true == name.StartsWith($"{segment} ", StringComparison.OrdinalIgnoreCase)))
                        retVal = child;
                }
 
            return retVal;
        }

        private static void Expand(AutomationElement item)
        {
            if (true == item.TryGetCurrentPattern(ExpandCollapsePattern.Pattern, out object pattern)
                && ExpandCollapseState.Collapsed == ((ExpandCollapsePattern)pattern).Current.ExpandCollapseState)
                ((ExpandCollapsePattern)pattern).Expand();
        }

        private static void Select(AutomationElement item)
        {
            if (true == item.TryGetCurrentPattern(SelectionItemPattern.Pattern, out object pattern))
                ((SelectionItemPattern)pattern).Select();
        }

        private static bool Accept(Application application, AutomationElement dialog)
        {
            bool retVal = PressAndWait(application, dialog, AcceptButton(dialog), "accept");
 
            return retVal;
        }

        private static void Cancel(Application application, AutomationElement dialog)
        {
            AutomationElement button = ButtonWithId(dialog, CANCEL_ID);
 
            if (true == PressAndWait(application, dialog, button, "cancel"))
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, "The file dialog could not be answered, so it was cancelled. The application is where it was before the dialog was raised.", application, GPALObjectType.Application);
            else
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, "The file dialog could not be answered and could not be cancelled either, so it is still on screen and everything after this goes into it.", application, GPALObjectType.Application);
        }

        private static bool PressAndWait(Application application, AutomationElement dialog, AutomationElement button, string what)
        {
            bool retVal = false;
            bool pressed = false;
 
            // taken while the dialog is still there. Once it closes, asking it anything is asking a proxy for a
            // window that has gone
            IntPtr handle = new IntPtr(dialog.Current.NativeWindowHandle);
 
            if (null == button)
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"The file dialog has no {what} button. {ElementHelper.WhatIsThere(dialog)}", application, GPALObjectType.Application);
            else if (true == button.TryGetCurrentPattern(InvokePattern.Pattern, out object pattern))
            {
                ((InvokePattern)pattern).Invoke();
 
                pressed = true;
            }
            else if (true == MsaaHelper.Press(application, button))
                pressed = true;
            else if (true == ElementHelper.HardwareReaches(application))
            {
                ElementHelper.HardwareClick(application, new GPALAutomationElement(button), ClickType.LeftClick, ModifierKeys.NONE);
 
                pressed = true;
            }
            else
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"The file dialog's {what} button cannot be pressed. It offers no InvokePattern, MSAA would not press it, and the mouse cannot reach it here.", application, GPALObjectType.Application);
 
            if (true == pressed)
            {
                retVal = Settled(handle);
 
                if (false == retVal)
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"The file dialog's {what} button was pressed but the dialog is still on screen after [{SETTLING_MS / 1000}]s.", application, GPALObjectType.Application);
            }
 
            return retVal;
        }

        private static bool Settled(IntPtr handle)
        {
            bool retVal = false;
            Stopwatch waited = Stopwatch.StartNew();
 
            while (false == retVal && waited.ElapsedMilliseconds < SETTLING_MS)
            {
                retVal = IntPtr.Zero == handle || false == IsWindow(handle);
 
                if (false == retVal)
                    Thread.Sleep(BETWEEN_CLOSING_LOOKS);
            }
 
            return retVal;
        }
 
    }
}