Home > Language Reference > UI Automation Functions > ClickUIA

ClickUIA

The ClickUIA function waits until the specified uia element is ready and clicks it.

Usage

The ClickUIA function clicks the element specified by its UIA descriptor and so will replay correctly even if the element has been moved within the window. ClickUIA waits for a maximum of #ActionTimeout (the default value is 30 seconds) that the element to click is ready for receiving the click and executes the click as soon as the element is seen ready. You can specify a "right" parameter to right-click an element. You can add mouse coordinates to ClickUIA to make the function click at a point near the specified element.

Video: How to generate the WinTask x64 UIA descriptor for clicking any element on the desktop using ClickUIA function.

Syntax

ret=ClickUIA(<uia_descriptor> [, left|right|double [, <x>,<y>]])

Parameters

<uia_descriptor>, string, UIA descriptor of the UI element to click within the desktop. Use Spy to find the UIA descriptor of the UI element.

left|right|double, optional keyword, left-click or right-click or double-click. The default is left-click.

<x>,<y>,
optional integers, x, y coordinates relative to the specified element. It is used to click near the element.

Return value

Ret, optional numeric return code. If the specified UI element has been successfully clicked within 30 seconds (this default value can be changed using #ActionTimeout), the function returns 0. If the function fails, the return value is a nonzero value (see UI Automation Functions Error Codes).

Remarks

At replay, the function waits for the specified UI element to be loaded before clicking it. The timeout is the value of #ActionTimeout, so 30 secs by default.

The UIA descriptor identifies uniquely an UI element displayed within the whole desktop. So no UseWindow is needed and the synchronization is made within the ClickUIA function algorithm. 

ClickUIA can click only a visible element. If the element to click is not visible within an arborescence, you need first to click the scrollbar to make the element visible before executing ClickUIA.

At times you may come across an error message generated by a WinTask x64 function that failed because a preceding ClickUIA function did not execute correctly. As you watch the script execute, you see the mouse cursor click somewhere within the window, but not on the intended element. One possible cause for this error is that the script was attempting to click a small element but the default mouse click coordinates are inaccurate, for example the click is done too much on the left of a button. The solution is to use the optional parameters of the ClickUIA function to pinpoint the mouse click coordinates.
Click slightly to the right and down from the top-left corner of the UIA element:
ClickUIAElement("[APP='iexplore.exe',CLASS='DirectUIHWND'][NAME='Save',ROLE='split button']",left,5,5)

See also

How to use UI Automation functions
GetUIAProperty
SelectUIAItem
WriteUIA

Examples

'Download a file from our demo web site
StartBrowser("IE", "www.wintask.com/demos", 3)
UsePage("WinTask Demonstration Pages")
 ClickHTMLElement("A[INNERTEXT= 'File']")
'Click the Save button in the small Download window at the bottom of the IE window
ClickUIA("[APP='iexplore.exe',CLASS='DirectUIHWND'][NAME='Save',ROLE='split button']")

'Download a file from our demo site and save it under a new name
StartBrowser("IE", "www.wintask.com/demos", 3)
UsePage("WinTask Demonstration Pages")
 ClickHTMLElement("A[INNERTEXT= 'File']")
'Click the arrow at the right of the Save button in the small Download window, in order to open the context menu
ClickUIA("[APP='iexplore.exe',CLASS='DirectUIHWND'][NAME='Save',ROLE='split button'][ROLE='split button']")
'Click Save As option in the opened context menu
ClickUIA("[APP='iexplore.exe'][NAME='Save as',ROLE='menu item']")
'The standard Save As window appears, a UseWindow is needed to wait until the window is displayed