Share this page

# ctrx_get_text_location

Example | Information Retrieval Functions

Searches for a text in a selected area and retrieves the text location.

`int ctrx_get_text_location( LPCSTR window_name, long *xpos, long *ypos, long *width, long *height, LPSTR text, long bMatchWholeWordOnly, LPCSTR filename, [CONTINUE_ON_ERROR,] CTRX_LAST );`

window_name | The window title. NULL if not within an active window.
xpos, ypos | Input/output parameters that set the beginning of the search area and get the text location.
width, height | The extent of the search area that starts at xpos, ypos.
text | The string for which to search.
bMatchWholeWordOnly | A flag to indicate whether to search only for a whole word match only or not. The flag can be TRUE or FALSE. True = 1, False = 0.
filename | The snapshot filename or an empty string.
CONTINUE_ON_ERROR | A constant, entered as shown without quotes. Overrides the error behavior runtime setting for this step so that script behaves as though the runtime setting was Continue on error.
CTRX_LAST | A marker that indicates the end of the argument list.

Note: This function is available only if the Citrix agent is installed. For details, see Citrix agent overview in the VuGen Help Center (select the relevant version).

ctrx_get_text_location searches for the specified text in the area specified by xpos, ypos, width, and height. If the string is found, after the function returns, xpos, and ypos are the location at which the text was found. If the string is not found, xpos, and ypos are zero.

The search text is a single word. A search for a phrase including spaces will always fail.

The xpos, and ypos arguments are relative to the window. If the window name is NULL, they are relative to the ICA client.

The asterisk wildcard character (*) can be used in window_name.

The easiest way to use ctrx_get_text_location is to record a script, then use the snapshot to insert a ctrx_get_text call. xpos, ypos, width, height, and the snapshot filename can all be taken from the ctrx_get_text call and used in the ctrx_get_text_location call.

## Return Values

Citrix ICA Return Values

## Parameterization

No parameterization is available for this function.

## Example

This example shows the use of ctrx_get_text_location.

    long x_pos, y_pos, wid, ht;
    ctrx_sync_on_window("Desktop", ACTIVATE, 0, 0, 801, 601, "snapshot6", CTRX_LAST );
    /* ctrx_get_text used to get coordinates and snapshot file
        for later call to ctrx_get_text_location */

    ctrx_get_text(NULL, 289, 70, 100, 70, "snapshot1", text_buffer, CTRX_LAST );
    lr_message( "%s", text_buffer );
    x_pos = 289;
    y_pos = 70;
    wid = 100;
    ht = 70;
    ctrx_get_text_location(NULL, &x_pos, &y_pos, &wid, &ht,
        "Documents", TRUE, "snapshot1", CTRX_LAST );

    lr_message( "%ld, %ld, %ld, %ld ",x_pos,y_pos, wid, ht );

    if (x_pos == 0 && y_pos == 0 && wid== 0 && wid == 0 )
        lr_message("'Documents' not found");
    else
        lr_message("'Documents' found at %d, %d, %d, %d", x_pos, y_pos, wid, ht );

    Example: Output:
    Starting action Action.
    Action.c(7): ctrx_sync_on_window("Desktop")
    Action.c(9): ctrx_get_text(".My Documents")
    .My Documents
    Action.c(18): ctrx_get_text_location(319 , 116 , 52 , 8)
    319, 116, 52, 8
    'Documents' found at 319, 116, 52, 8

Tips to improve your search results... VuGen Function Reference Version 25.1-25.3 Function Reference 25.1-25.3 All View Local Help Center View Online Help Center Version: