TkReplay: A TK RECORD AND REPLAY FACILITY
                    Version: 1.0b1 (first beta)
                         22 June 1995

OVERVIEW

This distribution contains Tcl/Tk code that allows you to record a
script of actions and then replay them.  You can save a script
and later reload and replay it.  This is useful for regression
testing or for creating demonstrations of your software.  You can
add comments to the demonstration that will display at the proper time.
The demonstration is replayed at the same rate as you recorded i
(or you can request that it be played faster).

See the file "HelpFile" for a description of how to use the program.
See "rebind.notes" for some information about how the
program was written and what the problems were.


TCL/TK VERSIONS REQUIRED

TkReplay requires Tcl 7.4 and Tk 4.0.  Later versions may work but
TkReplay will NOT work with Tk 3.6.


SPECIAL VERSION OF WISH MAY BE REQUIRED

TkReplay works best when it can move the mouse pointer around during replays.
Since Tk does not provide for this I have to use a C procedure to call
XWarpPointer.  This requires a custom version of wish that includes that C
procedure.  You can use TkReplay without pointer warping and use the standard
wish.

The files WarpPointer.c and tkAppInit.c are included to make a the special
version of wish (called wpwish).  The Makefile knows how to make wpwish.
If you are already using a custom version of wish you can add pointer
warping to that by including WarpPointer.o in the load and adding lines
106-109 from my tkAppInit.c to your own tkAppInit.c.


INSTALLING TKREPLAY

The only thing you have to do to install the program is to untar the
distribution into a directory and change the hard-wired path name on
line 3 of tkreplay.tcl to point to the directory where you put the
TkReplay distribution.

If you plan to use pointer warping you have to create a special version of
wish which includes WarpPointer.o and the code to create the new commands.


PLAYING A SAMPLE SCRIPT

I have included a sample program and script that you can try replaying.
Run it with the command:
    wpwish tkreplay.tcl test1.scr
or if you want it to play quickly:
    wpwish tkreplay.tcl -fast test1.scr


USING TKREPLAY

As an example we will use "test1.tcl" which is included in the distribution.

(1) Start test1.tcl with:
         wish test1.tcl
     We will call test1.tcl the "target application"..
     (You can start TkReplay and the target application in either order.)
(2) Start the replay program with:
         wpwish tkreplay.tcl
(3) If you are NOT using pointer warping, then you should set some
     preferences.  Call up the user preferences dialog box with
     Edit/Preferences...  Select the option to follow the actions
     (on replay) with a big red arrow.
(4) You need to connect to the target application before you can record or
     replay.  Do this by selecting "test1.tcl" from the submenu of
     File/Connect to application...  It will take a few seconds to connect
     so wait for the message that the connect is made.  (On my slow machine
     it takes about 20 seconds.)
(5) Now you are ready to start recording.  Press the "Record" button in the
     row of buttons below the menu bar.  The recording light (a check button)
     will go on.
(6) Do some things with test1.tcl, press some buttons, scroll, etc.  As you
     do things you will see the input events recorded in the script below the
     record control buttons.  The time delay, event type and widget are
     shown.
(7) When you are done press the "Stop" button.
(8) To replay the script, first rewind it with "Rewind" and then press "Play".
     "Play Fast" skips the delays and does the actions as quickly as it can.
(9) To save a script, use File/Save as..., pick a file name and save it.
(10) You can load a script with File/Open...  Note that you must be
      connected to the target application to replay a script.

More information can be found in "HelpFile".

SOME OTHER SCRIPTS TO TRY

I have included some sample scripts to try.  One is described above.

The others use the "widget" demo distributed with Tk.  They are:
widget.labels.scr, widget.listboxes.scr, widget.labels.scr,
widget.text.scr, widget.canvases.scr and widget.scalesetc.scr.
To run them:
  1. start tkreplay.tcl
  2. load in the script you want to replay.
  3. start the widget demo
  4. connect to widget
  5. Play


NOTES:
    

AUTHOR:
    Charlie Crowley
    Computer Science Department
    Univ. Of New Mexico
    crowley@cs.unm.edu
    http://www.cs.unm.edu/~crowley/
       look here for the latest version.

Comments and bug reports are very welcome.