CitrixWaitForWindowCreation Function

Action

This function waits until a specified window appears or a specified timeout period expires. A window can be specified by its caption, whereas five different search options can be provided by the nMatch parameter. When the window to wait for does not have a caption, the style of the window is used to identify the correct window (nStyle).

When this function succeeds, it returns a (positive) window handle that must be used as the nWindow parameter throughout the Citrix functions.

When the newly created window has a different size than is specified by the nWidth and nHeight parameters (size of the window during recording), the window is resized to the specified size (otherwise recorded user actions wouldn’t work). When the position of the newly created window is different than that specified by the nX and nY parameters (position of the window during recording) and the bForcePos parameter is set to true, the window is moved to the correct position. When the bForcePos parameter is omitted or set to false, profile settings (Citrix / General/ Force window position) specify whether or not the window is moved.

This function is not only triggered by the creation of a window, but also by a (matching) caption change of an existing window.

In the case of a timeout error, reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForWindowCreation( in sCaption  : string,
                             in nMatch    : number optional,
                             in nStyle    : number optional,
                             in nX        : number optional,
                             in nY        : number optional,
                             in nWidth    : number optional,
                             in nHeight   : number optional,
                             in bForcePos : boolean optional,
                             in nTimeout  : number optional,
                             in bNoError  : boolean optional ) : number;

Return value

>= 0 if the function succeeds (0 for the desktop)
< 0 otherwise

Parameter	Description
sCaption	Caption of the window to wait for. It does not matter if the caption appears due to the creation of a new window or because of a caption change of an existing window.
nMatch	Specify one of the following values (optional): MATCH_Exact (default): Case-sensitive comparison. MATCH_ExactNoCase: Case-insensitive comparison. MATCH_Wildcard: The search string must either begin or end with a '' character, which matches everything. The rest of the string is compared case sensitively. MATCH_WildcardNoCase: The search string must either begin or end with a '' character, which matches everything. The rest of the string is compared case insensitively. MATCH_RegExp: The search string is a regular expression. See the regular expression chapter for a description of Silk Performer's regular expression capability.
nStyle	When a window doesn’t have a caption, the style parameter is used to identify the correct window (optional).
nX	X coordinate of the left margin of the window at recording (optional). When this parameter is provided and either the bForcePos parameter or the global setting (profile setting / Citrix / General/ Force window position) is set to `true`, the window is moved to this position.
nY	Y coordinate of the top margin of the window at recording (optional). When this parameter is provided and either the bForcePos parameter or the global setting (profile setting / Citrix / General/ Force window position) is set to `true`, the window is moved to this position
nWidth	The width of the window at recording (optional). When this parameter is provided, the window is resized to this width.
nHeight	The height of the window at recording (optional). When this parameter is provided, the window is resized to this height.
bForcePos	See description of nX / nY.
nTimeout	Specifies the time in milliseconds to wait for the appearance of the window (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.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd5, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(3.33);
    CitrixMouseClick(208, 193, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5, EVENT_Destroy);
    ThinkTime(2.45);
    CitrixMouseClick(41, 7, hWnd4, MOUSE_ButtonLeft);
    hWnd7 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96400000, 2, 193, 163, 263);
    CitrixMouseClick(48, 250, hWnd7, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd7, EVENT_Destroy);
    hWnd9 := CitrixWaitForWindowCreation("Shut Down Windows", MATCH_Exact, 0x94C808CC, 111, 96, 417, 192);
    CitrixWaitForWindow(hWnd9, EVENT_Activate);
    CitrixMouseClick(184, 165, hWnd9, MOUSE_ButtonLeft);
    CitrixWaitForDisconnect();
  end TMain;