waitForImage

ScreenRectangle waitForImage(imageFile, [parameterMap], [searchRegion])

This function waits for an image as specified by imageFile to appear on the screen, by repeatedly calling ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]) until a timeout is reached. In case of success, the location of the image as found on the screen will be returned as a ScreenRectangle. Interaction functions like mouseClick(screenPoint, modifierState, button), doubleClick(screenPoint, modifierState, button) or tapObject(screenPoint, modifierState) can be used to click or tap on the detected location.

If a directory is passed for imageFile, it is treated as an Image Group.

The behavior of the search can be customized through additional parameters passed to the optional parameterMap of key-value pairs, where a key can be one of these:

• interval - Number of milliseconds to wait in between image search retries. The default is 1000 (1 second).
• timeout - Amount of time in milliseconds to search for an image before reporting that the image is not found. The default is 20000 (20 seconds).
• occurrence - The occurrence index. By default the first match (with index 1) will be returned. Index values 2 and higher will select consecutive matches as far as available.
• tolerant - Boolean switch that enables tolerant image search mode. In this mode some differences between the template image and the desktop screenshot are allowed. The default value is the value of testSettings.imageSearchTolerant property. The comparison algorithm used is Correlation.
• threshold - Threshold on the correlation between template image and a desktop screenshot, expressed as a percentage. A correlation higher than the threshold is considered a match against the template image. Usable values for this parameter usually fall between 99.0 and 100.0. The default value is the value of the testSettings.imageSearchThreshold property. This parameter is ignored if the tolerant parameter is set to false.
• multiscale - Boolean switch that enables scaled image search mode. In this mode the template image is expanded into a series of images of different sizes. Those image are subsequently used as template images for the image search. The default value is the value of the testSettings.imageSearchMultiscale property. This parameter is ignored if the tolerant parameter is set to false.
• minScale - Lower bound on the template image series sizes, expressed as a percentage. The resized template image sizes will span between minScale and maxScale of the original image size. The default value is the value of the testSettings.imageSearchMinScale property. This parameter is ignored if either the tolerant or the multiscale parameters are set to false.
• maxScale Upper bound on the template image series sizes, expressed as a percentage. The resized template image sizes will span between minScale and maxScale of the original image size. The default value is the value of the testSettings.imageSearchMaxScale property. This parameter is ignored if either the tolerant or the multiscale parameters are set to false.

# Click on icon.png
mouseClick(waitForImage("icon.png"))

// Click on icon.png
mouseClick(waitForImage("icon.png"));

# Click on icon.png
mouseClick(waitForImage("icon.png"));

# Click on icon.png
mouseClick(waitForImage("icon.png"))

# Click on icon.png
invoke mouseClick [waitForImage "icon.png"]

By default this function will repeatedly grab the screen content until successful or until 20 seconds have passed. Longer (or shorter) waiting periods can be set in milliseconds via a timeout value passed through the parameterMap. In order to perform a single image search, use the ScreenRectangle findImage(imageFile, [parameterMap], [searchRegion]) function.

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence": 2, "timeout": 10000})

// Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {occurrence: 2, timeout: 10000}));

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence" => 2, "timeout" => 10000}));

# Click on second icon.png, wait maximum 10 seconds
mouseClick(waitForImage("icon.png", {"occurrence" => 2, "timeout" => 10000}))

# Click on second icon.png, wait maximum 10 seconds
invoke mouseClick [waitForImage "icon.png" {occurrence 2 timeout 10000}]

The matching algorithm performs a pixel-by-pixel color value comparison. The screen content and sub-image content therefore have to match 100% unless the tolerant search mode is enabled.

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {'tolerant': True,
                                     'threshold': 99.7,
                                     'multiscale': True,
                                     'minScale': 100.0,
                                     'maxScale': 150.0})

// Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {tolerant: true,
                                     threshold: 99.7,
                                     multiscale: true,
                                     minScale: 100.0,
                                     maxScale: 150.0}));

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {tolerant => true,
                                     threshold => 99.7,
                                     multiscale => true,
                                     minScale => 100.0,
                                     maxScale => 150.0}));

# Click on icon.png, found with tolerance of 99.7
mouseClick(waitForImage("icon.png", {"tolerant" => true,
                                     "threshold" => 99.7,
                                     "multiscale" => true,
                                     "minScale" => 100.0,
                                     "maxScale" => 150.0}))

# Click on icon.png, found with tolerance of 99.7
invoke mouseClick [waitForImage "icon.png" {tolerant true \
                                            threshold 99.7 \
                                            multiscale true \
                                            minScale 100.0 \
                                            maxScale 150.0}]

In case a searchRegion is specified as the last argument, the search is performed only within the area corresponding to it. The search region can be an AUT object, a ScreenRectangle object or an array of such objects. It can also be a special string value "all", in which case all top-level objects are used.

The searchRegion can also be an Image Object object. In such case no new screenshots are taken and the specified image is used instead. Currently it is not possible to limit the search scope to a portion of an Image object; please use the Image.copy() to cut the relevant section. Since the Image object specified as the search region cannot possibly change overtime, this function will not perform the image search repetitively and will return the results immediately.

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) )

# Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] )

# Find icon.png on the left half of the MyWidget object
bounds = object.globalBounds( waitForObject( names.MyWidget ) )
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds )

# Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) )

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" )

// Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) );

// Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] );

// Find icon.png on the left half of the MyWidget object
var bounds = object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds );

// Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes.ScreenRectangle( 100, 100, 200, 300 ) );

// Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" );

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names::MyWidget ) );

# Find icon.png on multiple objects
waitForImage("icon.png", {}, ( waitForObject( names::MyWidget ),
                               waitForObject( names::MyOtherWidget ) ) );

# Find icon.png on the left half of the MyWidget object
my $bounds = object::globalBounds( waitForObject( names::MyWidget ) );
$bounds->width = $bounds->width / 2;
waitForImage("icon.png", {}, bounds );

# Find icon.png in the specified area
waitForImage("icon.png", {}, new UiTypes::ScreenRectangle( 100, 100, 200, 300 ) );

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" )

# Find icon.png on the MyWidget object
waitForImage("icon.png", {}, waitForObject( names.MyWidget ) );

# Find icon.png on multiple objects
waitForImage("icon.png", {}, [ waitForObject( names.MyWidget ),
                               waitForObject( names.MyOtherWidget ) ] );

# Find icon.png on the left half of the MyWidget object
bounds = Squish::Object.globalBounds( waitForObject( names.MyWidget ) );
bounds.width = bounds.width / 2
waitForImage("icon.png", {}, bounds );

# Find icon.png in the specified area
waitForImage("icon.png", {}, UiTypes::ScreenRectangle.new( 100, 100, 200, 300 ) );

# Find icon.png on all top-level objects
waitForImage("icon.png", {}, "all" );

# Find icon.png on the MyWidget object
waitForImage "icon.png" {} [ waitForObject $names::MyWidget ]

# Find icon.png on multiple objects
waitForImage "icon.png" {} { [ waitForObject $names::MyWidget ],
                             [ waitForObject $names::MyOtherWidget ] }

# Find icon.png on the left half of the MyWidget object
set bounds [object globalBounds [ waitForObject $names::MyWidget ] ]
property set $bounds width [ expr [ property get $bounds width ] / 2 ]
waitForImage "icon.png" {} $bounds

# Find icon.png in the specified area
waitForImage "icon.png" {} [ construct ScreenRectangle 100 100 200 300 ]

# Find icon.png on all top-level objects
waitForImage "icon.png" {} "all"