ControlClick

Sends a mouse button or mouse wheel event to a control.

ControlClick , Control-or-Pos, WinTitle, WinText, WhichButton, ClickCount, Options, ExcludeTitle, ExcludeText

Parameters

Control-or-Pos

If blank or omitted, the target window's topmost control will be clicked (or the target window itself if it has no controls). Otherwise, use one of the following modes.

Mode 1 (Position): Specify the X and Y coordinates relative to the target window's upper left corner. The X coordinate must precede the Y coordinate and there must be at least one space or tab between them. For example: X55 Y33. If there is a control at the specified coordinates, it will be sent the click-event at those exact coordinates. If there is no control, the target window itself will be sent the event (which might have no effect depending on the nature of the window).

Note: In mode 1, the X and Y option letters of the Options parameter are ignored.

Mode 2 (ClassNN or Text): Specify either ClassNN (the classname and instance number of the control) or the name/text of the control, both of which can be determined via Window Spy. When using name/text, the matching behavior is determined by SetTitleMatchMode.

By default, mode 2 takes precedence over mode 1. For example, in the unlikely event that there is a control whose text or ClassNN has the format "Xnnn Ynnn", it would be acted upon by mode 2. To override this and use mode 1 unconditionally, specify the word Pos in Options as in the following example: ControlClick, x255 y152, WinTitle,,,, Pos.

To operate upon a control's HWND (window handle), leave this parameter blank and specify ahk_id %ControlHwnd% for the WinTitle parameter (this also works on hidden controls even when DetectHiddenWindows is Off). The HWND of a control is typically retrieved via ControlGet Hwnd, MouseGetPos, or DllCall().

WinTitle, WinText, ExcludeTitle, ExcludeText

If each of these is blank or omitted, the Last Found Window will be used. Otherwise, specify for WinTitle a window title or other criteria to identify the target window and/or for WinText a substring from a single text element of the target window (as revealed by the included Window Spy utility).

ExcludeTitle and ExcludeText can be used to exclude one or more windows by their title or text. Their specification is similar to WinTitle and WinText, except that ExcludeTitle does not recognize any criteria other than the window title.

Window titles and text are case-sensitive. By default, hidden windows are not detected and hidden text elements are detected, unless changed with DetectHiddenWindows and DetectHiddenText. By default, a window title must start with the specified WinTitle or ExcludeTitle to be a match, unless changed with SetTitleMatchMode.

WhichButton

If blank or omitted, it defaults to Left (the left mouse button). Otherwise, specify the button to click or the rotate/push direction of the mouse wheel.

Button: Left, Right, Middle (or just the first letter of each of these); or X1 (fourth button) or X2 (fifth button).

Mouse wheel: Specify WheelUp or WU to turn the wheel upward (away from you); specify WheelDown or WD to turn the wheel downward (toward you). [v1.0.48+]: Specify WheelLeft (or WL) or WheelRight (or WR) to push the wheel left or right, respectively (but these have no effect on operating systems older than Windows Vista). ClickCount is the number of notches to turn the wheel.

ClickCount

If blank or omitted, it defaults to 1. Otherwise, specify the number of times to click the mouse button or turn the mouse wheel, which can be an expression.

Options

If blank or omitted, each click consists of a down-event followed by an up-event, and occurs at the center of the control when mode 2 is in effect. Otherwise, specify a series of one or more of the following options. For example: d x50 y25.

NA [v1.0.45+]: May improve reliability. See reliability below.

D: Press the mouse button down but do not release it (i.e. generate a down-event). If both the D and U options are absent, a complete click (down and up) will be sent.

U: Release the mouse button (i.e. generate an up-event). This option should not be present if the D option is already present (and vice versa).

Pos: Specify the word Pos anywhere in Options to unconditionally use the X/Y positioning mode as described in the Control-or-Pos parameter above.

Xn: Specify for n the X position to click at, relative to the control's upper left corner. If unspecified, the click will occur at the horizontal-center of the control.

Yn: Specify for n the Y position to click at, relative to the control's upper left corner. If unspecified, the click will occur at the vertical-center of the control.

Use decimal (not hexadecimal) numbers for the X and Y options.

Error Handling

[v1.1.04+]: This command is able to throw an exception on failure. For more information, see Runtime Errors.

ErrorLevel is set to 1 if there was a problem or 0 otherwise.

Reliability

To improve reliability -- especially during times when the user is physically moving the mouse during the ControlClick -- one or both of the following may help:

1) Use SetControlDelay -1 prior to ControlClick. This avoids holding the mouse button down during the click, which in turn reduces interference from the user's physical movement of the mouse.

2) Specify the string NA anywhere in the sixth parameter (Options) as shown below:

SetControlDelay -1
ControlClick, Toolbar321, WinTitle,,,, NA

The NA option avoids marking the target window as active and avoids merging its input processing with that of the script, which may prevent physical movement of the mouse from interfering (but usually only when the target window is not active). However, this method might not work for all types of windows and controls.

Remarks

Not all applications obey a ClickCount higher than 1 for turning the mouse wheel. For those applications, use a loop to turn the wheel more than one notch as in this example, which turns it 5 notches:

Loop, 5
    ControlClick, Control, WinTitle, WinText, WheelUp

SetControlDelay, Control, ControlGet, ControlGetText, ControlMove, ControlGetPos, ControlFocus, ControlSetText, ControlSend, Click

Examples

Clicks the OK button.

ControlClick, OK, Some Window Title

Clicks at a set of coordinates. Note the lack of a comma between X and Y.

ControlClick, x55 y77, Some Window Title

Clicks in NA mode at coordinates that are relative to a named control.

SetControlDelay -1  ; May improve reliability and reduce side effects.
ControlClick, Toolbar321, Some Window Title,,,, NA x192 y10