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:

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

Method GetText Returns the text from the specified window handle area.
Method GetTextFromImage

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

Supported in UFT One versions 15.0.1 and later.
Method GetTextLocation Checks whether the text string is contained in the window area and returns the string's location.
Method GetTextLocationFromImage

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.

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.

Example: Notes:

  • 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 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

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

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

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 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

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

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

See also: