HardwareHelper.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.Runtime.InteropServices;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using System.Windows.Input;
using static GenerallyPositive.Enums;
using ModifierKeys = GenerallyPositive.Enums.ModifierKeys;
 
namespace GenerallyPositive
{
    internal class HardwareHelper
    {
        // virtual keycodes: https://docs.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes?redirectedfrom=MSDN
        // scan codes: https://en.wikipedia.org/wiki/Scancode
        static byte scanCode = 0;
 
        // shared instance: a fresh Random(seed) per call was deterministic (same seed every time)
        private static readonly Random _random = new Random();

        internal static int GetTypingDelay(int ceilingMs)
        {
            if (0 >= ceilingMs)
                return 0;
 
            int floorMs = Math.Min(25, ceilingMs);
            return _random.Next(floorMs, ceilingMs + 1);
        }

        // https://stackoverflow.com/questions/26845532/c-sharp-ascii-to-keycode
        [DllImport("user32.dll")]
        public static extern short VkKeyScan(char ch);

        // http://tksinghal.blogspot.com/2011/04/how-to-press-and-hold-keyboard-key.html
        [DllImport("user32.dll")]
        public static extern void keybd_event(byte bVk, byte bScan, uint dwFlags, uint dwExtraInfo);

        // https://docs.microsoft.com/en-us/dotnet/desktop/winforms/input-mouse/how-to-simulate-events?view=netdesktop-6.0
        [DllImport("user32.dll", EntryPoint = "SetCursorPos")]
        [return: MarshalAs(UnmanagedType.Bool)]
        private static extern bool SetCursorPos(int x, int y);

        [DllImport("user32.dll")]
        public static extern bool GetCursorPos(out Point p);

        // https://stackoverflow.com/questions/8739523/directing-mouse-events-dllimportuser32-dll-click-double-click
        [DllImport("user32.dll")]
        static extern void mouse_event(int dwFlags, int dx, int dy,
                              int dwData, int dwExtraInfo);

        [Flags]
        public enum MouseEventFlags
        {
            LEFTDOWN = 0x00000002,
            LEFTUP = 0x00000004,
            MIDDLEDOWN = 0x00000020,
            MIDDLEUP = 0x00000040,
            MOVE = 0x00000001,
            ABSOLUTE = 0x00008000,
            RIGHTDOWN = 0x00000008,
            RIGHTUP = 0x00000010
        }

        public static void MouseDown(int x, int y, ClickType clickType)
        {
            MoveMouse(x, y);
            if (ClickType.LeftClick == clickType)
                mouse_event((int)(MouseEventFlags.LEFTDOWN), x, y, 0, 0);
            else if (ClickType.MiddleClick == clickType)
                mouse_event((int)(MouseEventFlags.MIDDLEDOWN), x, y, 0, 0);
            else if (ClickType.RightClick == clickType)
                mouse_event((int)(MouseEventFlags.RIGHTDOWN), x, y, 0, 0);
            else
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Unknown mouse down clicktype [{clickType}]", null, GPALObjectType.None);
        }
        public static void MouseUp(int x, int y, ClickType clickType)
        {
            MoveMouse(x, y);
            if (ClickType.LeftClick == clickType)
                mouse_event((int)(MouseEventFlags.LEFTUP), x, y, 0, 0);
            else if (ClickType.MiddleClick == clickType)
                mouse_event((int)(MouseEventFlags.MIDDLEUP), x, y, 0, 0);
            else if (ClickType.RightClick == clickType)
                mouse_event((int)(MouseEventFlags.RIGHTUP), x, y, 0, 0);
            else
                GPAL.PublishSimpleEvent(GPALEventType.ERROR, $"Unknown mouse down clicktype [{clickType}]", null, GPALObjectType.None);
        }

        public static void MiddleClick(int x, int y)
        {
            MoveMouse(x, y);
            // Separate down + up with a short dwell - a zero-duration combined click is dropped
            // intermittently by browsers (notably Firefox). Mirrors the reliable RightClick pattern.
            mouse_event((int)(MouseEventFlags.MIDDLEDOWN), x, y, 0, 0);
            Thread.Sleep(10);
            mouse_event((int)(MouseEventFlags.MIDDLEUP), x, y, 0, 0);
        }
        public static void LeftClick(int x, int y)
        {
            MoveMouse(x, y);
            // Separate down + up with a short dwell - a zero-duration combined click is dropped
            // intermittently by browsers (notably Firefox). Mirrors the reliable RightClick pattern.
            mouse_event((int)(MouseEventFlags.LEFTDOWN), x, y, 0, 0);
            Thread.Sleep(10);
            mouse_event((int)(MouseEventFlags.LEFTUP), x, y, 0, 0);
        }
        public static void LeftDoubleClick(int x, int y)
        {
            MoveMouse(x, y);
            mouse_event((int)(MouseEventFlags.LEFTDOWN | MouseEventFlags.LEFTUP), x, y, 0, 0);
            Thread.Sleep(15);
            mouse_event((int)(MouseEventFlags.LEFTDOWN | MouseEventFlags.LEFTUP), x, y, 0, 0);
        }
        public static void RightClick(int x, int y)
        {
            MoveMouse(x, y);
            // Simulate right mouse button down
            mouse_event((int)MouseEventFlags.RIGHTDOWN, x, y, 0, 0);
            Thread.Sleep(150);
            // Simulate right mouse button up
            mouse_event((int)MouseEventFlags.RIGHTUP, x, y, 0, 0);
 
        }
        public static void MoveMouse(int x, int y)
        {
            x = 0 <= x ? x : 0;
            y = 0 <= y ? y : 0;
 
            SetCursorPos(x, y);
        }
        internal static void PressModifierKey(ModifierKeys modifierKeys, bool dontPubolish = false)
        {
            if (false == dontPubolish)
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Pressed [{Browser.Browser.GetModifierKeys(modifierKeys)}]", modifierKeys, GPALObjectType.Other);
 
            if (0 != (ModifierKeys.Control & modifierKeys))
            {
                keybd_event(GPAL.VK_CONTROL_LEFT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
                keybd_event(GPAL.VK_CONTROL_RIGHT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
            }
 
            if (0 != (ModifierKeys.Shift & modifierKeys))
            {
                keybd_event(GPAL.VK_SHIFT_LEFT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
                keybd_event(GPAL.VK_SHIFT_RIGHT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
            }
 
            if (0 != (ModifierKeys.Alt & modifierKeys))
            {
                keybd_event(GPAL.VK_LMENU, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0); // Left Alt
                keybd_event(GPAL.VK_RMENU, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0); // Right Alt
            }
 
            if (0 != (ModifierKeys.Windows & modifierKeys))
            {
                keybd_event(GPAL.VK_LWIN, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
                keybd_event(GPAL.VK_RWIN, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
            }
 
            if (0 != (ModifierKeys.Application & modifierKeys))
            {
                keybd_event(GPAL.VK_APPS, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
            }
 
            if (0 != (ModifierKeys.ScrollLock & modifierKeys))
            {
                keybd_event(GPAL.VK_SCROLL, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0); // Press Scroll Lock
            }
        }

        internal static void ReleaseModifierKeys(ModifierKeys modifierKeys, bool dontPublish = false)
        {
            if (false == dontPublish)
                GPAL.PublishSimpleEvent(GPALEventType.INFO, $"Released [{Browser.Browser.GetModifierKeys(modifierKeys)}]", modifierKeys, GPALObjectType.Other);
 
            if (0 != (ModifierKeys.Alt & modifierKeys))
            {
                keybd_event(GPAL.VK_RMENU, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0); // Right Alt
                Thread.Sleep(150);
                keybd_event(GPAL.VK_LMENU, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0); // Left Alt
            }
 
            if (0 != (ModifierKeys.Control & modifierKeys))
            {
                keybd_event(GPAL.VK_CONTROL_RIGHT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
                Thread.Sleep(150);
                keybd_event(GPAL.VK_CONTROL_LEFT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
            }
 
            if (0 != (ModifierKeys.Shift & modifierKeys))
            {
                keybd_event(GPAL.VK_SHIFT_RIGHT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
                Thread.Sleep(150);
                keybd_event(GPAL.VK_SHIFT_LEFT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
            }
 
            if (0 != (ModifierKeys.Windows & modifierKeys))
            {
                keybd_event(GPAL.VK_RWIN, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
                Thread.Sleep(150);
                keybd_event(GPAL.VK_LWIN, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
            }
 
            if (0 != (ModifierKeys.Application & modifierKeys))
            {
                keybd_event(GPAL.VK_APPS, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
            }
 
            if (0 != (ModifierKeys.ScrollLock & modifierKeys))
            {
                keybd_event(GPAL.VK_SCROLL, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0); // Release Scroll Lock
            }
        }
        public static bool SendKey(byte keyToSend, ModifierKeys modifierKeys = ModifierKeys.NONE)
 
        {
            if (ModifierKeys.NONE != modifierKeys)
                PressModifierKey(modifierKeys);
 
            try
            {
                keybd_event(keyToSend, scanCode, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
                Thread.Sleep(_random.Next(10, 30)); // dwell time between press down and release, milliseconds
                keybd_event(keyToSend, scanCode, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
            }
            catch { }
 
            if (ModifierKeys.NONE != modifierKeys)
                ReleaseModifierKeys(modifierKeys);
 
            return true;
        }
        // CAVEAT: if SHIFT modifier is used with a mixed case string, sendchar will unshift and the whole string will not be sent in all caps.
        public static void SendString(string stringToSend, int delayMs = 0)
        {
            bool first = true;
            foreach (char c in stringToSend)
            {
                if (false == first && 0 < delayMs)
                    Thread.Sleep(GetTypingDelay(delayMs));
                SendChar(c, ModifierKeys.NONE, true);
                first = false;
            }
        }
        public static void SendChar(char charToSend, ModifierKeys modifierKeys = ModifierKeys.NONE, bool dontPublish = false)
        {
            short vkKeyScan = HardwareHelper.VkKeyScan(charToSend);
            System.Windows.Forms.Keys vkCode = (System.Windows.Forms.Keys)(vkKeyScan & 0xff);
 
            var shift = (vkKeyScan & 0x100) > 0;
            //var ctrl = (vkKeyScan & 0x200) > 0;
            //var alt = (vkKeyScan & 0x400) > 0;
 
            if (true == shift)  // uppercase char - keybd event has no concept of uppercase 'S', that is shift + 's' even if ascii has uppercase, keyboards do not
            {
                keybd_event(GPAL.VK_SHIFT_LEFT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
            }
 
            if (ModifierKeys.NONE != modifierKeys)
                PressModifierKey(modifierKeys, dontPublish);
 
            try
            {
                keybd_event((byte)vkCode, (byte)vkKeyScan, GPAL.KEYEVENTF_EXTENDEDKEY | 0, 0);
                Thread.Sleep(_random.Next(10, 30)); // dwell time between press down and release, milliseconds
                keybd_event((byte)vkCode, (byte)vkKeyScan, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
            }
            catch { }
 
            if (ModifierKeys.NONE != modifierKeys)
                ReleaseModifierKeys(modifierKeys, dontPublish);
 
            if (true == shift)
            {
                keybd_event(GPAL.VK_SHIFT_LEFT, 0, GPAL.KEYEVENTF_EXTENDEDKEY | GPAL.KEYEVENTF_KEYUP, 0);
            }
 
        }

        public static void HardwareClick(int x, int y, ClickType clickType)
        {
            switch (clickType)
            {
                case ClickType.LeftClick:
                    LeftClick(x, y);
                    break;
                case ClickType.LeftDoubleClick:
                    LeftDoubleClick(x, y);
                    break;
                case ClickType.MiddleClick:
                    MiddleClick(x, y);
                    break;
                case ClickType.RightClick:
                    RightClick(x, y);
                    break;
            }
 
        }
 
        // https://stackoverflow.com/questions/913646/c-sharp-moving-the-mouse-around-realistically
        // https://ben.land/post/2021/04/25/windmouse-human-mouse-movement/
        #region Improved WindMouse - Less Bounce, More Natural (C# 8 Compatible)

        public static void MoveMouse(int targetX, int targetY, int randomnessX = 4, int randomnessY = 4, double speed = 1.0)
        {
            Point current = new Point();
            GetCursorPos(out current);
 
            Random rnd = new Random();
 
            // Small target randomness
            targetX = Math.Max(0, targetX + rnd.Next(-randomnessX, randomnessX + 1));
            targetY = Math.Max(0, targetY + rnd.Next(-randomnessY, randomnessY + 1));
 
            double adjustedSpeed = Math.Max(0.4, speed);
 
            ImprovedWindMouse(
                current.X, current.Y,
                targetX, targetY,
                gravity: 9.0,
                wind: 2.5,
                minWait: 7.0 / adjustedSpeed,
                maxWait: 16.0 / adjustedSpeed,
                maxStep: 38.0 * adjustedSpeed,
                targetArea: 18.0
            );
        }

        private static void ImprovedWindMouse(double xs, double ys, double xe, double ye,
            double gravity, double wind, double minWait, double maxWait,
            double maxStep, double targetArea)
        {
            double dist, windX = 0, windY = 0, veloX = 0, veloY = 0;
            int oldX, oldY, newX = (int)Math.Round(xs), newY = (int)Math.Round(ys);
 
            double waitDiff = maxWait - minWait;
            double sqrt2 = Math.Sqrt(2.0);
            double sqrt3 = Math.Sqrt(3.0);
            double sqrt5 = Math.Sqrt(5.0);
 
            Random rnd = new Random();
 
            dist = Hypot(xe - xs, ye - ys);
 
            while (dist > 0.8)
            {
                wind = Math.Min(wind, dist * 0.8);
 
                if (dist >= targetArea)
                {
                    // Far from target
                    windX = windX / sqrt3 + (rnd.NextDouble() * wind * 2 - wind) / sqrt5;
                    windY = windY / sqrt3 + (rnd.NextDouble() * wind * 2 - wind) / sqrt5;
                }
                else
                {
                    // Close to target - smooth damping
                    windX = windX / sqrt2 * 0.75;
                    windY = windY / sqrt2 * 0.75;
 
                    if (maxStep < 4)
                        maxStep = 3.0 + rnd.NextDouble() * 2;
                    else
                        maxStep = maxStep / sqrt5 * 0.85;
                }
 
                // Gravity pull (weaker when very close)
                double pull = gravity * (dist > 1.0 ? 1.0 : dist);
                veloX += windX + pull * (xe - xs) / dist;
                veloY += windY + pull * (ye - ys) / dist;
 
                // Limit velocity
                double mag = Hypot(veloX, veloY);
                if (mag > maxStep)
                {
                    double stepSize = maxStep * 0.55 + rnd.NextDouble() * (maxStep * 0.45);
                    veloX = (veloX / mag) * stepSize;
                    veloY = (veloY / mag) * stepSize;
                }
 
                // Extra damping near target
                if (dist < targetArea * 0.6)
                {
                    veloX *= 0.88;
                    veloY *= 0.88;
                }
 
                oldX = (int)Math.Round(xs);
                oldY = (int)Math.Round(ys);
                xs += veloX;
                ys += veloY;
                dist = Hypot(xe - xs, ye - ys);
 
                newX = (int)Math.Round(xs);
                newY = (int)Math.Round(ys);
 
                if (oldX != newX || oldY != newY)
                    SetCursorPos(newX, newY);
 
                double step = Hypot(xs - oldX, ys - oldY);
                int wait = (int)Math.Round(waitDiff * (step / maxStep) + minWait);
                Thread.Sleep(Math.Max(1, wait));
            }
 
            // Gentle final settling (no hard snap)
            int finalX = (int)Math.Round(xe);
            int finalY = (int)Math.Round(ye);
 
            if (Math.Abs(newX - finalX) > 1 || Math.Abs(newY - finalY) > 1)
            {
                while (Math.Abs(newX - finalX) > 0 || Math.Abs(newY - finalY) > 0)
                {
                    int dx = Math.Sign(finalX - newX) * rnd.Next(1, 3);
                    int dy = Math.Sign(finalY - newY) * rnd.Next(1, 3);
 
                    newX = Math.Max(finalX - 3, Math.Min(finalX + 3, newX + dx));
                    newY = Math.Max(finalY - 3, Math.Min(finalY + 3, newY + dy));
 
                    SetCursorPos(newX, newY);
                    Thread.Sleep(rnd.Next(8, 18));
                }
            }
 
            SetCursorPos(finalX, finalY);
        }

        private static double Hypot(double dx, double dy)
        {
            return Math.Sqrt(dx * dx + dy * dy);
        }
 
        #endregion
        #region VKCODE to ASCII
        internal static class KeyboardUtils
        {
            // P/Invoke declarations
            [DllImport("user32.dll")]
            private static extern int ToAscii(uint uVirtKey, uint uScanCode, byte[] lpKeyState,
                [Out] StringBuilder lpChar, uint uFlags);

            [DllImport("user32.dll")]
            private static extern int GetKeyboardState(byte[] lpKeyState);

            [DllImport("user32.dll")]
            private static extern uint MapVirtualKey(uint uCode, uint uMapType);

            internal static string VkCodeToAscii(uint vkCode)
            {
                // Get the scan code for the virtual key
                uint scanCode = MapVirtualKey(vkCode, 0); // MAPVK_VK_TO_VSC
 
                // Get current keyboard state
                byte[] keyState = new byte[256];
                if (GetKeyboardState(keyState) == 0)
                    return string.Empty;
 
                // Adjust keyboard state based on your application's maintained state
                // Example: If Shift is "held" in your state, set VK_SHIFT (0x10)
                // keyState[0x10] = 0x80; // Uncomment to simulate Shift pressed
                // keyState[0x14] = 0x80; // Uncomment to simulate Caps Lock toggled
 
                // Buffer for output character
                StringBuilder charBuffer = new StringBuilder(2);
 
                // Call ToAscii to translate VK code to ASCII
                int result = ToAscii(vkCode, scanCode, keyState, charBuffer, 0);
 
                if (result == 1)
                {
                    // One character was written to the buffer
                    return charBuffer[0].ToString();
                }
                else if (result == 2)
                {
                    // Two characters (e.g., dead key combo); return first
                    return charBuffer[0].ToString();
                }
                else
                {
                    // No translation (e.g., VK_SCROLL, VK_LMENU) or error
                    return string.Empty;
                }
            }
        }
        #endregion VKCODE to ASCII
    }
}