TextUtil Object
Description
The object used to recognize text within a specified window handle.
IMPORTANT
When possible, it is recommended to use alternative methods of capturing 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 Unified Functional Testing 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
![]() | Returns the text from the specified window handle area. |
![]() | Returns the text from a specified area in an image file. Supported in UFT One versions 15.0.1 and later. |
![]() | Checks whether the text string is contained in the window area and returns the string's location. |
![]() | Checks whether the text string is contained in the image file and returns the string's location. Supported in UFT One versions 15.0.1 and later. |
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. Example: Notes:
|
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, it is recommended to use alternative methods of capturing 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, the APIs used in your application, and so on. Therefore, when possible, it is highly recommended to use alternative ways 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)
GetTextFromImage Method
Supported in UFT One versions 15.0.1 and later.
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, it is recommended to use alternative methods of capturing 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, the APIs used in your application, and so on. Therefore, when possible, it is highly recommended to use alternative ways 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
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.
|
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 also returns the exact coordinates of the specified text to the supplied arguments (the returned coordinates overwrite the supplied ones).
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, the APIs used in your application, and so on. Therefore, when possible, it is highly recommended to use alternative ways 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 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
GetTextLocationFromImage Method
Supported in UFT One versions 15.0.1 and later.
Description
Checks whether a specified text string is contained in a specified image file. If the text string is located, the location coordinates are also returned.
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 also returns the exact coordinates of the specified text to the supplied arguments (the returned coordinates overwrite the supplied ones).
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, the APIs used in your application, and so on. Therefore, when possible, it is highly recommended to use alternative ways 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 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
See also:
- Crypt Object
- DataTable Object
- Description Object
- DotNetFactory Object
- DTParameter Object
- DTSheet Object
- Environment Object
- Extern Object
- Parameter Object
- MercuryTimers Object (Collection)
- MercuryTimer Object
- NV Object
- OptionalStep Object
- ParallelUtil Object
- LocalParameter Object
- PathFinder Object
- Properties Object (Collection)
- QCUtil Object
- RandomNumber Object
- Recovery Object
- Remote Connection Object
- Reporter Object
- RepositoriesCollection Object
- Repository Object
- Services Object
- Setting Object
- SystemMonitor Object
- TestArgs Object
- TextUtil Object
- UIAutomation Object
- VisualRelation Object
- VisualRelations Object
- VisualRelationsCollection Object
- WebUtil Object
- XMLUtil Object