Interfaces.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.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using OpenQA.Selenium;
using static GenerallyPositive.GPALForm.GPALForm;
using static GenerallyPositive.Enums;
using static GenerallyPositive.GPAL;
using static GenerallyPositive.Application.Application;
using System.Windows.Automation;
 
namespace GenerallyPositive.Application
{
    #region <Application Interfaces>
    #region <Base Application Interfaces>
    public interface IAllowPersistentCallBack
    {
        // return values
        // 0 = not handled
        // 1 = handled
        // -1 = error
        [Callback(Description = "GLOBAL based callback if any selector in any UOW is found")]
        IAllowPersistentCallBack PersistentCallIfFound(Application.CallIfDelegate CallIfFound);
        [Callback(Description = "GLOBAL based callback if any selector in any UOW is NOT found")]
        IAllowPersistentCallBack PersistentCallIfNotFound(Application.CallIfDelegate CallIfNotFound);
    }
 
    public interface IAllowFillInFrom
    {
        [Data(Description = "")] IAllowSelectorActionOrAnySelector FillInFrom(string textToUse);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector AppendFrom(string textToUse);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector InsertFrom(string textToUse);
 
        [Data(Description = "")] IAllowSelectorActionOrAnySelector FillInFrom(GPALFile inputFile);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector AppendFrom(GPALFile inputFile);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector InsertFrom(GPALFile inputFile);
 
        [Data(Description = "")] IAllowSelectorActionOrAnySelector FillInFrom(GPALDatabase inputDatabase);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector AppendFrom(GPALDatabase inputDatabase);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector InsertFrom(GPALDatabase inputDatabase);
 
        [Data(Description = "")] IAllowSelectorActionOrAnySelector FillInFrom(IGPALGrid<string> inputGrid);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector AppendFrom(IGPALGrid<string> inputGrid);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector InsertFrom(IGPALGrid<string> inputGrid);
    }
    public interface IAllowClicks
    {
        [Action(Description = "")] IAllowSelectorActionOrAnySelector LeftClick(Selector selector = null);
        [Action(Description = "")] IAllowSelectorActionOrAnySelector LeftClick(ModifierKeys modifierKeys);
        [Action(Description = "")] IAllowSelectorActionOrAnySelector LeftDoubleClick(Selector selector = null);
        [Action(Description = "")] IAllowSelectorActionOrAnySelector MiddleClick(Selector selector = null);
        [Action(Description = "")] IAllowSelectorActionOrAnySelector RightClick(Selector selector = null);
        [Action(Description = "Drag-and-drop using selector's DeltaX/DeltaY as the drag distance from the element's origin. Always uses hardware mouse events.")] IAllowSelectorActionOrAnySelector DragAndDrop(Selector selector = null);
        [Action(Description = "Drag-and-drop while holding a modifier key.")] IAllowSelectorActionOrAnySelector DragAndDrop(ModifierKeys modifierKeys);
    }
    public interface IAllowKeyboardActions
    {
        [Data(Description = "")] IAllowSelectorActionOrAnySelector SendString(string textToSend);
        [Data(Description = "")] IAllowSelectorActionOrAnySelector SendKey(byte VKCode);
        IAllowSelectorActionOrAnySelector PressModifierKey(ModifierKeys modifierKeys);
        IAllowSelectorActionOrAnySelector ReleaseModifierKey(ModifierKeys modifierKeys);
    }
    public interface IAllowScrolling
    {
        [Scroll(Description = "")] IAllowSelectorActionOrAnySelector ScrollHorizontalSmall(int iterations);
        [Scroll(Description = "")] IAllowSelectorActionOrAnySelector ScrollHorizontalLarge(int iterations);
        [Scroll(Description = "")] IAllowSelectorActionOrAnySelector ScrollHorizontalPercent(int percent);
        [Scroll(Description = "")] IAllowSelectorActionOrAnySelector ScrollVerticalSmall(int iterations);
        [Scroll(Description = "")] IAllowSelectorActionOrAnySelector ScrollVerticalLarge(int iterations);
        [Scroll(Description = "")] IAllowSelectorActionOrAnySelector ScrollVerticalPercent(int percent);
    }
    public interface IAllowCallBack
    {
        // return values
        // 0 = not handled
        // 1 = handled
        // -1 = error
        [Callback(Description = "UOW based callback if any selector in the UOW is found")]
        IAllowAfterAnySelector CallIfFound(Application.CallIfDelegate CallIfFound);
        [Callback(Description = "UOW based callback if any selector in the UOW is NOT found")]
        IAllowAfterAnySelector CallIfNotFound(Application.CallIfDelegate CallIfNotFound);
        [Callback(Description = "UOW based callback when a row of input is consumed and entered.\nUseful for chaining to another workflow")]
        IAllowAfterAnySelector CallAfterFillIn(Application.CallAfterFillInDelegate CallAfterFillIn);
    }
 
    public interface IAllowSizeControl
    {
        [Action(Description = "")]
        IAllowAllApplicationAndAllSelector Maximize { get; }
        [Action(Description = "")]
        IAllowAllApplicationAndAllSelector Minimize { get; }
        [Action(Description = "")]
        IAllowAllApplicationAndAllSelector Restore { get; }
        [Action(Description = "Resize the window matched by WaitForWindow to the given width and height in pixels.")]
        IAllowAllApplicationAndAllSelector ResizeWindow(int width, int height);
        [Action(Description = "Move the window matched by WaitForWindow to the given screen coordinates.")]
        IAllowAllApplicationAndAllSelector MoveWindow(int x, int y);
    }
    public interface IAllowWaitForWindow
    {
        [Wait(Description = "")]
        IAllowAfterWaitForAndSizeControl WaitForWindow(string windowName);
        [Wait(Description = "")]
        IAllowAfterWaitForAndSizeControl WaitForWindowRegex(string windowNameRegex);
        [Wait(Description = "")]
        IAllowAfterWaitForAndSizeControl WithWaitForWindowTimeout(int waitTimeInSeconds);
 
    }
    public interface IAllowTabActions
    {
        [Action(Description = "")] IAllowAllActionAndAnySelector SwitchToTab(Selector selector = null);
    }
    public interface IAllowApplicationOpen
    {
        [Fluent(Description = "")]
        IAllowAllExceptParameters Open([Directory()] string ApplicationPath);
    }
    public interface IAllowApplicationSettings
    {
        [Settings(Description = "Name to use in Information and Exception channel messages")]
        IAllowApplicationSettingsOrOpen WithName(string name);
        [Settings(Description = "Parameter to pass into the program (will be concatenated to one string)")]
        IAllowApplicationSettingsOrOpen WithParameter(string parameter);
        [Settings(Description = "Use hardwre emulation for the entire workflow")]
        IAllowApplicationSettingsOrOpen WithUseHardware(bool trueFalse);
    }
    #endregion <Base Application Interfaces>
        #region <Derived Application Interfaces>
    public interface IAllowApplicationSettingsOrOpen : IAllowApplicationSettings, IAllowApplicationOpen
    { }
    public interface IAllowApplicationOpenOrParameters
    : IAllowApplicationOpen
    , IAllowApplicationSettings
    { }
    public interface IAllowAfterAnySelector
        : IAllowSelectorAction
        , IAllowCallBack
        , IAllowWithAllThatMatch
        , IAllowWithNextPageButtonOrGetGrid
        , IAllowWithInfiniteScroll
        , IAllowWithPages
    { }
    // NOTE: Add to this list what is added above
    public interface IAllowAfterAnySelectorExceptWithAll
        : IAllowSelectorAction
        , IAllowCallBack
        , IAllowWithNextPageButtonOrGetGrid
        , IAllowWithInfiniteScroll
        , IAllowWithPages
    { }
 
    public interface IAllowSelectorAction
        : IAllowClicks
        , IAllowFillInFrom
        , IAllowFocus
        , IAllowHover
        , IAllowMoveTo
        , IAllowScrolling
        , IAllowWaitFor
        , IAllowKeyboardActions
        , IAllowSetRange
        , IAllowToGPALObject<Application>
    { }
 
    public interface IAllowSelectorActionOrAnySelector
        : IAllowWithSelector
        , IAllowSelectorAction
        , IAllowWaitForWindow
        , IAllowWaitFor
        , IAllowCallBack
        , IAllowWithAllThatMatch
        , IAllowWithNextPageButtonOrGetGrid
        , IAllowWithInfiniteScroll
        , IAllowWithPages
    { }
    public interface IAllowWithHeaderOrFileActions
    : IAllowWithHeader
    , IAllowFileActions
    , IAllowAllActionAndAnySelector
    { }
    public interface IAllowFileActions
    {
        [File(Description = "Save the retrieved grid. Output format and delimiter are determined by the GPALFile (its extension, or explicit file settings).")]
        IAllowAllActionAndAnySelector SaveTo([GPALFile(Description = "")] GPALFile file);
        [File(Description = "Append the retrieved grid. Output format and delimiter are determined by the GPALFile (its extension, or explicit file settings).")]
        IAllowAllActionAndAnySelector AppendTo([GPALFile(Description = "")] GPALFile file);
    }
    public interface IAllowAllActionAndAnySelector
        : IAllowApplicationAction
        , IAllowAnySelector
        , IAllowSelectorAction
        , IAllowWaitFor
        , IAllowWaitForWindow
    { }
    public interface IAllowAfterWaitForAndSizeControl
        : IAllowAfterAnySelector
        , IAllowSizeControl
        , IAllowCallBack
    { }
    public interface IAllowAllApplicationAndAllSelector
        : IAllowApplicationAction
        , IAllowAnySelector
        , IAllowAfterAnySelector
        , IAllowSizeControl
        , IAllowApplicationSettings
    { }
    public interface IAllowAllExceptParameters
        : IAllowApplicationAction
        , IAllowAnySelector
        , IAllowAfterAnySelector
        , IAllowSizeControl
    { }
    public interface IAllowApplicationAction
        : IAllowClose
        , IAllowTabActions
        , IAllowSizeControl
    { }
    public interface IAllowAnySelector
        : IAllowWithSelector
    { }
    public interface IAllowPersistence
    : IAllowWithPersistentSelector
    , IAllowPersistentCallBack
    { }
 
    #endregion <Derived Application Interfaces>
    #region <Application Atoms>
    public interface IAllowToGPALObject<TResult>
    {
        [Fluent(Description = "Ends a declaration or workflow, returning a GPAL object which can be assigned. Use instead of an explicit cast. [ Selector mySel = GPAL.Selector.WithCSS(css).ToGPALObject() ]")]
        TResult ToGPALObject();  
    }
    public interface IAllowWithPersistentSelector 
    {
        [Selector(Description = "")]
        IAllowPersistence WithPersistentSelector(Selector selector); 
    }
    public interface IAllowWithSelector 
    {
        [Selector(Description = "")]
        IAllowSelectorActionOrAnySelector WithSelector(Selector selector); 
    }
    public interface IAllowClose 
    {
        [Action(Description = "")]
        void Close(); 
    }
    public interface IAllowFocus
    {
        [Action(Description = "")] IAllowSelectorActionOrAnySelector Focus(Selector selector = null);
    }
    public interface IAllowHover
    {
        [Action(Description = "")] IAllowSelectorActionOrAnySelector Hover(Selector selector = null);
    }
    public interface IAllowWithAllThatMatch 
    {
        [Settings(Description = "")]
        IAllowAfterAnySelectorExceptWithAll WithAllThatMatch(int rowCount); 
    }
    public interface IAllowMoveTo
    {
        [Action(Description = "")] IAllowSelectorActionOrAnySelector MoveTo(Selector selector = null);
    }
    public interface IAllowGetGrid
    {
        [Action(Description = "Retrieve data and add it into this GPALGrid. Pass a grid configured with .WithDedupeData(true) to skip duplicate rows.  GPAL also keeps it internally for SaveTo*.")]
        IAllowWithHeaderOrFileActions GetGrid(ref IGPALGrid<string> returnGrid);
    }
    public interface IAllowWaitFor 
    {
        [Action(Description = "")]
        IAllowAfterWaitForAndSizeControl WaitFor(int waitForTimeInTicks); 
    }
    public interface IAllowWithHardware 
    { 
        IAllowAfterAnySelector WithHardware
        {
            [Settings(Description = "")] 
            get; 
        } 
    }
    public interface IAllowWithHeader 
    {
        [Settings(Description = "")]
        IAllowWithHeaderOrFileActions WithHeader(string header); 
    }
    public interface IAllowWithGridToSave
    {
        [Settings(Description = "")]
        IAllowWithHeaderOrFileActions WithGridToSave(IGPALGrid<string> _);
    }
    public interface IAllowWithNextPageButton
    {
        [Data(Description = "When retrieving multiple pages of results, the control to click to load the next page.")]
        IAllowWithPagesAndGridActions WithNextPageButton(Selector selector);
    }
    public interface IAllowWithInfiniteScroll
    {
        IAllowWithPagesAndGridActions WithInfiniteScroll
        {
            [Data(Description = "When retrieving multiple pages of results, scroll to load more rows. Not supported for desktop applications.")]
            get;
        }
    }
    public interface IAllowWithPages
    {
        [Data(Description = "Number of result pages to retrieve when paging through results.")]
        IAllowGetGridAndFillInFrom WithPages(int numberOfPages);
    }
    public interface IAllowWithNextPageButtonOrGetGrid
        : IAllowWithNextPageButton
        , IAllowGetGrid
    { }
    public interface IAllowWithPagesAndGridActions
        : IAllowWithPages
        , IAllowGetGrid
    { }
    public interface IAllowGetGridAndFillInFrom
        : IAllowGetGrid
        , IAllowFillInFrom
    { }
    public interface IAllowSetRange
    {
        [Data(Description = "Set the value of an input slider, number and other range/numeric inputs")]
        IAllowAllActionAndAnySelector SetRange(double rangeValue);
    }
 
    #endregion <Application Atoms>
    public interface IApplication : IAllowAllActionAndAnySelector
        , IAllowAllApplicationAndAllSelector
        , IAllowSelectorActionOrAnySelector
        , IAllowSizeControl
        , IAllowAfterWaitForAndSizeControl
        , IAllowPersistence
        , IAllowAfterAnySelectorExceptWithAll
        , IAllowAllExceptParameters
        , IAllowApplicationOpenOrParameters
        , IAllowApplicationSettingsOrOpen
        , IAllowApplicationSettings
        , IAllowWithHeaderOrFileActions
        , IAllowWithPagesAndGridActions
        , IAllowGetGridAndFillInFrom
        , IAllowWithGridToSave
    {
        System.Diagnostics.Process Process { get; }
        object ManagedRootAutomationElement { get; }
        AutomationElement RootAutomationElement { get; }
        string Name { get; }
        string ApplicationPath { get; }
    }
    #endregion <Application Interfaces>
    #region <Element Assistant Interfaces>
    public interface IAllowElementSettingsAndActions
    : IAllowElementSetting
    , IAllowElementActions
    { }
    public interface IAllowElementActions
    {
        IAllowElementSettingsAndActions LeftClick();
        IAllowElementSettingsAndActions LeftClick(ModifierKeys modifierKeys);
        IAllowElementSettingsAndActions LeftDoubleClick();
        IAllowElementSettingsAndActions RightClick();
        IAllowElementSettingsAndActions FillInFrom(string inputText);
        IAllowElementSettingsAndActions InsertFrom(string inputText);
        IAllowElementSettingsAndActions AppendFrom(string inputText);
        IAllowElementSettingsAndActions SendKeyCode(byte keyCode);
        IAllowElementSettingsAndActions PressModifierKey(ModifierKeys modifierKeys);
        IAllowElementSettingsAndActions ReleaseModifierKey(ModifierKeys modifierKeys);
        IAllowElementSettingsAndActions ScrollHorizontal(System.Windows.Automation.ScrollAmount scrollAmount);
        IAllowElementSettingsAndActions ScrollHorizontalPercent(int percent);
        IAllowElementSettingsAndActions ScrollVertical(System.Windows.Automation.ScrollAmount scrollAmount);
        IAllowElementSettingsAndActions ScrolVerticalPercent(int percent);
    }
    public interface IAllowElementSetting
    {
        IAllowElementSettingsAndActions WithElement(IGPALAutomationElement Element);
        IAllowElementSettingsAndActions WithHardware { get; }
    }
    public interface IAllowForSelector { IAllowElementSetting ForSelector(Selector selector); };
    #endregion <Element Assistant Interfaces>
 
 
}