ExampleCitrix Synchronization Functions

Waits until specified text is displayed around the specified position.

int ctrx_sync_on_text( long xpos, long ypos, const char *value, eObjAttribute textEvent, const char *window_name, [CONTINUE_ON_ERROR,] CTRX_LAST );

xposThe horizontal distance in pixels from the left border of the ICA client window.
yposThe vertical distance in pixels from the upper border of the ICA client window.
valueThe text to for which to wait.
textEventTEXT to sync with object, CAPTURE to use saved text in box, or CAPTURE_LINE to use saved text in narrow box.
window_nameThe window title. The asterisk wildcard character (*) can be used in window_name.
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.

ctrx_sync_on_text is a synchronization function that waits for a specified string to appear at the specified position before continuing.

  • 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).
  • The Citrix agent supports text-trapping functions (ctrx_sync_on_text, ctrx_sync_on_text_ex, and ctrx_get_text) only on Windows 8.1 and Windows Server 2012 R2.

The xpos, ypos are relative to the window if defined or to the ICA client if window_name is null.

When ctrx_sync_on_text is recorded, the textEvent argument is set by the logic of the recording engine. Do not edit it.

If you wish to enter the function manually, run the script once using ctrx_get_text to find the exact string. Then, comment out the ctrx_get_text call and enter the string as the value argument in the ctrx_sync_on_text call. Use CAPTURE or CAPTURE_LINE as the textEvent argument.

When CAPTURE is used as the textEvent argument, ctrx_sync_on_text reads the text within a rectangle of 80 by 80 pixels centered on the coordinates passed in the first 2 parameters. When CAPTURE_LINE is used, a rectangle of 80 by 10 pixels is read.

When TEXT is used as the textEvent argument, ctrx_sync_on_text waits for the appearance of an object at the given coordinates whose text property is the value. To use TEXT, you must know the properties of the underlying object. Therefore, TEXT is generally not used when manually enhancing a script.

ctrx_sync_on_text function is recorded automatically before each mouse click and double click.

Return Values

Citrix ICA Return Values


No parameterization is available for this function.


In this example, ctrx_sync_on_text causes script execution to pause until the text "OK" appears at the location of the command button.

            ctrx_sync_on_text(421, 368, "OK", TEXT, "NULL=snapshot67", CTRX_LAST );
ctrx_obj_mouse_click("<class=Button text=OK>", 421, 368, LEFT_BUTTON, 0, "NULL=snapshot67", CTRX_LAST );