Home > Language Reference > Wait Functions > Wait for Image

Wait for Image

The Pause until bitmap pauses script execution until the specified image/bitmap is displayed in the specified window. If after the specified timeout, the pause condition is not met, the block of statements following PauseFalse keyword is executed.

 Video: How to use Image Synchronization

Usage

Used to wait for an update in the application when no new window or new text tells that the update has been done. For example, in a Windows application, only a new icon tells that the new screen is there, and so you could use Pause until bitmap is there to detect the new icon. Use Recording mode or Insert/Synchronization on Image menu to generate easily such a Pause.

Syntax

Pause [x secs|x ticks] until
    Bitmap(<filename>)
    InWindow(<window_name>,<instance>)
    [InArea(<x>,<y>,<height>,<width>)]
[PauseOK|PauseTrue]
 'If the condition is met, the optional statements after the PauseOK and before the PauseFalse are executed
[PauseFalse]
' After the specified timeout, if the condition is not met, the statements after the PauseFalse are executed
     MsgBox("Pause at line "+ #ErrorLine$ +" has failed !",16,"Runtime error")
     End
EndPause

Parameters

[x secs|x ticks], optional. If the pause condition is not met after x seconds or x ticks (a tick is around 1/100 sec), the statements after the PauseFalse keyword are executed. If not specified, the default timeout is the one as defined by #PauseTimeout system variable (default value: 120 seconds). mins can be used instead of secs for a timeout in minutes. If ticks unit is used, the search is made continuously, see Remarks below. 

Bitmap, keyword, specifies the <filename> which contains the bmp file to wait for.

InWindow, keyword. It specifies the <window_name> of the window where to search the bitmap (and its <instance> number) . 

InArea, optional keyword. It specifies the area as defined by coordinates <x>,<y>,<height>,<width> where to look for the bitmap . If not specified, the bitmap is searched in the whole <window_name>.

Remarks

Pause TextOCR compared to Pause Bitmap : both addresses the case where the text displayed within the window cannot be recognized as pure text. We explain here the advantages and drawbacks of each Pause. A pause TextOCR captures the defined area, submits the image to the OCR engine and the Pause triggers if the OCRerized text is seen - then if the text is not seen, the Pause waits around 1 sec before starting again the recognition attempt. So the main drawback of the Pause TextOCR is that it takes a while, the OCR engine can take up to 3-4 secs. There are 3 advantages compared to a Pause bitmap : no extra file for the captured image, a more readable Pause block as the text is seen in the script and the Pause will work even when you distribute the script on other PCs as the bitmap capture is done at execution.
Pause bitmap at execution captures the defined area and compares it to the specified bmp file. If ticks unit is used in the Pause bitmap, as soon as TaskExec sees that it does not trigger, it captures again and compares again, and so on. So with ticks unit, the Pause bitmap can take up to 100% of CPU but will be very fast to execute. If secs unit is used, when the image is not found, the Pause bitmap waits around 1 sec before starting again to capture the defined area. So whatever ticks or secs unit used, a Pause Bitmap will be always faster than a Pause TextOCR.

The system variable #BitmapPrecision specifies how closely the found image must match the input image. The default value of 100 means exact match.

See also

Wait for a Date
Wait for a Keystroke
Wait for a Menu Selection
Wait for a Mouse Click
Wait for OCR Text
Wait for a Text
Wait for a Time Delay
Wait for a Window

Examples

'Syntax example
Pause 10 secs until
   Bitmap("C:\Program Files (x86)\WinTask\Scripts\test.bmp")
   InWindow("IEXPLORE.EXE|Internet Explorer_Server||1",1)
   InArea( 818, 340, 35, 204 )
PauseFalse
   MsgBox("'Wait for' at line " + #ErrorLine$ + " has failed !")
   End
EndPause

'This more complex example shows how to use a pause_on_two_bmp Function to wait until one of the two specified bmp appears.
Function pause_on_two_bmp(win1$,bmp1$,win2$,bmp2$)
'win1$, window name where to search the first bitmap bmp1$
''win2$, window name where to search the second bitmap bmp2$
local sortie, ret, t
repeat
    Pause 1 until
        Bitmap(bmp1$)
        InWindow(win1$)
    PauseOk
        ret=1
    EndPause

    pause 1 until
        Bitmap(bmp2$)
        InWindow(win2$)
    PauseOk
        ret=2
    EndPause
    if ret=0 then
        t=t+1
    endif
until ret<>0 or t > #PauseTimeout
pause_on_two_bmp_bmp=ret
Endfunction
 
'Call example
win1$="AD-AWARE.EXE|TACimage|Ad-Aware SE Personal|16"
win2$="AD-AWARE.EXE|TACimage|Ad-Aware SE Personal|16"
bmp1$="C:\Program Files (x86)\WinTask\Scripts\aaw_next.bmp"
bmp2$="C:\Program Files (x86)\WinTask\Scripts\aaw_finish.bmp"
 
'Maximum timeout before pause on the 2 bmp fails.
#PauseTimeout=400
 
pause_on_two_bmp(win1$,bmp1$,win2$,bmp2$)
If pause_on_two_bmp=0 then
    msgbox("None of the two specified bmp has been found")
    End
Endif