Customizing the Recording Process

Overview

The Phantom recorder is able to incorporate script text that you provide into recorded scripts. This can be an alternative to editing the scripts after recording if a large number of similarly modified scripts must be created.

Your script text can replace or add to the script text automatically generated by the recorder in eight places in the recorded script:

IncludeFile statements - You can provide any number of IncludeFile statements to be automatically included in your recordings.

The Init subroutine - You can provide a replacement for the default Init subroutine provided by the recorder.

The TimeoutError procedure - You can provide a replacement for the default timeout handler procedure provided by the recorder when the Include timeout checks in recordings checkbox is checked in the The Phantom Options Dialog.

The SetWindow procedure - You can provide a replacement for the default SetWindow statement provided by the recorder. (During playback SetWindow causes the script to pause until a specified window appears and then reposition and resize the window to the location and dimensions that it had during recording.)

The WaitForWindowClose procedure - You can provide a replacement for the WaitForWindowClose statement provided by the recorder. (During playback, WaitForWindowClose causes the script to wait for a specified window to close.)

The WaitForMatch procedure - You can provide a replacement for the default WaitForMatch statement provided by the recorder when the an image match operation is specified during recording. (During playback WaitForMatch causes the script to wait until the content of a specified rectangle on the screen matches what it contained when the script was recorded.)

Termination statements - You can provide your own termination statements to replace the ExitScript statement normally provided by the recorder.

Additional procedures - You can provide any number of additional procedures to be included in your recorded scripts. (This is an alternative to using procedure libraries and IncludeFile statements.)

Script text for each of these is placed in a separate file in the RecordIncludeFiles subdirectory of the main Phantom directory. The file names must be the following:

IncludeFileStatements.txt
InitSubroutine.txt
TimeoutErrorProcedure.txt
SiteSetWindow.txt
SiteWaitForWindowClose.txt
SiteWaitForMatch.txt
TerminationStatements.txt
AdditionalProcedures.txt

If a file is not present in the subdirectory, the default script text is provided by the recorder. Thus, you need only provide script files for those areas that you wish to customize.

Care must be taken when preparing script text to be included by the recorder, as it is possible to introduce bugs and produce invalid scripts when this is done.

Script text included by the recorder is commented with the filename from which it was taken so that it can be easily identified.

IncludeFileStatements.txt

This file should contain comments and IncludeFile statements only. No other PhantomScript statements should be placed in this file.

InitSubroutine.txt

Except for comments, this file must begin with an Init: label and end with a Return statement. It is usually best to modify a copy of the Init subroutine provided by the recorder when preparing this file:

Init:
          SetPhantom Normal LoggingOn ErrorPopupsOn ContinueOnError 
          SetStringEscapeCharacter ~ 
          CapsLockOff 
          NumLockOff 
          ScrollLockOff 
          Return 

TimeoutErrorProcedure.txt

This file must contain a single procedure named TimeoutError that accepts two arguments: Action and TimoutSecs. This procedure is called when a timeout occurs in a SetWindow, WaitForWindowClose, or WaitForMatch statement. The Action argument receives the text "open", "close", or "match" depending on which statement produced the timeout. The TimeoutSecs argument receives the value of the Timeout parameter of the statement that timed out. For SetWindow and WaitForWindowClose statements, the intrinsic variables LastWindowCaption and LastWindowClass contain the values provided to the timed out statement's Class and Caption parameters identifying the window for which the timeout occurred.

Here is the default TimeoutError procedure provided by the recorder.

          Procedure TimeoutError ArgList=Action,TimeoutSecs 
            If Action="match" Then 
              ScriptError "Timed out waiting " & 
                TimeoutSecs & " seconds for an image match." 
            Else 
              ScriptError "Timed out waiting " & 
                TimeoutSecs & " seconds for window to " & 
                Action & ":~n" & "~tWindow Caption:~t" & LastWindowCaption & 
                  "~n" & "~tWindowClass:~t" & LastWindowClass 
            EndIf 
          EndProcedure 

SiteSetWindow.txt

This file must contain a procedure named SiteSetWindow that accepts four arguments: LTWHS, WCaption, WClass, and Seconds. The LTWHS argument receives the Left-Top-Width-Height-Show argument for the SetWindow statement. WCaption and WClass receive the Caption and Class arguments for SetWindow, and Seconds receives the Timeout argument for SetWindow. (If the Seconds argument is zero, then timeout checks were not enabled during recording of the script.)

The SiteSetWindow procedure should execute a SetWindow statement before returning as well as any other desired actions.

Important: If a SiteSetWindow procedure is provided, a SiteWaitForWindowClose procedure must also be provided.

Here is an example SiteSetWindow procedure that performs the minimum processing required to emulate the SetWindow statement that it replaces.

          Procedure SiteSetWindow ArgList=LTWHS,WCaption,WClass,Seconds 
            If Seconds=0 Then 
              SetWindow LTWHS Caption=WCaption Class=WClass 
            Else 
              SetWindow LTWHS Caption=WCaption Class=WClass Timeout=Seconds 
              If TimedOut Then 
                TimeoutError Action="open" TimeoutSecs=Seconds 
              EndIf 
            EndIf 
          EndProcedure 

SiteWaitForWindowClose.txt

This file must contain a procedure named SiteWaitForWindowClose that accepts three arguments: WCaption, WClass, and Seconds. WCaption and WClass receive the Caption and Class arguments for the WaitForWindowClose statement, and Seconds receives the Timeout value. (If the Seconds argument is zero, then timeout checks were not enabled during recording of the script.)

The SiteWaitForWindowClose procedure should execute a WaitForWindowClose statement before returning as well as any other desired actions.

Important: If a SiteWaitForWindowClose procedure is provided, a SiteSetWindow procedure must also be provided.

Here is an example SiteWaitForWindowClose procedure that performs the minimum processing required to emulate the WaitForWindowClose statement that it replaces.

          Procedure SiteWaitForWindowClose ArgList=WCaption,WClass,Seconds 
            If Seconds=0 Then 
              WaitForWindowClose Caption=WCaption Class=WClass 
            Else 
              WaitForWindowClose Caption=WCaption Class=WClass Timeout=Seconds 
              If TimedOut Then 
                TimeoutError Action="close" TimeoutSecs=Seconds 
              EndIf 
            EndIf 
          EndProcedure 

SiteWaitForMatch.txt

This file must contain a procedure named SiteWaitForMatch that accepts three arguments: LTRB, MFile and Seconds. LTRB receives the Left-Top-Right-Bottom argument of the WaitForMatch statement, BMPFile receives the file argument, and Seconds receives the Timeout value. (If the Seconds argument is zero, then timeout checks were not enabled during recording of the script.)

The SiteWaitForMatch procedure should execute a WaitForMatch statement before returning as well as any other desired actions.

Here is an example SiteWaitForMatch procedure that performs the minimum processing required to emulate the WaitForMatch statement that it replaces.

          Procedure SiteWaitForMatch ArgList=LTRB,BMPFile,Seconds 
            If Seconds=0 Then 
              WaitForMatch LTRB BMPFile 
            Else 
              WaitForMatch LTRB BMPFile Timeout=Seconds 
              If TimedOut Then 
                TimeoutError Action="match" TimeoutSecs=Seconds 
              EndIf 
            EndIf 
          EndProcedure 

TerminationStatements.txt

This file may contain any PhantomScript statements but should end with either the ExitScript or ExitPhantom statement.

AdditionalProcedures.txt

This file should contain only PhantomScript procedures. Any number of procedures may be included in the file. Note that this is an alternative to using procedures contained in files included using the IncludeFileStatements.txt file.