Description

The Regions.FindRegion 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 bitmap is not found, FindRegion 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.FindRegion(PictureToSearchFor, PictureToSearchIn, Left, Top, Transparent, Mouse, PixelTolerance)

PictureToSearchFor	[in]	Required	Variant
PictureToSearchIn	[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:

PictureToSearchFor

Specifies the sought-for image. PictureToSearchFor can be one of the following values:

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

PictureToSearchIn

Specifies the image, within which TestComplete searches for another image. To set the parameter, you can use the same values, which you used to specify the PictureToSearchFor 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 image is included into the image where the method operates. By default, the Mouse parameter is False. If it is True and the PictureToSearchIn parameter specifies an object (for example, a window or onscreen object) with the mouse pointer over it, then the mouse pointer is included in this image. The FindRegion method will only return True if the other image includes the mouse pointer in 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, FindRegion returns the Rect object whose properties are set to the values fitting the sought-for image found within the PictureToSearchIn image. This is the first image found, searching left-right and top-down. If the search fails, FindRegion 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.FindRegion method is similar to the Regions.Find 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.FindRegion(w, "Region1")))
    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.FindRegion(w, "Region1") == 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.FindRegion(w, "Region1") == 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.FindRegion(w, "Region1") 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.FindRegion(w, 'Region1') = nil then
    Log.Warning('Not found');
end;