TextUtil Object

Description

The object used to recognize text within a specified window handle.

IMPORTANT

When possible, we recommend that you use alternative methods to capture text instead of using the TextUtil object. For example:

  • Use the GetROProperty method or the Object property to retrieve the value of the text (or equivalent) property from an object in your application

  • Use a text or text area output value step to retrieve text or a text or text area checkpoint step to verify a text value.

  • Use the GetVisibleText or GetTextLocation methods of the appropriate test object.

For more details on text and text area checkpoints, see the Micro Focus UFT One User Guide. For more details on the GetVisibleText method, see the relevant section in the Micro Focus UFT One Object Model Reference for GUI Testing.

Methods

Method ClearOCRCacheClears OCR result cache.
Method GetTextReturns the text from the specified window handle area.
Method GetTextFromImage

Returns the text from the specified area in the image file.

Method GetTextFromImageByColor

(UFT One versions 2022 and later)

Returns the text in the specified color from the specified area in the image file.

Method GetTextLocation

Returns the location of the specified string.

Method GetTextLocationFromImage

Returns the location of the specified string in the image file.

Method GetTextLocationFromImageByColor

(UFT One versions 2022 and later)

Returns the location of the specified string in the specified color in the image file.

Method ResetABBYYParametersResets ABBYY OCR recognition parameters.
Method SetABBYYParametersSets ABBYY OCR recognition parameters for the current test run.

Back to top

ClearOCRCache Method

Description

Clears the OCR result cache, which stores any texts retrieved from images in the current run to improve OCR performance.

Use this method if you change the OCR settings (for example, using SetABBYYParameters) during a test run and want these changes to affect an image whose text was previously retrieved in this test run.

Syntax

TextUtil.ClearOCRCache()

Return Value

None

IMPORTANT

This method clears the cached information for all images. Any text retrieved earlier in the test run needs to be retrieved again, which may affect your test's performance.

The following example clears the previous cached text information for the Brown_Car image to apply ABBYY OCR parameter settings.

' Get text from the upper corner of the Brown_Car image
CarText = TextUtil.GetTextFromImage("C:\Users\Public\Pictures\Brown_Car.jpeg", 0, 0, 50, 50)
MsgBox CarText
' Clear the cached OCR result 
TextUtil.ClearOCRCache
' Set the ABBYY parameter enableAggressiveTextExtraction to extract as much text on the image as possible
TextUtil.SetABBYYParameters("enableAggressiveTextExtraction", True)
' Set the ABBYY parameter removeGarbage to remove garbage from the image during text extraction
TextUtil.SetABBYYParameters("removeGarbage", True)
CarText = TextUtil.GetTextFromImage("C:\Users\Public\Pictures\Brown_Car.jpeg", 0, 0, 50, 50)
MsgBox CarText

Back to top

GetText Method

Description

Returns the text from the specified window handle area. The area is defined by pairs of coordinates that designate two diagonally opposite corners of a rectangle.

Syntax

TextUtil.GetText(hWnd, [Left, Top, Right, Bottom])

Argument

Type

Description

hWnd

Number

The handle to a run-time object's window.

Note:  

  • If hWnd is not 0, then the coordinate arguments apply to the specified window. If hWnd is 0, the coordinates apply to the screen.

  • The value 0 is not supported when running steps on Vista operating systems or higher, or on any 64-bit operating system.

Left, Top, Right, Bottom

Number

Optional. These arguments define the search area within the window or screen.

Note: If these arguments are not specified, the method returns all text contained in the window or screen.

Return Value

String

IMPORTANT

  • The text to capture must be visible in the application window when the step runs.

  • When possible, we recommend that you use alternative methods to capture text. For more details, see the IMPORTANT section above.

  • The results of this method may be different depending on the settings selected in the Text Recognition pane of the Options dialog box (Tools > Options > GUI Testing tab > Text Recognition node).

  • The results of this method may be different in different run sessions depending on the operating system version you are using, service packs you have installed, other installed toolkits, or the APIs used in your application. Therefore, when possible, we highly recommend that you use alternative ways to retrieve the value of the text (or equivalent) property from an object in your application instead of using the GetText method, as described in the Important Information section of the TextUtil Object.

The following example retrieves all of the text from the "Telnet" window.

' Find handle of the Telnet window
Extern.Declare micLong,"FindWindow","User32","FindWindowA",micString,micString 
hTelnet = Extern.FindWindow("TelnetWClass", "Telnet - 100.100.100.100")

' Get text from the Telnet window
TelnetText = TextUtil.GetText(hTelnet)
MsgBox TelnetText

The following example retrieves the text from the screen rectangle.

' Get text from the screen rectangle
MsgBox TextUtil.GetText(0, 20, 20, 200, 200)

Back to top

GetTextFromImage Method

Description

Returns the text from a specified area in an image file.

Syntax

TextUtil.GetTextFromImage(FilePath, [Left, Top, Right, Bottom])

Argument

Type

Description

FilePath

String

The path to the image file. Supported image file types: BMP, GIF, JPEG, PNG, and TIFF.

Left, Top, Right, Bottom

Number

Optional. These arguments define the search area within the image.

Note: If these arguments are not specified, the method returns all text contained in the image.

Return Value

String

IMPORTANT

  • When possible, we recommend that you use alternative methods to capture text. For more details, see the IMPORTANT section above.

  • The results of this method may be different depending on the settings selected in the Text Recognition pane of the Options dialog box (Tools > Options > GUI Testing tab > Text Recognition node).

  • The results of this method may be different in different run sessions depending on the operating system version you are using, service packs you have installed, other installed toolkits, or the APIs used in your application. Therefore, when possible, we highly recommend that you use alternative ways to retrieve the value of the text (or equivalent) property from an object in your application instead of using the GetTextFromImage method, as described in the Important Information section of the TextUtil Object.

The following example retrieves the text from the upper left corner of the Brown_Car image.

' Get text from the upper corner of the Brown_Car image 
CarText = TextUtil.GetTextFromImage("C:\Users\Public\Pictures\Brown_Car.jpeg", 0, 0, 50, 50)
MsgBox CarText

Back to top

GetTextFromImageByColor Method

Supported on UFT One versions 2022 and later.

Description

Returns the text in a specified color from the specified area in the image file.

Syntax

TextUtil.GetTextFromImagebyColor(FilePath, TextColor, BackgroundColor, HueThreshold, TextInverted, [Left, Top, Right, Bottom])

Argument

Type

Description

FilePath

String

The path to the image file. Supported image file types: BMP, GIF, JPEG, PNG, and TIFF.

TextColorString

The color of the text you want to retrieve from the image file.

The value is a 6-digit hexadecimal color code without a # sign. The first two numbers refer to red, the next two refer to green, and the last two refer to blue.

BackgroundColorString

The background color of the image file.

The value is a 6-digit hexadecimal color code without a # sign. The first two numbers refer to red, the next two refer to green, and the last two refer to blue.

HueThresholdInteger

The level of change in hue that UFT One ignores when matching the object to the description.

For example, if you set this parameter to 10, when identifying the text in an image file, UFT One ignores a difference of 10 between the specified colors and the hues in the image.

We recommend that you set a smaller threshold to achieve a higher detection accuracy.

Value range: 0 - 180.

TextInvertedBoolean

Indicates whether the text and background colors are inverted.

Tip: In some cases, if the background color in your image is darker than the text color, setting TextInverted to true can improve text identification.

Left, Top, Right, Bottom

Integer

Optional. These arguments define the search area within the image.

Note: If these arguments are not specified, the method returns all color-matching text contained in the image.

Return Value

String

IMPORTANT

  • When possible, we recommend that you use alternative methods to capture text. For more details, see the IMPORTANT section above.

  • This method can only be used when you select ABBYY as the OCR engine in the Text Recognition pane of the Options dialog box (Tools > Options > GUI Testing tab > Text Recognition node).

  • If every letter or character in the text string you want to retrieve has its own color, we recommend that you retrieve the letter or character based on a color at a time.

  • If the text string you want to retrieve contains a multi-colored letter or character, we recommend that you use alternative methods. For more details, see the IMPORTANT section above.

The following example retrieves the blue text from the Brown_Car image.

Copy code
imagePath = C:\Users\Public\Pictures\Brown_Car.jpeg
Text = TextUtil.GetTextFromImageByColor (imagePath, "0066CC", "FFFFFF", 10, false)
MsgBox Text

Back to top

GetTextLocation Method

Description

Checks whether a specified text string is contained in a specified window area. If the text string is located, the location coordinates are also returned.

Syntax

TextUtil.GetTextLocation(TextToFind, hWnd, Left, Top, Right, Bottom)

Argument

Type

Description

TextToFind

String

The text string you want to locate.

hWnd

Number

The handle to a run-time object's window.

    Note:

  • If hWnd is not 0, then the coordinate arguments apply to the specified window. If hWnd is 0, the coordinates apply to the screen.

  • The value 0 is not supported when running steps on Vista operating systems or higher, or on any 64-bit operating system.

Left, Top, Right, Bottom

InOut, Number

These arguments define the search area within the window or screen.

Set all coordinates to -1 (or leave their values unset) to search for the text string within the entire window or screen.

The method returns the coordinates of the rectangle containing the first instance of the text into these variables if the text is found.

Return Value

Boolean

IMPORTANT

  • The text to capture must be visible in the application window when the step runs.

  • This method returns True only if the TextToFind argument value is found within a single line in the specified area. The text search restarts on each line of text.

  • If the TextToFind argument value includes a space, then this method searches for that text as whole words. For example, if you search for "a b" and the text "bla bla" exists, the method will still return False.

  • If the text is found (return value = True) and if the Left, Top, Right, and Bottom arguments are supplied as variables, then the method overwrites these arguments with the coordinates that describe the location of the found text.

  • The results of this method may be different depending on the settings selected in the Text Recognition pane of the Options dialog box (Tools Options > GUI Testing tab > Text Recognition node).

  • The results of this method may be different in different run sessions depending on the operating system version you are using, service packs you have installed, other installed toolkits, or the APIs used in your application. Therefore, when possible, we highly recommend that you use alternative ways to retrieve the value of the text (or equivalent) property from an object in your application instead of using the GetTextLocation method, as described in the Important Information section of the TextUtil Object.

The following example searches for the word Mercury within the entire screen and clicks it if the word is found.

l = -1 
t = -1 
r = -1 
b = -1 
Succeeded = TextUtil.GetTextLocation("Mercury",0,l,t,r,b) 

If Not Succeeded Then 
    MsgBox "Text not found"
else
    x = (l+r) / 2 
    y = (t+b) / 2 
    Set dr = CreateObject("Mercury.DeviceReplay") 
    dr.MouseClick x, y, 0 
End If

Back to top

GetTextLocationFromImage Method

Description

Returns the location of the specified string in the image file.

Syntax

TextUtil.GetTextLocationFromImage(TextToFind, FilePath, Left, Top, Right, Bottom[, MatchWholeWordOnly])

Argument

Type

Description

TextToFind

String

The text string you want to locate.

FilePath

String

The path to the image file. Supported image file types: BMP, GIF, JPEG, PNG, and TIFF.

Left, Top, Right, Bottom

InOut, Number

These arguments define the search area within the image.

Set all coordinates to -1 (or leave their values unset) to search for the text string within the entire window or screen.

The method returns the coordinates of the rectangle containing the first instance of the text into these variables if the text is found.

Return Value

Boolean

IMPORTANT

  • This method returns True only if the TextToFind argument value is found within a single line in the specified area. The text search restarts on each line of text.

  • If the TextToFind argument value includes a space, then this method searches for that text as whole words. For example, if you search for "a b" and the text "bla bla" exists, the method will still return False.

  • If the text is found (return value = True) and if the Left, Top, Right, and Bottom arguments are supplied as variables, then the method overwrites these arguments with the coordinates that describe the location of the found text.

  • The results of this method may be different depending on the settings selected in the Text Recognition pane of the Options dialog box (Tools Options > GUI Testing tab > Text Recognition node).

  • The results of this method may be different in different run sessions depending on the operating system version you are using, service packs you have installed, other installed toolkits, or the APIs used in your application. Therefore, when possible, we highly recommend that you use alternative ways to retrieve the value of the text (or equivalent) property from an object in your application instead of using the GetTextLocationFromImage method, as described in the Important Information section of the TextUtil Object.

The following example retrieves the text from the upper left corner of the Brown_Car image.

'Create the coordinate variables to store the returned value
Dim l  'coordinate for left
Dim t  'coordinate for top
Dim r  'coordinate for right
Dim b  'coordinate for bottom
'Leave coordinates empty to search the entire image
TextUtil.GetTextLocationFromImage "text_to_find", "C:\ImagePath", l, t, r, b

Back to top

GetTextLocationFromImageByColor Method

Supported on UFT One versions 2022 and later.

Description

Returns the location of the specified string in the specified color in the image file.

Syntax

TextUtil.GetTextLocationFromImageByColor(TextToFind, FilePath, Left, Top, Right, Bottom, TextColor, BackgroundColor, HueThreshold, TextInverted)

Argument

Type

Description

TextToFind

String

The text string you want to locate.

FilePath

String

The path to the image file. Supported image file types: BMP, GIF, JPEG, PNG, and TIFF.

Left, Top, Right, Bottom

InOut, Number

These arguments define the search area within the image.

Set all coordinates to -1 (or leave their values unset) to search for the text string within the entire image.

The method returns the coordinates of the rectangle containing the first instance of the text into these variables if the text is found.

TextColorString

The color of the text string you want to locate.

The value is a 6-digit hexadecimal color code without a # sign. The first two numbers refer to red, the next two refer to green, and the last two refer to blue.

BackgroundColorString

The background color of the image file.

The value is a 6-digit hexadecimal color code without a # sign. The first two numbers refer to red, the next two refer to green, and the last two refer to blue.

HueThresholdInteger

The level of change in hue that UFT One ignores when matching the object to the description.

For example, if you set this parameter to 10, when identifying the text in an image file, UFT One ignores a difference of 10 between the specified colors and the hues in the image.

We recommend that you set a smaller threshold to achieve a higher detection accuracy.

Value range: 0 - 180.

TextInvertedBoolean

Indicates whether the text and background colors are inverted.

If true, UFT One looks for text in the color specified as BackgroundColor on a background whose color is TextColor.

Tip: If the text color in your image is darker than the background color, setting TextInverted to true can improve text identification.

Return Value

Boolean

IMPORTANT

  • This method can only be used when you select ABBYY as the OCR engine in the Text Recognition pane of the Options dialog box (Tools > Options > GUI Testing tab > Text Recognition node).

  • This method returns True only if the TextToFind argument value is found within a single line in the specified area. The text search restarts on each line of text.

  • If the TextToFind argument value includes a space, then this method searches for that text as whole words. For example, if you search for "a b" and the text "bla bla" exists, the method will still return False.

  • If the text is found (return value = True) and if the Left, Top, Right, and Bottom arguments are supplied as variables, then the method overwrites these arguments with the coordinates that describe the location of the found text.

The following example checks where the blue text string "Car" exists in the Brown_Car image.

Copy code
'Create the coordinate variables to store the returned value
Dim l  'coordinate for left
Dim t  'coordinate for top
Dim r  'coordinate for right
Dim b  'coordinate for bottom
'Leave coordinates empty to search the entire image
imagePath = C:\Users\Public\Pictures\Brown_Car.jpeg
result = TextUtil.GetTextLocationFromImageByColor ("Car", imagePath, l, t, r, b, "0066CC", "FFFFFF", 10, false)
MsgBox result

Back to top

ResetABBYYParameters Method

Description

Resets ABBYY OCR recognition parameters.

Syntax

TextUtil.ResetABBYYParameters()

Return Value

None

IMPORTANT

  • You can use this method to return to the global ABBYY OCR settings after using custom ABBYY settings (SetABBYYParameters) for part of the test run.

  • UFT One 2021 R1 or later: To use this method, the ABBYY OCR engine has to be included in the UFT One installation.

The following example first sets ABBYY parameters to retrieve more texts from the Brown_Car image and then resets these parameters as the result did not turn out as expected: 

' Set the ABBYY parameter enableAggressiveTextExtraction to extract as much text on the image as possible
TextUtil.SetABBYYParameters("enableAggressiveTextExtraction", True)
' Set the ABBYY parameter removeGarbage to remove garbage from the image during text extraction
TextUtil.SetABBYYParameters("removeGarbage", True)
CarText = TextUtil.GetTextFromImage("C:\Users\Public\Pictures\Brown_Car.jpeg", 0, 0, 50, 50)
MsgBox CarText
' Find that the retrieved text did not turn out as expected. Reset ABBYY parameters
TextUtil.ResetABBYYParameters

Back to top

SetABBYYParameters Method

Description

Sets ABBYY OCR recognition parameters for the current test run.

Syntax

TextUtil.SetABBYYParameters(ParamName, Enable, [EnumIndex])

Argument

Type

Description

ParamName

String

The text recognition parameter you want to set for ABBYY OCR engine.

Possible Values:

  • detectTextOnPictures

    Instructs the ABBYY OCR engine to detect all text on a page image, including text embedded into figures and pictures.

  • enableAggressiveTextExtraction

    Instructs the ABBYY OCR engine to extract as much text on the image as possible.

  • enableTextExtractionMode

    Instructs the ABBYY OCR engine to extract text from text blocks.

  • oneWordPerLine

    Instructs the ABBYY OCR engine to recognize the lines of text as a single word.

  • fastObjectsExtraction

    Instructs the ABBYY OCR engine to speed up objects extraction.

  • removeGarbage

    Instructs the ABBYY OCR engine to remove garbage from the image during objects extraction.

  • removeTexture

    Instructs the ABBYY OCR engine to remove the background noise from a temporary image used for recognition.

  • useFastBinarization

    Instructs the ABBYY OCR engine to use fast image binarization.

  • correctSkew

    Instructs the ABBYY OCR engine to correct skew during image preparation.

  • prohibitColorImage

    Instructs the ABBYY OCR engine to use only black-and-white plane during objects extraction.

  • discardColorImage

    Instructs the ABBYY OCR engine to leave only black-and-white plane in the prepared image.

  • fastMode

    Instructs the ABBYY OCR engine to provide faster recognition speed.

  • lowResolutionMode

    Instructs the ABBYY OCR engine to recognize a text on an image with low resolution.

  • prohibitItalic

    Instructs the ABBYY OCR engine to not recognize letters printed with italic-styled font.

  • prohibitSubscript

    Instructs the ABBYY OCR engine to not recognize subscript letters.

  • prohibitSuperscript

    Instructs the ABBYY OCR engine to not recognize superscript letters.

  • prohibitHyphenation

    Instructs the ABBYY OCR engine to prohibit recognition of hyphenation from line to line.

  • caseRecognitionMode

    Specifies the mode of letter case recognition.

  • fieldMarkingType

    Specifies the type of marking around letters (for example, underline, frame, box).

Enable

Boolean

Indicates whether to enable the ABBYY parameter.

Possible values:

  • True

  • False

EnumIndex

Integer

Optional. The index number of the value of the ABBYY parameter in an enumeration.

This argument is mandatory when you set bsParameter to caseRecognitionMode or fieldMarkingType.

Possible values when you set bsParameter to caseRecognitionMode:

  • 0: Auto Case

  • 1: Lower Case

  • 2: Upper Case

Possible values when you set bsParameter to fieldMarkingType:

  • 0: Simple Text

  • 1: Underlined Text

  • 2: Text In Frame

  • 3: Gray Boxes

  • 4: Char Box Series

  • 5: Simple Comb

  • 6: Comb In Frame

  • 7: Partitioned Frame

Return Value

None

IMPORTANT

  • After using custom ABBYY settings for part of the test run, you can use ResetABBYYPrameters to return to the global ABBYY OCR settings.

  • UFT One 2021 R1 or later: To use this method, the ABBYY OCR engine has to be included in the UFT One installation.

TextUtil.SetABBYYParameters "detectTextOnPictures", True

TextUtil.SetABBYYParameters "enableAggressiveTextExtraction", True

TextUtil.SetABBYYParameters "enableTextExtractionMode", False

TextUtil.SetABBYYParameters "oneWordPerLine", False

TextUtil.SetABBYYParameters "fastObjectsExtraction", False

TextUtil.SetABBYYParameters "removeGarbage", False

TextUtil.SetABBYYParameters "removeTexture", True

TextUtil.SetABBYYParameters "useFastBinarization", False

TextUtil.SetABBYYParameters "correctSkew", True

TextUtil.SetABBYYParameters "prohibitColorImage", False

TextUtil.SetABBYYParameters "discardColorImage", False

TextUtil.SetABBYYParameters "fastMode", False

TextUtil.SetABBYYParameters "lowResolutionMode", False

TextUtil.SetABBYYParameters "prohibitItalic", False

TextUtil.SetABBYYParameters "prohibitSubscript", False

TextUtil.SetABBYYParameters "prohibitSuperscript", False

TextUtil.SetABBYYParameters "prohibitHyphenation", False

TextUtil.SetABBYYParameters "caseRecognitionMode", True, 1

TextUtil.SetABBYYParameters "fieldMarkingType", True, 0

See also: