do-keypress

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-2012, Franz Inc. Oakland, CA., USA. All rights reserved.Documentation for Allegro CL version 9.0. This page was not revised from the 8.2 page.Created 2012.5.30.