# $Id: README,v 1.1.1.1 2004/03/09 15:36:16 clif Exp $
# $Log: README,v $
# Revision 1.1.1.1  2004/03/09 15:36:16  clif
# The initial TkReplay from Crowley's website.
#
# Revision 1.2  1996/07/31  16:18:22  crowley
# This is the 1.1 revision of tjreplay.  Lots of small changes.
# Most of them from Dean Brettle.  Connecting and replay are
# faster.  Socket support has been added.
#
# Revision 1.1  1996/07/29  22:47:41  crowley
# Initial revision
#
              TkReplay: A TK RECORD AND REPLAY FACILITY
                    Version: 1.1
                    1 August 1996


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 it
(or you can request that it be played faster).

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


CHANGES from TkReplay1.0 to TkReplay1.1

1. Dramatic speed up in connection speed.  Some speedup in replay speed.
2. break and continue bugs fixed.
3. Uses environment variables to find wish and libraries.
4. Now works for Itcl2 and wish4.0.
5. Sockets a little easier to use.


CHANGES from TkReplay1.0b4 to TkReplay1.0

1. Added the ability to use sockets instead of the send command.
2. Fixed bugs in using after.
3. Changed WarpPointer into a loadable extension.



TCL/TK VERSIONS REQUIRED

TkReplay requires Tcl 7.4 and Tk 4.0.  Tcl 7.5 is required in order to 
dynamically load the WarpPointer extension.


LOADABLE EXTENSION (WARPPOINTER) TO WISH IS USEFUL BUT NOT 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 loadable extension to wish that includes that C
procedure.  You can use TkReplay without pointer warping and not use the
WarpPointer extension.

The directory WarpPointer contains the loadable extension.  The README in
that directory will tell you how to build it.


INSTALLING TKREPLAY

The four things you have to do to install the program are:
1. Untar the distribution into a directory.
2. If you plan to run TkReplay from a directory other than the distribution
     directory, set the environment variable REPLAY_LIBRARY to be the full path
     to the distribution directory.
3. If you plan to use an interpreter with a name other than wish4.1, set the
     environment variable REPLAY_WISH to be the name of the interpreter.
4. If you plan to use pointer warping you have to create the loadable
     extension to wish (WarpPointer).


USING SOCKETS INSTEAD OF THE SEND COMMAND

The "send" command only works in UNIX, not on PCs or Macs.  I have
included code to allow the use of sockets to simulate the send command.
This requires more setup than using send.  It requires the following
steps to use:

(1) TkReplay needs to know the name of the application it will be
    recording and the port numbers to use.  Start TkReplay with:
        tkreplay.tcl -usesockets tkreplay_port app_name app_port
    for example:
        tkreplay.tcl -usesockets 3010 test1.tcl 3020

(2) Add the following lines near the beginning of the application
    you are recording:
        source socksend/socksend.tcl
        sockappsetup app_port tkreplay.tcl tkreplay_port
    for example:
        source socksend/socksend.tcl
        sockappsetup 3020 tkreplay.tcl 3010
    Look at test1.tcl for an example of this.


If you want to connect to more than one application you have to choose
a third port number, modify tkreplay.tcl (add another socksendopen), and
create a different socksend/sockapp2.tcl for the second application to source.

Most the examples have to be changed to work with sockets.  You have to
add the source command.  The scripts will still work unless you change
the name of the application.


PLAYING A SAMPLE SCRIPT

I have included a sample program and script that you can try replaying.
Run it with the command:
    tkreplay.tcl -app test1.tcl test1.scr -play
    

USING TKREPLAY

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

(1) Start test1.tcl with:
         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:
         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.
Here are some more you can try.

To run the same demo faster
    tkreplay.tcl -app test1.tcl test1.scr -playfast

To run the same demo even faster
    tkreplay.tcl -app test1.tcl test1.scr -mousespeed warp -playfast

To play a demonstration:
    tkreplay.tcl -app "ste.tcl ste.ex0" ste.demo.scr -play

To play a regression test:
    tkreplay.tcl -app "ste.tcl ste.ex1" ste.test.scr -play

To play a demonstration where two programs are controlled:
    tkreplay.tcl -app test2.tcl -app test3.tcl twotargets.scr -play

The other scripts use the "widget" demo distributed with Tk.  Go into the
subdirectory TkDemo and play some of the .all scripts.  For example:
  1. Go into TkDemo
  2. Start up the "widget" demo
  3. Connect TkReplay to widget
  4. Load the script "Tk.labels.all"
  4. Play


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

Comments and bug reports are very welcome.
