BlockByText Method

Applies to TestComplete 14.40, last modified on April 22, 2021

Description

The BlockByText method returns an OCRTextBlock object that describes a block of recognized text that matches the specified string.

Declaration

OCRTextDocumentObj.BlockByText(Text, SelectionPreference)

OCRTextDocumentObj An expression, variable or parameter that specifies a reference to an OCRTextDocument object
Text [in]    Required    String    
SelectionPreference [in]    Optional    Integer Default value: -1   
Result An OCRTextBlock object

Applies To

The method is applied to the following object:

OCRTextDocument

Parameters

The method has the following parameters:

Text

Specifies a string value the needed text block should match. Can contain an asterisk (*) or question mark (?) wildcards. The asterisk corresponds to a string of any length (including an empty string), the question mark corresponds to any single character (including none). Can be case-sensitive or case-insensitive depending on the Playback > Use case-sensitive parameters property of your project.

SelectionPreference

If there are several text blocks that match the Text parameter, the SelectionPreference parameter specifies which of them the method should return. The allowed parameter values are:

Constant Description
spNone Default value. The method will return the first text block it finds. If there are several text blocks that match the specified text, the method will post a warning to the test log.
spNearestToCenter The method will return the text block that is the closest to the center of the recognition area.
spLeftMost The method will return the leftmost text block.
spRightMost The method will return the rightmost text block.
spTopMost The method will return the topmost text block.
spBottomMost The method will return the bottommost text block.
spLargest The method will return the largest text block (the text block that occupies the largest area).
spSmallest The method will return the smallest text block (the text block that occupies the smallest area).

Note: The text block position is estimated relative to the recognition area to which the block belongs.

Result Value

An OCRTextBlock object that describes a text block that matches the specified string.

If the recognized text does not contain a text block whose text matches the specified string, the method will post an error to the test log and return a stub OCRTextBlock object. To avoid possible errors, we recommend that you check whether the recognized text returned by the OCRTextDocument.FullText property contains the needed text fragment. For example, you can do this by using the aqString.Find method. The examples below show how you can do this.

Example

The code below shows how to locate a screen area by its text and simulate user actions on it. It opens the About dialog of the Windows Notepad application, searches for the OK button in it and clicks the button:

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

JavaScript, JScript

function GetObjectByText()
{
  var textToGet = "OK";

  var p = Sys.WaitProcess("notepad", 3000);
  if (p.Exists)
  {
    // Get the Notepad window
    var wndNotepad = p.WaitWindow("Notepad", "*", 1, 3000);
    if (wndNotepad.Exists)
    {
      wndNotepad.MainMenu.Click("Help|About Notepad");
      // Get the About Notepad window
      var wndAbout = p.WaitWindow("#32770", "About Notepad", 1, 3000);
      if (wndAbout.Exists)
      {
        // Recognize the text that the About Notepad window contains
        var recognizedText = OCR.Recognize(wndAbout);

        // Checks whether the recognized text contains the needed fragment
        if (aqString.Find(recognizedText.FullText, textToGet, 0, false) > -1)
        {
          var okTextBlock = recognizedText.BlockByText(textToGet);
          // Click on the window area that contains the specified text
          okTextBlock.Click();
        }
      }
    }
  }
  else
  {
    Log.Warning("Notepad is not running.");
  }
}

Python

def GetObjectByText():
  textToGet = "OK"

  p = Sys.WaitProcess("notepad", 3000)
  if p.Exists:
    # Get the Notepad window
    wndNotepad = p.WaitWindow("Notepad", "*", 1, 3000)
    if wndNotepad.Exists:
      wndNotepad.MainMenu.Click("Help|About Notepad")
      # Get the About Notepad window
      wndAbout = p.WaitWindow("#32770", "About Notepad", 1, 3000)
      if wndAbout.Exists:
        # Recognize the text that the About Notepad window contains
        recognizedText = OCR.Recognize(wndAbout)

        # Checks whether the recognized text contains the needed fragment
        if aqString.Find(recognizedText.FullText, textToGet, 0, False) > -1:
          okTextBlock = recognizedText.BlockByText(textToGet)
          # Click on the window area that contains the specified text
          okTextBlock.Click()
  else:
    Log.Warning("Notepad is not running.")

VBScript

Sub GetObjectByText

  textToGet = "OK"

  Set p = Sys.WaitProcess("notepad", 3000)
  If p.Exists Then
    ' Get the Notepad window
    Set wndNotepad = p.WaitWindow("Notepad", "*", 1, 3000)
    If wndNotepad.Exists Then
      wndNotepad.MainMenu.Click("Help|About Notepad")
      ' Get the About Notepad window
      Set wndAbout = p.WaitWindow("#32770", "About Notepad", 1, 3000)
      If wndAbout.Exists Then
        ' Recognize the text that the About Notepad window contains
        Set recognizedText = OCR.Recognize(wndAbout)

        ' Checks whether the recognized text contains the needed fragment
        If aqString.Find(recognizedText.FullText, textToGet, 0, False) > -1 Then
          Set okTextBlock = recognizedText.BlockByText(textToGet)
          ' Click on the window area that contains the specified text
          okTextBlock.Click
        End If
      End If
    End If
  Else
    Log.Warning("Notepad is not running.")
  End If
End Sub

DelphiScript

procedure GetObjectByText();
var textToGet, p, wndNotepad, wndAbout, recognizedText, okTextBlock;
begin

  textToGet := 'OK';

  p := Sys.WaitProcess('notepad', 3000);
  if p.Exists then
  begin
    // Get the Notepad window
    wndNotepad := p.WaitWindow('Notepad', '*', 1, 3000);
    if wndNotepad.Exists then
    begin
      wndNotepad.MainMenu.Click('Help|About Notepad');
      // Get the About Notepad window
      wndAbout := p.WaitWindow('#32770', 'About Notepad', 1, 3000);
      if wndAbout.Exists then
      begin
        // Recognize the text that the About Notepad window contains
        recognizedText := OCR.Recognize(wndAbout);

        // Checks whether the recognized text contains the needed fragment
        if aqString.Find(recognizedText.FullText, textToGet, 0, false) > -1 then
        begin
          okTextBlock := recognizedText.BlockByText(textToGet);
          // Click on the window area that contains the specified text
          okTextBlock.Click;
        end;
      end;
    end;
  end
  else
    Log.Warning('Notepad is not running.');
end;

C++Script, C#Script

function GetObjectByText()
{
  var textToGet = "OK";

  var p = Sys["WaitProcess"]("notepad", 3000);
  if (p["Exists"])
  {
    // Get the Notepad window
    var wndNotepad = p["WaitWindow"]("Notepad", "*", 1, 3000);
    if (wndNotepad["Exists"])
    {
      wndNotepad["MainMenu"]["Click"]("Help|About Notepad");
      // Get the About Notepad window
      var wndAbout = p["WaitWindow"]("#32770", "About Notepad", 1, 3000);
      if (wndAbout["Exists"])
      {
        // Recognize the text that the About Notepad window contains
        var recognizedText = OCR["Recognize"](wndAbout);

        // Checks whether the recognized text contains the needed fragment
        if (aqString["Find"](recognizedText["FullText"], textToGet, 0, false) > -1)
        {
          var okTextBlock = recognizedText["BlockByText"](textToGet);
          // Click on the window area that contains the specified text
          okTextBlock["Click"]();
        }
      }
    }
  }
  else
  {
    Log["Warning"]("Notepad is not running.");
  }
}

The code below shows how to locate a non-unique text fragment and simulate user actions on it. It opens the About dialog of the Windows Notepad application, searches for the text fragment containing the Microsoft substring and residing closest to the dialog bottom, and clicks on the found fragment:

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

JavaScript, JScript

function GetObjectByText_NonUnique()
{
  var textToGet = "Microsoft";

  var p = Sys.WaitProcess("notepad", 3000);
  if (p.Exists)
  {
    // Get the Notepad window
    var wndNotepad = p.WaitWindow("Notepad", "*", 1, 3000);
    if (wndNotepad.Exists)
    {
      wndNotepad.MainMenu.Click("Help|About Notepad");
      // Get the About Notepad window
      var wndAbout = p.WaitWindow("#32770", "About Notepad", 1, 3000);
      if (wndAbout.Exists)
      {
        // Recognize the text that the About Notepad window contains
        var recognizedText = OCR.Recognize(wndAbout);

        // Get the bottommost 'Microsoft' text fragment and click it
        if (aqString.Find(recognizedText.FullText, textToGet, 0 , false) > -1)
        {
          var link = recognizedText.BlockByText(textToGet, spBottomMost);
          link.Click();
        }
      }
    }
  }
  else
  {
    Log.Warning("Notepad is not running.");
  }
}

Python

def GetObjectByText_NonUnique():

   textToGet = "Microsoft"

   p = Sys.WaitProcess("notepad", 3000)
   if p.Exists:
     # Get the Notepad window
     wndNotepad = p.WaitWindow("Notepad", "*", 1, 3000)
     if wndNotepad.Exists:
       wndNotepad.MainMenu.Click("Help|About Notepad")
       # Get the About Notepad window
       wndAbout = p.WaitWindow("#32770", "About Notepad", 1, 3000)
       if wndAbout.Exists:
         # Recognize the text that the About Notepad window contains
         recognizedText = OCR.Recognize(wndAbout)

         # Get the bottommost 'Microsoft' text fragment and click it
         if aqString.Find(recognizedText.FullText, textToGet, 0 , False):
           link = recognizedText.BlockByText(textToGet, spBottomMost)
           link.Click()
   else:
     Log.Warning("Notepad is not running.")

VBScript

Sub GetObjectByText_NonUnique

  textToGet = "Microsoft"

  Set p = Sys.WaitProcess("notepad", 3000)
  If p.Exists Then
    ' Get the Notepad window
    Set wndNotepad = p.WaitWindow("Notepad", "*", 1, 3000)
    If wndNotepad.Exists Then
      wndNotepad.MainMenu.Click("Help|About Notepad")
      ' Get the About Notepad window
      Set wndAbout = p.WaitWindow("#32770", "About Notepad", 1, 3000)
      If wndAbout.Exists Then
        ' Recognize the text that the About Notepad window contains
        Set recognizedText = OCR.Recognize(wndAbout)

        ' Get the bottommost 'Microsoft' text fragment and click it
        If aqString.Find(recognizedText.FullText, textToGet, 0, False) > -1 Then
          Set link = recognizedText.BlockByText(textToGet, spBottomMost)
          link.Click
        End If
      End If

    End If
  Else
    Log.Warning("Notepad is not running.")
  End If
End Sub

DelphiScript

procedure GetObjectByText_NonUnique();
var textToGet, p, wndNotepad, wndAbout, recognizedText, link;
begin

  textToGet := 'Microsoft';

  p := Sys.WaitProcess('notepad', 3000);
  if p.Exists then
  begin
    // Get the Notepad window
    wndNotepad := p.WaitWindow('Notepad', '*', 1, 3000);
    if wndNotepad.Exists then
    begin
      wndNotepad.MainMenu.Click('Help|About Notepad');
      // Get the About Notepad window
      wndAbout := p.WaitWindow('#32770', 'About Notepad', 1, 3000);
      if wndAbout.Exists then
      begin
        // Recognize the text that the About Notepad window contains
        recognizedText := OCR.Recognize(wndAbout);

        // Get the bottommost 'Microsoft' text fragment and click it
        if aqString.Find(recognizedText.FullText, textToGet, 0 , false) > -1 then
        begin
          link := recognizedText.BlockByText(textToGet, spBottomMost);
          link.Click;
        end;
      end;

    end;
  end  else
    Log.Warning('Notepad is not running.');
end;

C++Script, C#Script

function GetObjectByText_NonUnique()
{
  var textToGet = "Microsoft";

  var p = Sys["WaitProcess"]("notepad", 3000);
  if (p["Exists"])
  {
    // Get the Notepad window
    var wndNotepad = p["WaitWindow"]("Notepad", "*", 1, 3000);
    if (wndNotepad["Exists"])
    {
      wndNotepad["MainMenu"]["Click"]("Help|About Notepad");
      // Get the About Notepad window
      var wndAbout = p["WaitWindow"]("#32770", "About Notepad", 1, 3000);
      if (wndAbout["Exists"])
      {
        // Recognize the text that the About Notepad window contains
        var recognizedText = OCR["Recognize"](wndAbout);

        // Get the bottommost 'Microsoft' text fragment and click it
        if (aqString.Find(recognizedText.FullText, textToGet, 0 , false) > -1)
        {
          var link = recognizedText["BlockByText"](textToGet, spBottomMost);
          link["Click"]();
        }
      }
    }
  }
  else
  {
    Log["Warning"]("Notepad is not running.");
  }
}

See Also

OCRTextDocument Object
Optical Character Recognition

Highlight search results