ctrx_sync_on_bitmap_change

ExampleCitrix Synchronization Functions

Waits until a bitmap changes.

int ctrx_sync_on_bitmap_change( long x_start, long y_start, long width, long height, [int Initial Wait Time,] [int Timeout,] [const char * Initial Value,] [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.
Initial Wait TimeThe initial time to wait before the starting to check the bitmap for changes. Default: 0 seconds.
TimeoutThe period to wait for any changes to occur in the bitmap. Default: 0 seconds
Initial Value The hashed string representing the value of the bitmap that must change.
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_LASTA marker that indicates the end of the argument list.

ctrx_sync_on_bitmap_change is a synchronization function that waits for a specified bitmap to change before continuing. It 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 automatically generated instead.

ctrx_sync_on_bitmap_change captures a snapshot of an active bitmap when called and waits for that bitmap to change. However, if the bitmap changed before the call, it captures the new bitmap after the expected change has already occurred, and synchronizes on this bitmap. In this case, the function will fail on timeout.

If it is possible in your application for the bitmap to change before the call, use the Initial Value argument. Capture the bitmap before the change with ctrx_get_bitmap_value. Use the output buffer from ctrx_get_bitmap_value as the Initial Value. If the value of the bitmap when ctrx_sync_on_bitmap_change is called is the same as the Initial Value, the script will wait for the bitmap to change. If the bitmap is any other value, the script will continue without waiting.

Example:

// At some point before the bitmap changes

ctrx_get_bitmap_value(x_start, y_start, width, ht, capture_bmap);

// Later when you want to wait for the change

ctrx_sync_on_bitmap_change(x_start, y_start, width, ht,

    0, 10, capture_bmap, CTRX_LAST );

Note: The optional arguments must be passed in the order given. To use any of the optional arguments, all preceding optional arguments must also be passed. For example, if you pass an Initial Value, you must first pass values for the Initial Wait Time and the Timeout.

Tip: ctrx_sync_on_bitmap_change 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. VuGen automatically records the function as ctrx_sync_on_bitmap. After recording has finished, edit the name of the function to ctrx_sync_on_bitmap_change and remove the final arguments to match its parameters.

Return Values

Citrix ICA Return Values

Parameterization

No parameterization is available for this function.

Example

The following example launches Microsoft's Internet Explorer after connecting to the Citrix server ludens. The test run 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_change 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 deemed a success.

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

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

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

     lr_start_transaction("news_item");

     /* 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);
     lr_think_time(7);

     /* 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 to appear */
     rc = ctrx_sync_on_bitmap_change(137, 211, 51, 17, CTRX_LAST );

     if (rc != E_OK) 
          lr_end_transaction("news_item", LR_FAIL);
     else
          lr_end_transaction("news_item", LR_PASS);

     /* 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);
     lr_think_time(12);
     ctrx_disconnect_server("ludens", CTRX_LAST);

     return 0;
}