Keyboard and mouse input

Simulation of user input and support for system-wide hotkeys

SYNOPSIS

package require twapi_input

block_input

click_mouse_button BUTTON

get_input_idle_time

get_keyboard_layout_name

get_mouse_location

move_mouse XPOS YPOS ?-relative?

register_hotkey HOTKEY SCRIPT ?-append?

send_input INPUTLIST

send_input_text TEXT

send_keys KEYSEQUENCE

turn_mouse_wheel WHEELUNITS

unblock_input

unregister_hotkey HOTKEY_ID

DESCRIPTION

This package provides procedures related to user input on Windows platforms. The commands send_input, send_keys, send_input_text, move_mouse, click_mouse_button and turn_mouse_wheel can be used to simulate user input. The mouse position can be retrieved using get_mouse_location. The commands block_input and unblock_input can be used to prevent interference from real user input while simulating input.

The commands register_hotkey and unregister_hotkey can be used to register scripts to be invoked when the user presses a hotkey combination.

The amount of time elapsed since the last keyboard or mouse input event can be obtained through get_input_idle_time.

The name of the current keyboard layout can be retrieved with get_keyboard_layout_name.

Commands

block_input

This command blocks real physical input events and simulated events from threads other than the caller from being entered into the input queue. The command can be used to prevent interference when the commands such as send_input, send_input_text, click_mouse_button are used to simulate user input. The command unblock_input should be called to renable input.

The return value of block_input is 1 if the input was previously unblocked and 0 if the input was already blocked.

click_mouse_button BUTTON

Generates input to simulate clicking the specified mouse button. BUTTON may have one of the values left, right, middle, x1 or x2 to specify the button that was clicked.

get_input_idle_time

Returns the elapsed time in milliseconds since the last keyboard or mouse input event.

get_keyboard_layout_name

Returns the string identifier for the current keyboard layout.

get_mouse_location

Returns a pair of integers containing the mouse cursor's X and Y screen coordinates in pixels.

move_mouse XPOS YPOS ?-relative?

Generates input to simulate mouse movement. Movement is in absolute mouse coordinates unless the option -relative is specified. See description of send_input for more details.

register_hotkey HOTKEY SCRIPT ?-append?

Registers a script to be invoked when the user presses the hotkey specified by HOTKEY. Note that the script is invoked when the hotkey is pressed even if some other application had the input focus. If the caller had previously registered a script for the same hotkey, it is replaced by SCRIPT unless the -append option is specified. In this latter case, SCRIPT is added to the list of scripts. These are invoked in turn in the order they were registered. If any of the scripts returns an error or a return code value of 3 (break), subsequent scripts in the list are not invoked. Any errors are reported as background errors using the standard Tcl background error mechanism.

HOTKEY is a string describing the key combination and consists of 0-4 modifiers followed by the key code, all separated by the - character. A modifier may be one of ctrl (or control), alt (or menu), shift or win. The key code itself may be a single alphanumeric character, one of the virtual key names, such as F9, listed in send_keys (but without the surrounding braces), or the actual virtual key code itself. Examples are ctrl-alt-a, shift-f9 and ctrl-alt-65.

The command returns an identifier corresponding to the specified hotkey registration. It should be deregistered when no longer needed by calling the unregister_hotkey function.

send_input INPUTLIST

Simulates user input by generating keyboard and mouse events based on INPUTLIST. This must be in the form of a list of sublists, each sublist being a keyboard or mouse input event specification.

A keyboard input specification takes the form

"KEYTYPE VK SCANCODE ?keyopts?".

KEYTYPE may have one of the following values:

key	Specifies a virtual key being pressed and released. This is a more convenient form of specifying consecutive keydown, keyup events. VK should be an integer in the range 1-254 and specifies the virtual key. SCANCODE specifies a hardware scancode for the key. If -usescan is specified in keyopts, the specified scan code is used and VK will be ignored by the system. If -extended is specified in keyopts, the key is treated as an extended key with the scan code being preceded by a byte that has value 0xE0.
keydown	Specifies a virtual key being pressed. VK should be an integer in the range 1-254 and specifies the virtual key. SCANCODE specifies a hardware scancode for the key. keyopts may have the same values as specified for vkey.
keyup	Specifies a virtual key being released. VK should be an integer in the range 1-254 and specifies the virtual key. SCANCODE specifies a hardware scancode for the key. keyopts may have the same values as specified for vkey.
unicode	Specifies a unicode character. SCANCODE should contain the integer corresponding to the unicode character. VK and any keyopts are ignored if specified.

For more detailed information, refer the the documentation of the KEYBDINPUT structure in the Windows SDK.

send_input should generally be used only for the most low level input sequences involving both keyboard and mouse input. The commands send_input_text and send_keys provide more convenient alternatives for sending pure text and a combination of text and special keys respectively.

A mouse input specification takes the form

"mouse XPOS YPOS ?mouseopts?".

Arguments XPOS and YPOS specify the position of the mouse in absolute (default) or relative coordinates. In the former case, the values range from 0 to 65535 and are in mouse coordinates. In the latter case, the values are in pixels. Note when relative mode is used, the system will take into account the mouse speed and acceleration settings. The command move_mouse is much simpler to use unless you have a need to send complex mouse input sequences.

mouseopts may contain one or more of the following options:

-relative	Indicates that XPOS and YPOS should be treated as relative to the last reported position, and not as absolute coordinates.
-ldown	Indicates that the left mouse button has been pressed since the last reported event.
-lup	Indicates that the left mouse button has been released since the last reported event.
-rdown	Indicates that the right mouse button has been pressed since the last reported event.
-rup	Indicates that the right mouse button has been released since the last reported event.
-mdown	Indicates that the middle mouse button has been pressed since the last reported event.
-mup	Indicates that the middle mouse button has been released since the last reported event.
-x1down	Indicates that the first X button has been pressed since the last reported event.
-x1up	Indicates that the first X button has been released since the last reported event.
-x2down	Indicates that the second X button has been pressed since the last reported event.
-x2up	Indicates that the second X button has been released since the last reported event.
-moved	Indicates that the mouse has moved since the last reported event.
-wheel WHEELUNITS	Indicates that the mouse wheel was rotated by WHEELUNITS. This may be a positive integer for forward rotation, or a negative integer for backward rotation. This option may not be used with any of the X button options.

For more detailed information, refer the the documentation of the MOUSEINPUT structure in the Windows SDK.

The commands move_mouse, click_mouse_button and turn_mouse_wheel may be more convenient for common cases.

send_input_text TEXT

Simulates user input by generating keyboard events corresponding to TEXT.

send_keys KEYSEQUENCE

Simulates user input of keyboard events. This function differs from send_input_text in that the keys generated may include non-text keys such as function keys, modifier keys etc.. KEYSEQUENCE indicates the keys to be generated and is specified with the syntax defined below. This syntax is a superset of the syntax used by the Visual Basic SendKeys command.

All characters in KEYSEQUENCE result in the corresponding keystroke being generated except for the following characters which have a special meaning:

The ~ character stands for the ENTER key.

The +, ^ and % characters are used as key modifiers for the following character or character groups. The + character is used to indicate the following character should be entered as though the SHIFT key was pressed while entering the character. Similarly, ^ and % indicate the CTRL and ALT modifiers respectively. For example, the sequence +ab will result in the following key stroke sequence being generated: SHIFT is pressed and held down, the a key is pressed and released, the SHIFT key is released, and finally the b key is pressed and released.

The ( and ) characters are used to group a set of characters together. This is used for applying a key modifier to a sequence of characters. For example, the sequence +(abc) will result in the following key stroke sequence being generated: SHIFT is pressed and held down and then the keys a, b and c are pressed and released before the SHIFT key is released.

The { and } keys are used to indicate special keys such as function keys and to enter the special characters such as +. Thus, {+} will result in the key + being pressed and released. Similarly, {(} and {}} indicate the character ( and } being entered. As a special case, the form {C N} results in the character C being entered N times. Note that the character may be any character, not just a special character that needs to be escaped.

The other use of the braced escape sequence is to enter special keys. These special sequences and the corresponding generated keystrokes are:

{BACKSPACE}	Backspace
{BACK}	(same as {BACKSPACE})
{BS}	(same as {BACKSPACE})
{BKSP}	(same as {BACKSPACE})
{TAB}	Tab
{CLEAR}
{ENTER}	Enter key on the main keyboard
{RETURN}	(same as {ENTER})
{SHIFT}	Shift (see note below on difference between this and use of the + modifier).
{CONTROL}	Shift (see note below on difference between this and use of the ^ modifier).
{ALT}	Shift (see note below on difference between this and use of the % modifier).
{MENU}	(same as {ALT})
{PAUSE}	Pause
{BREAK}	Break
{CAPSLOCK}	Caps Lock
{CAPITAL}	(same as {CAPSLOCK})
{KANA}
{HANGEUL}
{HANGUL}
{JUNJA}
{FINAL}
{HANJA}
{KANJI}
{ESCAPE}	Escape
{ESC}	(same as {ESCAPE})
{CONVERT}
{NONCONVERT}
{ACCEPT}
{MODECHANGE}
{SPACE}	Spacebar
{PGUP}	Page Up
{PRIOR}	(same as {PGUP})
{PGDN}	Page Down
{NEXT}	(same as {PGDN})
{END}	End
{HOME}	Home
{LEFT}	Left arrow
{UP}	Up arrow
{RIGHT}	Right arrow
{DOWN}	Down arrow
{SELECT}
{PRTSC}	Print Screen key
{PRINT}	Print key
{EXECUTE}
{SNAPSHOT}
{INSERT}	Insert
{INS}	(same as {INSERT})
{DELETE}	Delete
{DEL}	(same as {DELETE})
{HELP}	Help
{LWIN}	Left Windows key
{RWIN}	Right Windows key
{APPS}
{SLEEP}
{NUMPAD0}	Numeric keypad 0
{NUMPAD1}	Numeric keypad 1
{NUMPAD2}	Numeric keypad 2
{NUMPAD3}	Numeric keypad 3
{NUMPAD4}	Numeric keypad 4
{NUMPAD5}	Numeric keypad 5
{NUMPAD6}	Numeric keypad 6
{NUMPAD7}	Numeric keypad 7
{NUMPAD8}	Numeric keypad 8
{NUMPAD9}	Numeric keypad 9
{MULTIPLY}	Numeric keypad *
{ADD}	Numeric keypad +
{SEPARATOR}
{SUBTRACT}	Numeric keypad -
{DECIMAL}	Numeric keypad .
{DIVIDE}	Numeric keypad /
{F1}	Function key F1
{F2}	Function key F2
{F3}	Function key F3
{F4}	Function key F4
{F5}	Function key F5
{F6}	Function key F6
{F7}	Function key F7
{F8}	Function key F8
{F9}	Function key F9
{F10}	Function key F10
{F11}	Function key F11
{F12}	Function key F12
{F13}	Function key F13
{F14}	Function key F14
{F15}	Function key F15
{F16}	Function key F16
{F17}	Function key F17
{F18}	Function key F18
{F19}	Function key F19
{F20}	Function key F20
{F21}	Function key F21
{F22}	Function key F22
{F23}	Function key F23
{F24}	Function key F24
{NUMLOCK}	Numlock
{SCROLL}	Scroll lock
{SCROLLLOCK}	Scroll lock
{LSHIFT}	Left Shift
{RSHIFT}	Right Shift
{LCONTROL}	Left Control
{RCONTROL}	Right Control
{LALT}	Left Alt
{LMENU}	(same as {LALT})
{RALT}	Right Alt
{RMENU}	(same as {RALT})
{BROWSER_BACK}	Back
{BROWSER_FORWARD}	Forward
{BROWSER_REFRESH}
{BROWSER_STOP}	Stop
{BROWSER_SEARCH}	Search
{BROWSER_FAVORITES}	Favorites
{BROWSER_HOME}	Web Home
{VOLUME_MUTE}
{VOLUME_DOWN}
{VOLUME_UP}
{MEDIA_NEXT_TRACK}
{MEDIA_PREV_TRACK}
{MEDIA_STOP}
{MEDIA_PLAY_PAUSE}
{LAUNCH_MAIL}
{LAUNCH_MEDIA_SELECT}
{LAUNCH_APP1}
{LAUNCH_APP2}

Note that use of the braced sequences for the modifier keys such as SHIFT is not the same as the corresponding special characters. For example, the string {SHIFT}a results in the key sequence where the SHIFT key is pressed and released before the a key is pressed. The string +a on the other hand results in a key sequence where the SHIFT key is released after the a is pressed and released.

turn_mouse_wheel WHEELUNITS

Generates input to simulate turning the wheel. A positive value of WHEELUNITS simulates forward rotation by the specified number of units, a negative value simulates backward rotation.

unblock_input

This command reverses the effect of a previous call to block_input.

The return value of unblock_input is 1 if the input was previously blocked and 0 if the input was already unblocked.

unregister_hotkey HOTKEY_ID

Unregisters a hot key that was previously registered. HOTKEY_ID should be a hotkey identifer returned by a previous call to register_hotkey. All scripts associated with the hotkey are unregistered.

COPYRIGHT

Copyright © 2003, 2004, Ashok P. Nadkarni