CitrixWaitForText Function

Action

This function uses optical character recognition (OCR) to synchronize subsequent user actions. Based on provided parameters, this function waits until the provided text pattern appears on the specified location.

Use TrueLog Explorer to insert this synchronization call.

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: Text 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).

When optional font parameters are present, the pattern file is checked to see if the selected font is available. When font parameters are omitted font checking is not performed.

For successful text conversion it is necessary to use the perfOcrFonts.dat and perfOcrPattern.pat configuration files, which contain used fonts in the correct size and format. These files must be added to the Data Files section of the project (both files are located at <public user documents>\Silk Performer 21.0\Data). If the files are not available, or do not contain the correct specifications, they can be generated or updated using the OCR dialog in the Citrix System Settings.

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

Include file

CitrixAPI.bdh

Return value

true if successful
false otherwise

Syntax

CitrixWaitForText(  in  sText        : string,
                    in  nWindow      : number,
                    in  nX           : number,
                    in  nY           : number,
                    in  nWidth       : number,
                    in  nHeight      : number,
                    in  nMatch       : number,
                    in  sFont        : string  optional,
                    in  nFontSize    : number  optional,
                    in  nFontFlags   : number  optional,
                    in  nTimeout     : number  optional,
                    in  bNoError     : boolean optional,
                    out sResult      : string  optional, 
                    in  nPolling     : number  optional ): boolean;

Parameter	Description
sText	String or string pattern to wait for.
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.
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. In the optional flag MATCH_IfDifferent is added to the value the function waits until the OCR result does not match the provided string or string pattern any more.
sFont	Font that should be checked for on the system and in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If a specified font is not on the operating system, then it must be installed. If the provided configuration files do not contain the font, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted font checking is not performed.
nFontSize	The font size that should be checked for in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If the provided configuration files do not contain the font size, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted, font-size checking is not performed.
nFontFlags	Specifies the font shape (bold, italic, or underlined) that should be checked for in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If the provided configuration files do not contain the specified font shapes, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted, font-shape checking is not performed. Specify any combination of the following values: FONT_FLAG_Italic FONT_FLAG_Bold FONT_FLAG_Underlined
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.
sResult	Retrieves the result of the OCR conversion.
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 setting overrides the `CitrixSetOption(CITRIX_OPT_ScreenTextPolling)` polling interval.

Example:

transaction TMain
var
  sResult  : string;
begin
  CitrixInit(800,600); // do not change the resolution
  CitrixConnect("server","John",Decrypt("8V6F"),"",COLOR_256);
  CitrixWaitForLogon();
  CitrixWaitForText("St*",DESKTOP,20,579,35,16,MATCH_Wildcard,null,0,0,0,false,sResult);
  print(sResult);
  CitrixDisconnect();
end TMain;