# $Id: HelpFile,v 1.1.1.1 2004/03/09 15:36:16 clif Exp $
# $Log: HelpFile,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:18  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:39  crowley
# Initial revision
#
                 TK RECORD AND REPLAY FACILITY

CONTENTS OF THIS HELP FILE:
    OVERVIEW
    REQUIREMENTS
    THE TKREPLAY WINDOW
    WHAT A SCRIPT LOOKS LIKE
    HOW TO RECORD A SCRIPT
    HOW TO SAVE A SCRIPT
    HOW TO LOAD A SCRIPT
    HOW TO ADD A COMMENT
    HOW TO INSERT TCL CODE
    HOW TO INSERT A SUBSCRIPT
    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
    COMMAND LINE OPTIONS
    HOW TO USE SOCKETS INSTEAD OF SEND
    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.

REQUIREMENTS:
  TkReplay requires Tcl7.4 and Tk4.0 or higher.
  This is version 1.1 of 1 August 1996.

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.  All of these
      commands can be invoked from the menus also.
  The next line gives the file name of the script
  The list box shows the events currently in the script.  The selected event
      is the one about to be replayed.
  The bottom line shows which applications TkReplay is currently connected to.

WHAT A SCRIPT LOOKS LIKE:
  TkReplay records user actions, also called events.  It defines some special
  events like ExecTcl BeginComment, etc.  The current script is the record of
  the events recorded so far.  It is similar to a tape in a tape recorder.
  There is only one script at a time.  This script may be saved or a new
  script loaded.  You can do some editing of the script within TkReplay.
  You can also edit the script in its saved file form.  A saved script
  is normal ASCII text and is (relatively) readable (see the next two
  paragraphs).
  
  The current script is displayed in TkReplay's main window.  The time
  between events is shown first, then the event type then some other
  information about the event.
  
  The script can be saved into a file.  The file form has all the information
  about each event and is in the following form.  The file is a list of
  Tcl commands.  Each one is an "InsertAction" and so this is the first
  word of each line.  Then comes the time before this event.  Next is the
  target application the event came from.  Next is the identifier of the
  event.  This usually begins with "Bind,".  it includes the tag and the
  Tk event name.  Some special "events" defined by TkReplay have there
  own names.  Last is an association list (a list of pairs) of named
  values related to the event.  The most common values are W (the widget
  name), x (the x coordinate) and y (the y coordinate).

HOW TO RECORD A SCRIPT:
  1. Start the tcl/tk program you want to record, the "target application".
  2. Start TkReplay with the command tkreplay.tcl.  tkreplay.tcl will
      try to load the WarpPointer extension and inform you if it fails
      to do so.
  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 the "Record" button to start recording a script.
  5. The listbox 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.  If you want add Tcl code, see HOW TO ADD TCL CODE
  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.
      The default name is "Unnamed".
  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 INSERT TCL CODE:
  For regression tests you may want to, a certain points in the replay,
  check if the program is in the correct state.  This will involve
  running some arbitrary Tcl code that checks your database.  You can add
  an "event" that will run the code you specify.  Usually this will be
  a procedure call to some code in your application that checks the state.
  Normally this Tcl code is run in the target application (actually all
  currently connected applications) but it is possible to run it in TkReplay
  if you want (but I don't see why you would want to).
  
  1. During recording, press "Insert Tcl" and a dialog box will come up.
  2. Type in the Tcl code you want toe execute at this point during the replay.
  3. When you are satisfied with the Tcl code "Done".

HOW TO INSERT A SUBSCRIPT:
  You can play one script from another script.  This is called playing a
  subscript.  This is handy for constructing a demonstration or test out
  of parts recorded separately.  It is easier to record small scripts.
  This is done as follows:
  
  1. During recording, select "Exec Script..." from the "Recorder" menu.
  2. A file box will come up that allows you to select a prerecorded script.
  3. The event is recorded in the script, but the subscript is not replayed
      during recording.  During replay, when this event is replayed, it will
      fetch the script, replay it, and return to the original script.

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 "tkreplay.tcl scriptName"
  3. Or you can open the script after you start TkReplay.
  4. Connect to the target application.
  5. Rewind the script to the beginning (if necessary).
      NOTE: actually you can start replaying from anywhere in the script.
      Just select the first event to replay and press "Play".  However,
      if you start in the middle, the replay might not work as you expect.
  6. 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 are 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 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
  Connect to application -- a submenu of all existing Tcl/Tk interpreters
    that you could connect to.
  Load application -- start another Tcl/Tk  application.  You can also do
    this from an xterm.
  About TkReplay... - the about box.
  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 else 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:
  Erase script -- the entire script is deleted.
  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.
  Delete event -- the selected event is deleted from 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.
  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 the WarpPointer
  extension (which only works on UNIX).
  You can use both of them at the same time if you want to.
  
  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.
  

THE RECORDER MENU:
  This menu duplicates the functions of the record control buttons except for:
  Exec Script... -- execute another script when this script is replayed.
    During replay, the script display will switch to the other script
    and that script will be played.  When it is done, TkReplay will switch
    back to this script.  Note that the script is NOT executed when you
    select this command while recording, only during replay.  You can
    next as many levels of scripts as you want. 

THE RECORDER CONTROL BUTTONS:
  Record -- start recording.  The recording check button goes on.
  Comment -- start a comment at this point in the script.
  Insert Tcl -- execute some Tcl code 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.
  Stop -- stop recording.  This will also stop a replay if you can get
     control of the mouse pointer long enough to press it.
  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 because th dialog box will not have been displayed.
  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.  For the fastest replay, also
    speed up the mouse movements (from the Preferences dialog box).

COMMAND LINE OPTIONS:
    -app appName -- Load this Tcl/Tk application and connect to it.
    -script scriptName -- Load the named script.
    -play -- Start playing automatically after TkReplay initializes.
        This assumes you have a -app and -script options.
    -playfast -- Like play but playing without delays.
    -movemouse -- Move the mouse pointer when replaying.  (default)
    -nomovemouse -- Do not move the mouse pointer when replaying.
    -movearrow -- Move the red arrow when replaying.
    -nomovearrow -- Do not move the red arrow when replaying.  (default)
    -mousethenarrow -- Use the mouse if possible else use the
        red arrow.  (default)
    -nomousethenarrow -- Do not automatically use the red arrow if
        the mosue cannot be moved.
    -mousespeed speed -- Set the mouse speed.  "speed" can be one of:
        slow, Slow, medium, Medium, fast, Fast, veryfast, VeryFast,
        warp, Warp, or a number.  A number is the number of pixels to
        move the mouse on each step. (default is medium)
    -usesend -- Use the send command to communication between TkReplay
        and the target application.  (default)
    -usesockets -- Use sockets to communication between TkReplay and the
        target application.
    -sendthensockets -- Try to use send but use sockets if send is not
        available.  (default)

HOW TO USE SOCKETS INSTEAD OF SEND:
  TkReplay was developed to work with the Tk "send" command but some code
  has been added to allow it to simular send with sockets.  Using sockets
  is more trouble than using send.  Here is what you have to do:
  1. In the application, add two lines:
         source socksend/socksend.tcl
         sockappsetup app_port tkreplay.tcl tkreplay_port
     for example:
         source socksend/socksend.tcl
         sockappsetup 3020 tkreplay.tcl 3010
  2. Run tkreplay with the command:
         tkreplay.tcl -usesockets tkreplay_port app_name app_port
     for example:
         tkreplay.tcl -usesockets 3010 test1.tcl 3020

KNOWN PROBLEMS:
    1. It slows things up somewhat.
    2. Time dependent things do not replay correctly since the replay is
        not exactly at the same speed.  I have fixed this problem for
        most time delays (like autorepeating in scrolling) but it may
        occur in some other places.
    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.
