do-click

This generic function programmatically emulates clicking a mouse
button, after optionally exposing a window and/or moving the mouse
cursor over it. This may be useful for automated testing.

window-or-widget-or-nil may be either a window, a
dialog-item, or nil. If this argument is
non-nil and pre-expose
is true, then the specified window or widget and all of its ancestor
windows are selected so that the window or widget is in front to
receive the mouse click. The position argument
will also be relative to this window or widget.

The keyword arguments are:

position: may be a position, or the special
keyword :center, or nil.
If non-nil, then the mouse cursor is moved to
the indicated position before the mouse click is done. If
window-or-widget-or-nil is non-nil, then the position is in that object's stream
coordinates, and otherwise it is a screen position. The special
:center value indicates the center of that object's
client area. The default value is :center if
window-or-widget-or-nil is non-nil, and nil otherwise.

Note that the mouse cursor is left at the specified position. If you
would like to return the mouse cursor to where it was previously, then
you should first call cursor-position or ncursor-position and save
the current position, then call do-click, and finally call (setf cursor-position) to
return the mouse cursor to its original position.

mouse-button: may be either
:left, :middle, or
:right to indicate which mouse button is to be
clicked. The default is :left.

pre-expose: if this argument is true and
window-or-widget-or-nil is non-nil, then that window or widget and all its ancestor
windows are selected before the click is done, so that it is in front
to receive the click. The default is t.

preview-seconds may be either a non-negative
number indicating the number of seconds to sleep before pressing the
mouse button, 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 mouse
button down but before releasing it, or nil
to not sleep at all. The default is 0.5.

Examples

;; Left-click at the center of a window's scrollable page.
(do-click some-window)
;; Left-click near the upper-right corner of its scrollable page.
(do-click some-window
:position (make-position (- (interior-width some-window) 8)
12))
;; Left-click it with no pause for people to watch the action.
(do-click some-window :preview-seconds nil :down-seconds nil)
;; Right-click in the center of a window's scrollable page.
(do-click some-window :button :right)
;; Left-click whatever is under the mouse.
(do-click nil)
;; Left-click an arbitary position on the screen.
(do-click nil :position (make-position 100 200))
;; Left-click over the center of a window, but without
;; first exposing it. So if another window covers it, then the
;; click will go to that window instead. Pre-expose defaults to
;; t to ensure that the click goes to the specified window, but
;; it may be useful to pass it as nil as in this example if you
;; are testing that the window is exposed when it should be.
(do-click some-window :pre-expose nil)

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 8.2. This page was not revised from the 8.1 page.Created 2010.1.21.