do-click

Arguments: window-or-widget-or-nil &key (position (and window-or-widget-or-nil :center)) (mouse-button :left) (pre-expose t) (preview-seconds 0.5) (down-seconds 0.5)

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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.