ExampleCitrix Synchronization Functions

Waits until a bitmap appears.

int ctrx_sync_on_bitmap( long x_start, long y_start, long width, long height, char *hash, char* AddOffsetToInput, char* WaitFor, [CONTINUE_ON_ERROR,] CTRX_LAST );

x_startThe horizontal distance, in pixels, of the bitmap's top left edge from the left border of the ICA client window
y_startThe vertical distance, in pixels, of the bitmap's top left edge from the upper border of the ICA client window
widthThe width, in pixels, of the bitmap
heightThe height, in pixels, of the bitmap

A unique string hash that is automatically generated for the bitmap. This value can contain one hash or multiple hashes separated by the '|' character.

For example:

One hash value:

ctrx_sync_on_bitmap(182 , 287 , 18 , 10 , "daf780c43c09882744d4ee90177256c6", CTRX_LAST);

Two hash values, separated by a '|' character:

ctrx_sync_on_bitmap(182 , 287 , 18 , 10 , "daf780c43c09882744d4ee90177256c6|daf780c43c09882744d4ee90177256c6", CTRX_LAST);


  • The maximum number of multiple hash values that can be used is 10, the rest will be ignored.
  • The hash value is used as the snapshot file name. If the hash value is too long, or if multiple hash values are used, the file name may exceed the maximum allowed path length.

The offset is the change in position from where the image was found during the test run to where it is found when recorded.

This argument indicates whether to add the offset to subsequent input, for example, mouse-click coordinates. Possible values: Yes (add offset), No (do not add offset).


(Optional) The event to occur on one of the specified areas and images.

Possible values are:

  • Appear. (Default) The function waits for the specified area to match the specified text.
  • Change. The function waits for the specified area to match the specified text, and then not to match it. That is, the match is found and then the area changes so that it no longer matches.
  • NotAppear. The function returns LR_FAIL if the text appears before the function times out. If the timeout is reached and the text has not appeared, the function returns LR_PASS.

Note: When AddOffsetToInput is set to Yes, we do not recommend setting WaitFor to Change or NotAppear.

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_bitmap is a synchronization function that waits for a specified bitmap to appear before continuing.

This function is typically used when a change occurs in a window but the window name remains the same. If the window name changes, ctrx_set_window is recorded instead of ctrx_sync_on_bitmap.

The function can be manually recorded by clicking on the rectangle icon in VuGen's Citrix recording toolbar. The mouse pointer changes to a precision shape, which you use to select a bitmap area.

Return Values

Citrix ICA Return Values


No parameterization is available for this function.


The following example launches Microsoft's Internet Explorer after connecting to the Citrix server ludens. The script waits for the browser window to appear using ctrx_set_window.

The example then navigates to a URL that has a navigation frame. Every item in the frame loads another news story, but the title of the window ("News - Microsoft Internet Explorer") remains the same. Therefore, ctrx_set_window is not generated. In this case, a call to ctrx_sync_on_bitmap is inserted to wait for the change in the text that indicates that the new story has been loaded. If it loads successfully, the transaction news_item is a success.

Actions () {
     int rc;
     ctrx_connect_server("ludens", "test", "test", "ludens", CTRX_LAST);

     /* Launch the web browser by clicking on desktop IE icon */
     ctrx_mouse_double_click(34, 325, LEFT_BUTTON, 0, NULL, CTRX_LAST);

     /* Wait for browser window to appear */
     ctrx_set_window("Nasdaq liveQUOTES - Microsoft Internet Explorer", CTRX_LAST);

     /* Go to the "NEWS" tab */
     ctrx_mouse_click(133, 186, LEFT_BUTTON, 0, 
               "The Nasdaq Stock Market - Microsoft Internet Explorer", CTRX_LAST);

     ctrx_set_window("News - Microsoft Internet Explorer", CTRX_LAST);

     /* Click on a news item in the left frame */
     ctrx_mouse_double_click(198, 320, LEFT_BUTTON, 0, 
               "News - Microsoft Internet Explorer", CTRX_LAST);

     /* Wait for news item to appear */
     rc = ctrx_sync_on_bitmap(137, 211, 51, 17,
                "18d962dcbf373e948e83489a19419512", "AddOffsetToInput=Yes", "WaitFor=Appear", CTRX_LAST);

     /* Exit the web browser by clicking on top left Exit check box */
     ctrx_mouse_click(573, 61, LEFT_BUTTON, 0, 
               "Welcome to MSN.com - Microsoft Internet Explorer", CTRX_LAST);

     ctrx_disconnect_server("ludens", CTRX_LAST);
     return 0;