CitrixWaitForScreen Function

Action

This function uses screen appearance to synchronize subsequent user actions. Based on provided parameters, this function waits until the image in the specified screen region changes, matches the captured hash value(s), or does not match the hash value(s). To compare the actual screen region with the provided hash value(s), it is necessary that the color depth used during recording be identical to that used during replay.

The screen region can be specified absolutely or relatively to a window (by specifying a window handle). When only a window handle, and no position or size, is provided, the region specified by the window outline is used.

Note: Screen synchronization is only possible in Normal Mode (see CitrixInit). When used in Fast Mode this function waits a specified period of time (configurable through a call to CitrixSetOption). In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForScreen( in nWindow  : number,
                     in nX       : number,
                     in nY       : number,
                     in nWidth   : number,
                     in nHeight  : number,
                     in sHash    : string optional,
                     in bUnequal : boolean optional,
                     in nTimeout : number optional,
                     in bNoError : boolean optional,
                     in nPolling : number optional ) : boolean;

Return value

true if successful
false otherwise

Parameter	Description
nWindow	Window handle returned by a call to `CitrixWaitForWindowCreation`. Use `DESKTOP` to specify a region relative to the desktop.
nX	X coordinate of the left margin of the screen region.
nY	Y coordinate of the top margin of the screen region.
nWidth	Width of the region.
nHeight	Height of the region.
sHash	Captured hash value, to which the specified region should be compared (optional). This can also be a list of hash values separated by one of the following characters: `, ; \| /` Omit this parameter to synchronize on any change in the region.
bUnequal	Set this parameter to `true` to wait for the specified region to mismatch the provided hash value.
nTimeout	Specify the time in milliseconds to wait for the screen region to reach the correct appearance (optional). When this parameter is omitted or set to `0`, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the `CitrixSetOption` function.
bNoError	Set this parameter to `true` to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.
nPolling	Specify the polling period in milliseconds that the Citrix Replay engine will wait to poll a screen for an update (`0` means no polling). If omitted, the parameter is set to `1000`. This parameter needs to be set to wait for any change in the specified region, rather than waiting for a specific change as defined by the sHash parameter. This setting overrides the `CitrixSetOption(CITRIX_OPT_ScreenTextPolling)` polling interval.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("citserver", "user", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(3.31);
    CitrixMouseClick(214, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(112, 16, DESKTOP, MOUSE_ButtonLeft);
    hWnd9 := CitrixWaitForWindowCreation("Microsoft Excel – Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 460);
    CitrixWaitForScreen(hWnd9, 172, 137, 250, 148, "f100c8b71521fd895c23825b7f73a3a5|56a4337ff1aaf9ea477f0c5a2073dd2d", false);
    CitrixMouseClick(634, 9, hWnd9, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd9, EVENT_Destroy);
    ThinkTime(3.02);
    CitrixDisconnect();
  end TMain;