FindPosition Method

Applies to TestComplete 15.20, last modified on January 19, 2022

Description

Returns a rectangular area of your PC desktop or mobile device screen that corresponds to the specified image.

Declaration

TestObj.FindPosition(SearchArea)

TestObj A variable, parameter or expression that specifies a reference to one of the objects listed in the Applies To section
SearchArea [in]    Optional    Object    
Result A Rect object.

Applies To

ImageSetItem

View Mode

To view this method in the Object Browser panel and in other panels and dialogs, activate the Advanced view mode.

Parameters

The method has the following parameter:

SearchArea

Specifies the area, within which the method will search for the image. Can take the following values:

If the parameter is omitted, first the method will search for the image on the screen of the current mobile device (you can set the current device by calling Mobile.SetCurrent in your script code, or the Select Device or Device Loop operation in your keyword test).

If the image is not found, the method will search for the image on your PC desktop.

Result Value

The Rect object that describes the rectangle within the specified search area where the image was found. If the image was not found, the method will return an “empty” object (null in JavaScript, JScript, C#Script and C++Script, None in Python, Nothing in VBScript, nil in DelphiScript).

Remarks

  • The coordinates and the size of the resulting area are logical. Note that the logical coordinates (points) on iOS devices may not correspond to physical coordinates (pixels). For detailed information on logical and physical coordinates, see the iOS documentation.

  • Typically, the scale factor for logical coordinates on high-resolution iOS devices is 2. So, in order to get physical coordinates and the size of the resulting area, you need to multiply the parameters of the corresponding rect object by two.

Example

The sample code below opens the All Apps screen and outputs the coordinates of the rectangular area containing the GMail App (if it is found):

JavaScript
JScript
Python
VBScript
DelphiScript
C++Script, C#Script

JavaScript

function FindGMailPosition()
{
  var GMailRect;
  Mobile.SetCurrent("Nexus 7", 0);

  Mobile.Device().PressButton(mbkHome, aptDownUp);
  // Open the All Apps screen
  ImageRepository.launcher.AllApps.Touch();
  // Search for the GMail App image within the mobile device screen
  GMailRect=ImageRepository.launcher.TextView_Gmail.FindPosition();
  if (!strictEqual(GMailRect, null))
    {
      Log.Message("GMail App coordinates:");
      Log.Message("Top: "+GMailRect.Top);
      Log.Message("Left: "+GMailRect.Left);
      Log.Message("Bottom: "+GMailRect.Bottom);
      Log.Message("Right: "+GMailRect.Right);
    }
  else Log.Warning("The GMail App was not found on the mobile device screen.")
}

JScript

function FindGMailPosition()
{
  var GMailRect;
  Mobile.SetCurrent("Nexus 7", 0);

  Mobile.Device.PressButton(mbkHome, aptDownUp);
  // Open the All Apps screen
  ImageRepository.launcher.AllApps.Touch();
  // Search for the GMail App image within the mobile device screen
  GMailRect=ImageRepository.launcher.TextView_Gmail.FindPosition();
  if (GMailRect!=null)
    {
      Log.Message("GMail App coordinates:");
      Log.Message("Top: "+GMailRect.Top);
      Log.Message("Left: "+GMailRect.Left);
      Log.Message("Bottom: "+GMailRect.Bottom);
      Log.Message("Right: "+GMailRect.Right);
    }
  else Log.Warning("The GMail App was not found on the mobile device screen.")
}

Python

def FindGMailPosition():
  Mobile.SetCurrent("Nexus 7", 0)
  Mobile.Device().PressButton(mbkHome, aptDownUp)
  # Open the All Apps screen
  ImageRepository.launcher.AllApps.Touch()
  # Search for the GMail App image within the mobile device screen 
  GMailRect = ImageRepository.launcher.TextView_Gmail.FindPosition()
  if GMailRect != None:
    Log.Message("GMail App coordinates:")
    Log.Message("Top: " + str(GMailRect.Top))
    Log.Message("Left: "+ str(GMailRect.Left))
    Log.Message("Bottom: " + str(GMailRect.Bottom))
    Log.Message("Right: " + str(GMailRect.Right))
  else:
    Log.Warning("The GMail App was not found on the mobile device screen.")

VBScript

Sub FindGMailPosition
  Dim GMailRect
  Call Mobile.SetCurrent("Nexus 7", 0)

  Call Mobile.Device.PressButton(mbkHome, aptDownUp)
  ' Open the All Apps screen
  Call ImageRepository.launcher.AllApps.Touch()
  ' Search for the GMail App image within the mobile device screen
  Set GMailRect=ImageRepository.launcher.TextView_Gmail.FindPosition()
  If Not GMailRect Is Nothing Then
      Call Log.Message("GMail App coordinates:")
      Call Log.Message("Top: "+GMailRect.Top)
      Call Log.Message("Left: "+GMailRect.Left)
      Call Log.Message("Bottom: "+GMailRect.Bottom)
      Call Log.Message("Right: "+GMailRect.Right)
  Else 
      Call Log.Warning("The GMail App was not found on the mobile device screen.")
  End If
End Sub

DelphiScript

procedure FindGMailPosition();
  var GMailRect;
begin
  Mobile.SetCurrent('Nexus 7', 0);

  Mobile.Device.PressButton(mbkHome, aptDownUp);
  // Open the All Apps screen
  ImageRepository.launcher.AllApps.Touch();
  // Search for the GMail App image within the mobile device screen
  GMailRect:=ImageRepository.launcher.TextView_Gmail.FindPosition();
  if GMailRect <> nil then
    begin
      Log.Message('GMail App coordinates:');
      Log.Message('Top: '+GMailRect.Top);
      Log.Message('Left: '+GMailRect.Left);
      Log.Message('Bottom: '+GMailRect.Bottom);
      Log.Message('Right: '+GMailRect.Right);
    end
  else Log.Warning('The GMail App was not found on the mobile device screen.')
end;

C++Script, C#Script

function FindGMailPosition()
{
  var GMailRect;
  Mobile["SetCurrent"]("Nexus 7", 0);

  Mobile["Device"]["PressButton"](mbkHome, aptDownUp);
  // Open the All Apps screen
  ImageRepository["launcher"]["AllApps"]["Touch"]();
  // Search for the GMail App image within the mobile device screen
  GMailRect=ImageRepository["launcher"]["TextView_Gmail"]["FindPosition"]();
  if (GMailRect!=null)
    {
      Log["Message"]("GMail App coordinates:");
      Log["Message"]("Top: "+GMailRect["Top"]);
      Log["Message"]("Left: "+GMailRect["Left"]);
      Log["Message"]("Bottom: "+GMailRect["Bottom"]);
      Log["Message"]("Right: "+GMailRect["Right"]);
    }
  else Log["Warning"]("The GMail App was not found on the mobile device screen.")
}

See Also

Testing Android Applications (Legacy)
Touch Method (ImageSetItem Object)
Exists Method
Image-Based Testing

Highlight search results