Citrix ICA Vuser Functions (CTRX) > Alphabetical List of Functions > ctrx_sync_on_bitmap_change


Example: ctrx_sync_on_bitmap_change 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_start The horizontal distance, in pixels, of the bitmap's top left edge from the left border of the ICA client window.
y_start The vertical distance, in pixels, of the bitmap's top left edge from the upper border of the ICA client window.
width The width, in pixels, of the bitmap.
height The height, in pixels, of the bitmap.
Initial Wait Time The initial time to wait before the starting to check the bitmap for changes. Default: 0 seconds.
Timeout The 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 run-time setting for this step so that script behaves as though the run-time setting was Continue on error.
CTRX_LAST A 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.


// 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


No parameterization is available for this function.