Description

The Regions.Find method searches pixel-by-pixel for one image, specified by the PictureToSearchFor parameter, within another, represented by the PictureToSearchIn parameter, and returns the rectangular area that corresponds to the found image. If either image is not found, Find generates an error string, which you can retrieve from the LastError property of the Regions object (and post to the test log).

This method uses the TestComplete image comparison engine. To learn more about it, read the How Image Comparison Works topic.

Declaration

Regions.Find(PictureToSearchIn, PictureToSearchFor, Left, Top, Transparent, Mouse, PixelTolerance)

PictureToSearchIn	[in]	Required	Variant
PictureToSearchFor	[in]	Required	Variant
Left	[in]	Optional	Integer	Default value: 0
Top	[in]	Optional	Integer	Default value: 0
Transparent	[in]	Optional	Boolean	Default value: False
Mouse	[in]	Optional	Boolean	Default value: False
PixelTolerance	[in]	Optional	Integer	Default value: 0
Result	A `Rect` object

Applies To

The method is applied to the following object:

Regions

Parameters

The method has the following parameters:

PictureToSearchIn

Specifies the image within which another image will be searched. You can use one of the following values to specify this image:

The name of the image in the Regions collection of the Stores project item (if the image is added to this collection).
A Picture object.
A window or onscreen object.
Fully-qualified path to the image file. The following file types are supported:
- BMP
- JPEG
- PNG
- TIFF
- GIF
- ICO

PictureToSearchFor

Specifies the image, that TestComplete searches for within another image specified by the PictureToSearchIn parameter.

To specify the PictureToSearchFor parameter you can use the same values, which you used to specify the PictureToSearchIn parameter: the image’s name in the Regions collection, the Picture or window object, or the fully-qualified file name.

Left

The horizontal coordinate of the PictureToSearchIn image’s pixel that serves as the top-level corner of the imaginary rectangle within that image. The method will search for the PictureToSearchFor picture inside this rectangle. This allows you to restrict the search area. 0 is the default value; it means that this imaginary rectangle starts from the left side of the given image.

Top

The vertical coordinate of the PictureToSearchIn image’s pixel that serves as the top-level corner of the imaginary rectangle within that image. The method will search for the PictureToSearchFor picture inside this rectangle. This allows you to restrict the search area. 0 is the default value; it means that this imaginary rectangle starts from the top side of the given image.

Transparent

False by default. If it is True, then the top left pixel of PictureToSearchFor will be treated as the “transparent” (background) color in PictureToSearchIn, which is meaningless for comparison. For instance, if that pixel is gray, then any gray pixel in PictureToSearchFor will match any color pixel in PictureToSearchIn.

Mouse

The Mouse parameter specifies whether the mouse pointer is included into the image specified by the PictureToSearchFor parameter. By default, the Mouse parameter is False. If it is True and the PictureToSearchFor parameter specifies an object (for example, a window or onscreen object) with the mouse pointer over this object, then the mouse pointer is included as part of the image. The Find method will only return True if the other image also includes the mouse pointer image at the same position.

PixelTolerance

Lets you ignore slight differences between the bitmaps during the search. If the number of different pixels is less than or equal to PixelTolerance, then TestComplete considers the images to be identical. 0 is the default value; it means that no differences between the bitmaps except for those set by the Transparent parameter are ignored.

Note:

Using the PixelTolerance parameter with non-zero values may slow down the search process.

Result Value

If the search is successful, Find returns the Rect object whose properties are set to the values fitting the image found within the PictureToSearchIn image. This is the first image found, searching left-right and top-down. If the search fails, Find returns an empty value (null in JavaScript, JScript, C#Script and C++Script, None in Python, Nothing in VBScript, nil in DelphiScript).

Remarks

If the method fails to locate an image, while the sought-for image is part of another image, see the Why Image Comparison Fails and Factors Affecting Image Comparison help topics to determine the cause of the failure.

The Regions.Find method is very similar to the Regions.FindRegion method. The only difference between them is the order of the PictureToSearchIn and PictureToSearchFor parameters.

Example

The following code searches for an image within another image that is stored in the Regions collection.

JavaScript

function Test()
{
  let w;
  w = Sys.Desktop.ActiveWindow().Picture(20, 20, 50, 50);

  // Region1 is part of the Regions collection
  if (strictEqual(Regions.Find("Region1", w)))
    Log.Warning("Not found", null);
}

JScript

function Test()
{
  var w;
  w = Sys.Desktop.ActiveWindow().Picture(20, 20, 50, 50);

  // Region1 is part of the Regions collection
  if (Regions.Find("Region1", w) == null)
    Log.Warning("Not found");
}

Python

def Test():
  w = Sys.Desktop.ActiveWindow().Picture(20, 20, 50, 50)
  # Region1 is part of the Regions collection
  if Regions.Find("Region1", w) == None:
    Log.Warning("Not found")

VBScript

Sub Test
  Set w = Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50)

  ' Region1 is part of the Regions collection
  If Regions.Find("Region1", w) Is Nothing Then
    Log.Warning "Not found"
  End If
End Sub

DelphiScript

procedure Test();
var
  w : OleVariant;
begin
  w := Sys.Desktop.ActiveWindow.Picture(20, 20, 50, 50);

  // Region1 is part of the Regions collection
  if Regions.Find('Region1', w) = nil then
    Log.Warning('Not found');
end;