                 TK RECORD AND REPLAY FACILITY

CONTENTS OF THIS HELP FILE:
    OVERVIEW
    THE TKREPLAY WINDOW
    HOW TO RECORD A SCRIPT
    HOW TO SAVE A SCRIPT
    HOW TO LOAD A SCRIPT
    HOW TO ADD A COMMENT
    HOW TO SEE A TRANSCRIPT OF ALL MESSAGES
    HOW TO REPLAY A SCRIPT
    HOW TO STOP A REPLAY
    HOW TO EDIT THE SCRIPT
    THE FILE MENU
    THE EDIT MENU
    THE PREFERENCES BOX
    THE RECORDER MENU
    THE RECORDER CONTROL BUTTONS
    KNOWN PROBLEMS
    HOW TO CONTACT THE AUTHOR

OVERVIEW: This program allows you to record and (later) replay scripts
  of user actions for any Tcl/Tk program.
  TkReplay requires Tcl7.4 and Tk4.0 (or later).
  This is version Version: 1.0b1 (first beta) of 20 June 1995.

THE TKREPLAY WINDOW:
  The top line is a message line which gives you feedback on what is
      happening in the program.
  The next line is a menu bar.
  The next two lines are the recorder control buttons.  They are intended
      to look a little like the buttons on a tape recorder.
  The next line gives the file name of the script
  The following list box shows the events currently in the script.  The
      selected event is the one about to be replayed.
  The bottom line indicates which applications TkReplay is currently
      connected to.

HOW TO RECORD A SCRIPT:
  1. Start the tcl/tk program you want to record, the "target application".
  2. Start TkReplay with the command:
      wpwish tkreplay.tcl
      (Note: wpwish is a version of wish with the WarpPointer command).
  3. Connect to the target application by choosing its name from the
      submenu in "File/Connect to application".
      It may take 10-20 seconds to connect.
  4. Press "Record" to start recording a script.
  5. The listboxes will display all the recorded events as you generate them.
  6. If you want to add a comment to the script, see HOW TO MAKE A COMMENT
       below.
  7. When you are done, press "Stop" to end recording.

HOW TO SAVE A SCRIPT:
  1. If you are happy with the name use "File/Save".  The name of the script
      is shown just above the list of events and just below the buttons.
  2. Choose "File/Save as..." to pick a new name for the script and save
      the script.

HOW TO LOAD A SCRIPT:
  1. Choose "File/Open..."
  2. You will see a typical file browser.
  3. Double click on the file name to load it.
  NOTE that loading may take some time if it is a large script,
      sometimes a minute or two.

HOW TO ADD A COMMENT:
  For a demonstration you will want to have comments that explain to the
  user what is going on.  You start a comment after a user input event
  and dismiss it after some later event.  On replay it will stay visible
  between those two events.
  
  1. During recording, press "Comment" and a dialog box will come up.
  2. Type in the text of the comment in the text widget provided.
  3. When you are satisfied with the text press "Text Done".
  4. Continue with the recording as long as you want the comment to
      remain visible on the screen during replay.
  5. When you want to comment to disappear press "Dismiss Comment".

HOW TO SEE A TRANSCRIPT OF ALL MESSAGES:
  1. Choose "Show messages" from the Help menu.
  
HOW TO REPLAY A SCRIPT:
  1. Start the target application you want to replay a script for.
  2. Start TkReplay with the command:
      wpwish tkreplay.tcl scriptName
  3. Or you can open the script after you start TkReplay.
  4. Connect to the target application.
  5. Press "Play" to play out the script. (Or "Play Fast" to replay at
      maximum speed.)

     The script will be replayed at the same rate that you recorded it.
     Actually it will be slower since the record/replay mechanism takes
     some extra time.  When you get to a comment you must press "Okay"
     to continue.  You can see the events in the listboxes as they are
     being replayed.  Notice that everything you did is recorded, even
     the extraneous enter and exit events that you generate when you move
     the mouse over widgets.
     
HOW TO STOP A REPLAY:
  It may be hard to stop a replay in the middle if it is taking control
  of the mouse because you cannot get the mouse to the right window to change
  the focus.  There is an escape mechanisms to deal with this problem.
  
  If you click mouse button 1 (the left mouse button) or press the Escape
  key during a replay, the replay will stop at the end of the current
  action.  This may take a few seconds, especially if it has to move the
  mouse some distance.  You can restart from where you left off just by
  pressing "Play" again.
  
HOW TO EDIT THE SCRIPT:
   You can make some small edits in the script within the TkReplay program.
   The editing commands are on the Edit menu.  Tear off this menu (using
   the "-----" entry on the top) if you are going to be doing a lot of editing.
   You can delete events, move them up or down and change the delay of an
   event.  You can also erase the entire script and eliminate extra mouse
   motion events.
   
   Editing a script file:
   If you want to do extensive editing you can edit the script file that
   is saved.  Each event is one line in the file and it stands by itself
   so you can move events or blocks of events around by moving lines in
   a text editor.  Within a line, only change the delay unless you are
   sure of what you are doing.

THE FILE MENU:
  Open... -- load a script
  Save -- save the script
  Save as... -- rename the script and then save it
  Load application -- start another Tcl/Tk  application.  You can also do
    this from an xterm.
  Connect to application -- a submenu of all existing Tcl/Tk interpreters
    that you could connect to.
  Quit Replay -- exit this program.
  
  There is a list of connected interpreters at the bottom of the TkReplay
  window.  It doesn't hurt to try to connect to an application a second
  time.  You will get a warning message and nothing will happen.  You can
  connect to two or more target applications at the same time and interleave
  user input events from all connected applications.  When a connected
  application quits you get a warning message.

THE EDIT MENU:
  Delete event -- the selected event is deleted from the script.
  Change delay -- a dialog box allows you to change the delay of the
    selected event.  Type in the new delay and press Return.  Press
    Dismiss to cancel and change in the delay.
  Move event up -- the selected event is moved up in the script.
  Move event down -- the selected event is moved down in the script.
  Compress motion events -- consecutive mouse motion events to do usually
    matter so the replay is speeded up if you eliminate them.  This command
    goes through the script and deletes all mouse motion events that are
    followed by another mouse motion event.
  Erase script -- the entire script is deleted.
  Preferences... -- bring up the preferences dialog box
  
  These commands allow you to edit the script.  No changes are saved until
  you save to a file.

THE PREFERENCES BOX:
  Pointing to widgets: You can choose to move the mouse pointer as the
  events are replayed or to move a big red arrow (or both).
  The mouse pointer is more realistic but it requires a custom wish.
  
  Mouse speed: you can choose the speed at which the mouse is moved.
      The warp speed jumps the mouse from place to place in one big jump.
  
  Events to skip: It speeds up the simulation if you skip focus events.
      Skipping enter and leave events often causes the widgets not
      to react properly.
  
  Showing events:  You can choose not to display events are they are
      being recorded or replayed.

THE RECORDER MENU:
  This menu duplicates the functions of the record control buttons.

THE RECORDER CONTROL BUTTONS:
  Record -- start recording.  The recording check button goes on.
  Stop -- stop recording.  This will also stop a replay if you can get
     control of the mouse pointer long enough to press it.
  Comment -- start a comment at this point in the script.
  Pause -- stop the replay at this point.  It can be restarted with "Play".
     Note this is not the usual sense of "Pause".  You can pause as long as
     you want between events.  This is to stop a script to allow the user
     to explore.  The script must be started again manually.
  Play -- play a script from the selected event on.  NOTE that you can start
    a script anywhere but it might not work if previous events are necessary
    for the replay.  For example, if a previous menu choice brought up a
    dialog window and you skip that then events interacting with the dialog
    window will not work.
  Rewind -- select the first event in the script.
  Play Fast -- like Play except that the time delays are ignored.  This plays
    the script as fast as possible.  NOTE that this might not really be that
    fast since the replay mechanism itself adds delays.  In addition, delays
    are caused by moving the mouse around.

KNOWN PROBLEMS:
    1. It slows things up noticeably.
    2. Time dependent things do not replay correctly since the replay is
        not exactly at the same speed.  This is most noticeable in scrolling.
        Scrolling which autorepeats will probably repeat too many times
        in the replay.
    3. The script does not know about window manager commands.  Moving the
        windows will not affect things but if you resize the windows with
        the window manager the script may not replay properly.
    4. Replays look a little jerky.

HOW TO CONTACT THE AUTHOR:
    Charlie Crowley
    Computer Science Department
    University 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.
