Get Text

A Get text building block gets text that isn’t known in advance from the whole screen or part of the screen. Formatting and filtering rules can be applied so that for instance only text which is formatted as “Status: [TEXT] today” and which starts with “Green”.

See the Capture text on screen lesson for examples of how to use the Get text block. Similar functionality is provided in the Get number block, and an example of this can be seen in the Use Numbers and Variables video.

Fully expanded, the Get text block shows the following properties:

Get text building block, expanded to show all properties

The Block Header (“Get text”)

The green input connector in the header is used to trigger the block to start executing.

The green output connector in the header triggers when the text has been retrieved. If “All occurrences” of the “Use occur.” property is selected (see below), this output connector triggers on each iteration until all occurrences are iterated through.

The title of the block (“Get text”) can be changed by double-clicking on it and typing in a new title.

Area

An area of the screen where the text will be searched for in X, Y, Width, Height coordinates, starting with the upper-leftmost pixel. The top-left corner of the screen is position 0, 0. If no area is defined, the entire screen is searched.

It’s possible to enter the area values manually, but the area can also be captured by right-clicking the property and selecting “Capture area”. See the Getting Started 2/2 video for an example of how this works.

Click the expander button to work with the area’s position and size and their nested sub-properties separately.

Text found

The text that was retrieved from the screen, subject to the optional formatting and filtering settings (see below).

Not Found

This green output connector triggers if a piece of text is not found before the timeout, subject to the optional formatting and filtering settings (see below). This is typically used to branch execution flow or to explicitly fail a case by linking it to a Fail block.

Position found

The screen position where the text was found in X, Y coordinates. The top-left corner of the screen is position 0, 0.

Note that this position is the middle of the text retrieved, not the upper-leftmost pixel of the text.

Click the expander button to work with the X and Y coordinates separately.

Area found

The screen area where the text was found in X, Y, Width, Height coordinates, starting with the upper-leftmost pixel. The top-left corner of the screen is position 0, 0.

Click the expander button to work with the area’s position and size and their nested sub-properties separately.

Find format

Define a format that the text must meet to be retrieved. For instance, by defining “Status: [TEXT] today” only text inside paragraphs such as “Status: Green Mode today” will be retrieved.

Is case sensitive

Select whether the text recognition should be case sensitive. By default, it is case insensitive.

Use dirty edge mode

Check this checkbox if the text is placed on top of a textured background or is close to a visual border element. This instructs the text recognition engine to use a special mode to compensate for such backgrounds and borders.

It should be noted that no text recognition engine is perfect. If you experience problems with text recognition, try zooming in on the content. Larger letters are typically easier to recognize.

Filter

Define a filter that the text must meet to be retrieved. For instance, only retrieve numbers that “Starts with” the word Green.

Filter value

The value used by the filter.

Use Occurrence

Select which occurrence of the text on screen to use, if more than one is found.

Select “All” to iterate through all of the occurrences. By selecting “All”, the sub-properties Current index and Completed are shown (see below).

Current index

The current index when iterating through all occurrences of the number on screen. For instance, if three occurrences are found, this property will contain 1 for the first one, then 2 for the second and finally 3 for the last one.

Completed

This green output connector triggers when the iteration of all occurrences are completed.

Timeout

The maximum time spent searching for the text before giving up and triggering “Not found” (see above).

The default value is 10 seconds.

Note: All cases have a “global timeout” that can be configured in the “Settings” panel. This is unrelated to the timeout of a single building block. However, a running case will automatically be cancelled if it runs for longer than the global timeout.

Scroll to find

When a value other than “None” is selected, the building block will use scrolling when searching for the text. This can be useful when searching in scrollable content such as web pages and documents.

Max repeats

The maximum number of times to perform a scroll before giving up searching for the text.

Amount

The amount of scrolling that will be performed on each scroll repeat.

Delay (sec)

The delay in seconds between each of the scroll amounts.

Await no movement

Delay the search for the text until there has been no movement on the screen for a specific period of time — for instance 2 seconds.

This is useful when waiting for a screen update to occur, for instance a page loading in a browser window. Regardless of this checkbox, the search will occur after waiting a maximum of 30 seconds.

Await Timeout

The number of seconds the screen must have seen no movement before proceeding.

Examples of usage:

Author: Claus Topholt, June 6, 2016.