[Collapse]TestComplete/viewarticle/63445/
 [Expand]General Information/viewarticle/63445/
 [Expand]Using Help System/viewarticle/55799/
 [Expand]Getting Started Tutorial/viewarticle/56246/
 [Expand]Using TestComplete/viewarticle/57875/
 [Expand]Testing Types/viewarticle/62721/
 [Expand]Applications Testing/viewarticle/62606/
 [Expand]Working With Application Objects and Controls/viewarticle/55815/
 [Expand]Samples and Tutorials/viewarticle/56239/
 [Collapse]References/viewarticle/57878/
  [Expand]Test Objects/viewarticle/57881/
  [Expand]Scripting Objects/viewarticle/57882/
  [Collapse]Project and Project Item Objects/viewarticle/57880/
   [Expand]Project Suite Objects/viewarticle/59766/
   [Collapse]Project Item Objects/viewarticle/59767/
     ActiveX Objects/viewarticle/56464/
    [Expand]Android Gesture Collection/viewarticle/59748/
    [Expand]Events/viewarticle/56945/
    [Expand]Image Repository/viewarticle/59749/
    [Expand]Keyword Testing/viewarticle/59771/
    [Expand]Low-Level Procedures Collection/viewarticle/59772/
    [Expand]Manual Tests/viewarticle/59773/
    [Expand]Name Mapping/viewarticle/59774/
    [Expand]Network Suite/viewarticle/59775/
    [Expand]ODT/viewarticle/59776/
    [Expand]Script/viewarticle/59777/
    [Collapse]Stores/viewarticle/59778/
     [Expand]DBTable/viewarticle/57122/
     [Expand]DBTables/viewarticle/57121/
     [Expand]DBTableVariable/viewarticle/55656/
     [Expand]ManualCheck/viewarticle/57011/
     [Expand]File/viewarticle/57147/
     [Expand]Files/viewarticle/55172/
     [Expand]Objects/viewarticle/55232/
     [Expand]Region/viewarticle/57163/
     [Expand]RegionInfo/viewarticle/58342/
     [Collapse]Regions/viewarticle/55165/
       Regions Object/viewarticle/55165/
      [Collapse]Regions Object Methods/viewarticle/58341/
        Add Method/viewarticle/55423/
        AddPicture Method/viewarticle/55222/
        Compare Method/viewarticle/55076/
        Contains Method/viewarticle/58268/
        ContainsFile Method/viewarticle/58261/
        Count Method/viewarticle/58264/
        CreateRegionInfo Method/viewarticle/55741/
        FileNameByIndex Method/viewarticle/58265/
        FileNameByName Method/viewarticle/58267/
        FileNamesList Method/viewarticle/58263/
        Find Method/viewarticle/55091/
        FindRegion Method/viewarticle/55077/
        GetPicture Method/viewarticle/57162/
        Items Method/viewarticle/58343/
        LastError Method/viewarticle/58255/
        NameByFileName Method/viewarticle/58260/
        NameByIndex Method/viewarticle/58262/
        NamesList Method/viewarticle/58266/
        Remove Method/viewarticle/57141/
       Regions Object Properties/viewarticle/58340/
     [Expand]StoredObject/viewarticle/57148/
     [Expand]StoredObjectProperty/viewarticle/59050/
     [Expand]Table/viewarticle/57170/
     [Expand]Tables/viewarticle/57171/
     [Expand]TableVariable/viewarticle/55623/
     [Expand]WebAccessibility/viewarticle/55426/
     [Expand]WebComparison/viewarticle/55392/
     [Expand]WebTesting/viewarticle/57184/
     [Expand]XMLCheckpointOptions/viewarticle/57195/
     [Expand]XML/viewarticle/55363/
     [Expand]XMLCheckpoint/viewarticle/56360/
    [Expand]Tested Applications/viewarticle/59779/
    [Expand]Unit Testing/viewarticle/59780/
    [Expand]User Forms/viewarticle/59781/
    [Expand]Web Services/viewarticle/59782/
   [Expand]Project Objects/viewarticle/59768/
   [Expand]Test Log Objects/viewarticle/59769/
   [Expand]COM Automation Objects/viewarticle/59770/
  [Expand]TestComplete Events/viewarticle/56945/
  [Expand]Language Reference/viewarticle/57879/
  [Expand]User Form Components/viewarticle/56689/
 [Expand]Other Tools That Help You Test Better/viewarticle/63442/
 [Expand]TestComplete 10 Licensing Guide/viewarticle/63451/
Updated: 7/15/2014 Applies To: TestComplete 10 Rating: No votes Click to rate: PoorNot badAverageGoodExcellent
Programming Reference

FindRegion Method

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’s image comparison engine. To learn more about it, read the How Image Comparison Works topic.

Declaration

Regions.FindRegion(PictureToSearchForPictureToSearchInLeftTopTransparentMousePixelTolerance)

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:

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 (Nothing in VBScript, null in JScript, C++Script and C#Script and 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.

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

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");
}

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;

C++Script, C#Script

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");
}

See also
About Regions Editor | About Region Checkpoints | How Image Comparison Works | Compare Method | Find Method | Find Method | Picture Object


© 2014 SmartBear Software. All rights reserved.
Email Send feedback on this document