do-keypress

Arguments: window-or-widget-or-handle-or-nil keynum-or-character &key (preview-seconds 0.5) (down-seconds 0.5) shift control alt (down t) (up t)

This generic function programmatically emulates pressing and/or releasing a key on the keyboard, after optionally exposing a window and giving it the keyboard focus. This may be useful for automated testing.

The two required arguments window-or-widget-or-handle-or-nil and keynum-or-character.

window-or-widget-or-handle-or-nil may be either a window, a dialog-item, an internal window "handle", or nil. If non-nil, then the specified window or widget and all of its ancestor windows are brought to front, and the window is given the keyboard focus before the keypress is done, so that the specified window will receive it. (If a handle of a window in another application is specified, then it is not possible to give it the keyboard focus programmatically, though do-click can work for that.)

keynum-or-character indicates which key to press and/or release. It may be either the value of one of the "vk-" key constants (see key-names) or the character that appears on one of the alphanumeric keys. If an uppercase character is passed, then a shift is done as if shift were true.

The keyword arguments are:

• preview-seconds: may be either a non-negative number indicating the number of seconds to sleep before pressing the key down, or nil to not sleep at all. The default is 0.5.
• down-seconds may be either a non-negative number indicating the number of seconds to sleep after pressing the key down but before releasing it, or nil to not sleep at all. The default is 0.5.
• shift, control, and alt: if shift is true, then the shift key is pressed before pressing and/or releasing the main key, and released after pressing and/or releasing the main key. control and alt work similarly for the control and alt keys.
• down and up: If down argument is true, then the key is pressed down. If up is true, then the key is released. If both are true, the key is first pressed and then released. Both are true by default. It would not be useful to pass both as nil.

Examples

;; Type a "j" to a window.
(do-keypress some-window #\j)

;; Type a semicolon to whatever window has the keyboard focus.
(do-keypress nil vk-semicolon)

;; Press down the shift key without releasing it.
;; WARNING:  Doing this without a subsequent
;; up-click of the same key leaves the OS thinking
;; that the shift key is still down, and a further keystroke
;; will believe it is shifted.  This can be fixed interactively
;; by simply pressing and releasing the left shift key.
(do-keypress some-window vk-shift :up nil)

;; Type control-j into a window.
(do-keypress some-window #\j :control t)

GTK Note

This function is not implemented on GTK, and we doubt that there is any feasible way to implement it. The function does not exist at all on the GTK platform, so you should use #+mswindows to conditionalize any calls to it.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.