Functions/GenXdev.Windows/Send-Key.ps1
|
<##############################################################################
Part of PowerShell module : GenXdev.Windows Original cmdlet filename : Send-Key.ps1 Original author : René Vaessen / GenXdev Version : 1.274.2025 ################################################################################ MIT License Copyright 2021-2025 GenXdev Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ################################################################################> ############################################################################### <# .SYNOPSIS Sends simulated keystrokes to a window or process. .DESCRIPTION This function sends keyboard input to a target window or process using the Windows Script Host Shell object. It can target windows by process name, process ID, or window handle. The function supports special key sequences, escape characters, and various timing options for reliable key delivery. .PARAMETER KeysToSend The keyboard input to send as an array of strings. Supports special key sequences like {ENTER}, {TAB}, {F1}, etc. Each string in the array is processed sequentially with optional delays between them. .PARAMETER SendKeyEscape When specified, escapes curly braces in the input text so they are sent as literal characters rather than interpreted as special key sequences. .PARAMETER ProcessName The name of the target process to send keys to. Supports wildcard patterns for flexible process matching. .PARAMETER ProcessId The process ID of the target process to send keys to. Provides precise targeting when multiple processes have similar names. .PARAMETER WindowHandle The window handle (HWND) of the target window to send keys to. Offers direct window targeting when the handle is known. .PARAMETER SendKeyHoldKeyboardFocus When specified, keeps keyboard focus on the target window after sending keys instead of returning focus to the PowerShell window. .PARAMETER SendKeyUseShiftEnter When specified, converts newline characters to Shift+Enter key sequences instead of regular Enter key sequences. .PARAMETER SendKeyDelayMilliSeconds The delay in milliseconds between sending different key sequences. Helps ensure reliable delivery when sending multiple key strings. .EXAMPLE Send-Key -KeysToSend "Hello World{ENTER}" -ProcessName "notepad" Sends text to Notepad followed by Enter key using process name targeting. .EXAMPLE Send-Key "Special {F11} key" -SendKeyEscape -ProcessId 1234 Sends literal "{F11}" text rather than F11 key using process ID targeting. .EXAMPLE sendkeys "Line 1{ENTER}Line 2" -WindowHandle 123456 -SendKeyDelayMilliSeconds 50 Sends multi-line text with custom delay using window handle targeting. #> function Send-Key { [CmdletBinding(DefaultParameterSetName = 'ByProcessName')] [Alias('sendkeys', 'invokekeys')] param ( ############################################################################### [Parameter( Position = 0, Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ValueFromRemainingArguments = $false, HelpMessage = 'The keyboard input to send as an array of strings' )] [string[]] $KeysToSend, ############################################################################### [Parameter( ParameterSetName = 'ByProcessName', Mandatory = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = 'Name of the process to send keys to (supports wildcards)' )] [ValidateNotNullOrEmpty()] [SupportsWildcards()] [string] $ProcessName, ############################################################################### [Parameter( ParameterSetName = 'ByProcessId', Mandatory = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = 'ID of the process to send keys to' )] [ValidateNotNull()] [Alias('Id', 'PID')] [int] $ProcessId, ############################################################################### [Parameter( ParameterSetName = 'ByWindowHandle', Mandatory = $false, ValueFromPipelineByPropertyName = $true, HelpMessage = 'Window handle to send keys to' )] [ValidateNotNull()] [Alias('Handle', 'hWnd')] [long] $WindowHandle, ############################################################################### [Parameter( Mandatory = $false, HelpMessage = 'Escape control characters and modifiers in input text' )] [Alias('Escape')] [switch] $SendKeyEscape, ############################################################################### [Parameter( Mandatory = $false, HelpMessage = 'Hold keyboard focus on target window after sending keys' )] [Alias('HoldKeyboardFocus')] [switch] $SendKeyHoldKeyboardFocus, ############################################################################### [Parameter( Mandatory = $false, HelpMessage = 'Use Shift+Enter instead of Enter for newlines' )] [Alias('UseShiftEnter')] [switch] $SendKeyUseShiftEnter, ############################################################################### [Parameter( Mandatory = $false, HelpMessage = 'Delay between different input strings in milliseconds' )] [ValidateRange(0, [int]::MaxValue)] [Alias('DelayMilliSeconds')] [int] $SendKeyDelayMilliSeconds = 10 ) begin { # initialize the windows script host shell object for sending keystrokes $helper = Microsoft.PowerShell.Utility\New-Object -ComObject WScript.Shell # initialize window variable for target window operations $window = $null; # attempt to locate the target window if targeting parameters are provided if ($null -eq $window) { try { # copy relevant parameters for get-window cmdlet invocation $invocationArguments = GenXdev.Helpers\Copy-IdenticalParamValues ` -FunctionName 'GenXdev.Windows\Get-Window' ` -BoundParameters $PSBoundParameters ` -DefaultValues (Microsoft.PowerShell.Utility\Get-Variable ` -Scope Local ` -ErrorAction SilentlyContinue) # check if any window targeting parameters were provided if ((-not [string]::IsNullOrWhiteSpace($ProcessName)) -or ` ($ProcessId -ne 0) -or ` ($WindowHandle -ne 0)) { # retrieve the first matching window for the specified criteria $window = GenXdev.Windows\Get-Window @invocationArguments ` -ErrorAction SilentlyContinue | Microsoft.PowerShell.Utility\Select-Object -First 1 } } catch { Microsoft.PowerShell.Utility\Write-Warning $_.Exception.Message } } # bring the target window to foreground if one was found if ($null -ne $window) { $null = $window.Focus() # allow time for window activation to complete Microsoft.PowerShell.Utility\Start-Sleep -Milliseconds 500 } } process { try { # iterate through each key sequence string to send foreach ($key in $KeysToSend) { Microsoft.PowerShell.Utility\Write-Verbose ` "Processing key sequence: $key" try { # join array elements into a single string for processing $escapedQuery = $key -join ' ' # escape curly braces if escape mode is enabled if ($SendKeyEscape) { $escapedQuery = $escapedQuery -replace '(\{)', '{{}' $escapedQuery = $escapedQuery -replace '(\})', '{}}' } # normalize line endings to consistent newline format $escapedQuery = $escapedQuery -replace '`r', '`n' $escapedQuery = $escapedQuery -replace '`n`n', '`n' # convert newlines to appropriate key sequences based on mode if ($SendKeyUseShiftEnter) { $escapedQuery = $escapedQuery -replace '`n', '+{ENTER}' } else { $escapedQuery = $escapedQuery -replace '`n', '{ENTER}' } Microsoft.PowerShell.Utility\Write-Verbose ` "Sending keys: $escapedQuery" if ($key -eq '^v') { Microsoft.PowerShell.Utility\Start-Sleep 2 } # send the processed key sequence to the target window $null = $helper.sendKeys($escapedQuery, $true) # apply delay between key sequences if specified if ($SendKeyDelayMilliSeconds -gt 0) { Microsoft.PowerShell.Utility\Start-Sleep ` -Milliseconds $SendKeyDelayMilliSeconds } if ($key -eq '^v') { Microsoft.PowerShell.Utility\Start-Sleep 2 } } catch { Microsoft.PowerShell.Utility\Write-Warning $_.Exception.Message } } } finally { # handle window focus restoration after key sending is complete if ($null -ne $window) { try { # restore powershell window focus unless holding focus was requested if (-not $SendKeyHoldKeyboardFocus) { try { Microsoft.PowerShell.Utility\Write-Verbose ` 'Restoring PowerShell window focus' GenXdev.Windows\Set-WindowPosition -SetForeground -FocusWindow } catch { Microsoft.PowerShell.Utility\Write-Warning ` $_.Exception.Message } } } catch { Microsoft.PowerShell.Utility\Write-Warning $_.Exception.Message } } } } end { } } ############################################################################### |