Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!mnetor!uunet!seismo!husc6!mit-eddie!ll-xn!cit-vax!ucla-cs!zen!ucbvax!s.cc.purdue.edu!dpvc From: dpvc@ur-tut.UUCP (Davide P. Cervone) Newsgroups: comp.sources.amiga Subject: Journal and Playback (documentation) Message-ID: <485@s.cc.purdue.edu> Date: Fri, 10-Jul-87 14:57:20 EDT Article-I.D.: s.485 Posted: Fri Jul 10 14:57:20 1987 Date-Received: Sun, 12-Jul-87 12:56:07 EDT Expires: Fri, 7-Aug-87 09:34:41 EDT Sender: doc@s.cc.purdue.edu Reply-To: doc@s.cc.purdue.edu (Craig Norborg) Distribution: world Organization: Purdue University Computing Center Lines: 400 Approved: doc@s.cc.purdue.edu Here is the documentation to a neat utility that allows you to record and playback events that happen in a window. Binaries and sources available in respective groups! -Doc # This is a shell archive. # Remove everything above and including the cut line. # Then run the rest of the file through sh. #----cut here-----cut here-----cut here-----cut here----# #!/bin/sh # shar: Shell Archiver # Run the following text with /bin/sh to create: # README # journal.doc # This archive created: Fri Jul 10 13:53:16 1987 # By: Craig Norborg (Purdue University Computing Center) cat << \SHAR_EOF > README Well, when I was working on MonIDCMP, I wanted to provide a real-life example of how it could be used for something useful (like HARDCOPY was to MONPROC). I thought, "Wouldn't it be great to be able to record and play back the events that went on in a window?" You could make "Guided Tour" demonstrations, or turnkey systems that perform all kinds of mouse and keyboard activity, or you could record the events that demonstrate a bug that you have been able to produce and send the recorded events to Commodore as documentation of the bug. But MonIDCMP doesn't have the power to accomplish this: it can trick a window into thinking that things have happened, but gadgets would not REALLY be pressed, and windows would not REALY be resized. To do it right you have to go directly to the Input Device and look at the events that are being passed to Intuition. I set out to do this. What I came up with was JOURNAL and PLAYBACK. To see what they do and what they are good for, read the following document, which describes in detail how to use JOURNAL and PLAYBACK. With a little more work, these could become important documentation tools for any Amiga software company. I am willing to do that additional work, but only if there is sufficient interest. If you want to see the enhancements I discuss below (or any of your own design), please contact me and let me know. I did this mainly as an exercise, but think it would be valuable to continue work on it, but not if I'm the only one who will use it. I hope you find these little programs interesting. I think they're kind of spooky myself. I'm not sure I like it when my computer types things for me without my pressing the keys... Davide P. Cervone dpvc@tut.cc.rochester.EDU dpvc@ur-tut.UUCP DPVC@UORDBV.BITNET SHAR_EOF cat << \SHAR_EOF > journal.doc OVERVIEW: JOURNAL is a program that records a sequence of mouse and keyboard events as they occur and stores them in a file. The file can be played back via the program PLAYBACK, thus causing the same sequence of events to occur again. This is useful for creating demonstrations of programs (much like the "Guided Tours" on the Macintosh computer). It also is useful for documenting repeatable bugs: rather than trying to describe to CATS (or some third-party vender) what you did that revealed the bug, you could record the actions with JOURNAL, and send them the output file instead. Finally, you can use JOURNAL to set up turnkey demo-disks for conferences and computer shows that will run unattended while you talk to customers. It's even possible for PLAYBACK to restart itself when it comes to the end of the file. In a future version, there will be a journal editor that allows you to add "special effects" like explanation windows that tell the viewer what you are doing, or that call up the narrator device to "speak" some information as your demonstration progresses. JOURNAL may not work with some programs the "take over" the system or bypass the Input.Device (see USAGE NOTES for additional information). HOW TO USE JOURNAL: To run JOURNAL, type: 1> RUN JOURNAL TOwhere is the name of the journal file that you wish to produce. JOURNAL should respond by displaying its version number and telling you how to cancel it, and by moving the pointer to the upper, left-hand corner of the screen. Once the pointer has been moved, JOURNAL will record all the key presses and mouse movements that you perform, by writing them to the file that you specified. This file will be used A LOT, so if it is on floppy-disk, be sure that the disk can be left in the drive, and that it has enough space available for the journal file. The journal grows FAST, so do some exparimenting before you create a long journal file. RAM: is a good place to write small journals, but may not be appropriate for long ones, as you may need your RAM space for the programs that you are running. When you are done creating your journal, press CTRL-LEFTAMIGA-E. This signals JOURNAL to stop recording events. Once you get the "Joural Complete" message, any further actions will not be added to the journal file. HOW JOURNAL WORKS: JOURNAL installs an input handler into the handler chain of the Input.Device. This handler's priority puts it ahead of Intuition, so it sees the "undigested" events as they arrive from the Keyboard.Device, Gameport.Device, and Timer.Device. When keyboard or mouse events are passed to the handler, it copies them into a linked list of events and signals JOURNAL that new events are ready, then passes the unmodified event list on to Intuition. JOURNAL picks up the list of events and packs them into "TinyEvents" that take up fewer bytes, and records these in the output file. To save even more space in the file, JOURNAL compresses multiple mouse move events into single output file records when possible, but records the number of events that were compressed, so that they can be recreated by PLAYBACK, if desired. The amount of compression is controlled by command-line options (see below). When the handler sees that CTRL-AMIGA-E has been pressed, it signals JOURNAL, which tells the Input.Device to remove the handler from the chain and closes the journal file. JOURNAL OPTIONS: JOURNAL supports a number of command-line options that modify its behavior: TO Designates as the JOURNAL output file (the keyword "TO" is optional). DX x Specifies the amount of x movement that can be compressed into one output event (mouse movements are added together until their conbined x-offsets exceed DX or their combined y-offsets exceed DY). The default value is 8. DY y Specifies the amount of y movement that can be compressed into one output event (mouse movements are added together until their conbined x-offsets exceed DX or their combined y-offsets exceed DY). The default value is 8. SMOOTHX x Specifies an alternate value for DX that is used when extra precision is needed (for example, when you need to draw a free-form line in a paint program). This value is in effect when the SMOOTH and TRIGGER mask conditions are met (see below). The default value is 1. SMOOTHY y Specifies an alternate value for DY that is used when extra precision is needed (for example, when you need to draw a free-form line in a paint program). This value is in effect when the SMOOTH and TRIGGER mask conditions are met (see below). The default value is 1. SMOOTH mask Indicates which qualifier keys MUST be pressed in order to activate the SMOOTHX and SMOOTHY values. Whan ALL the keys specified by the SMOOTH mask are pressed, and AT LEAST ONE of the keys designated by the TRIGGER mask is pressed, then the SMOOTHX and SMOOTHY values are used in place of DX and DY. By default, the left Amiga key specifies smoothing. TRIGGER mask Indicates which qualifier keys trigger the use of SMOOTHX and SMOOTHY. When ANY ONE of the keys indicated by TRIGGER mask is pressed, and ALL of the keys specified by the SMOOTH mask are pressed, then SMOOTHX and SMOOTHY are used in place of DX and DY. By default, any qualifier key triggers smoothing. For people who understand "C" syntax, the expression that determines whether to use DX and DY or SMOOTHX and SMOOTHY is the following: if (((Qualifiers & SmoothMask) == SmoothMask) && (Qualifiers & TriggerMask)) use SMOOTHX and SMOOTHY else use DX and DY Note that this provides considerable flexibility in specifying what will activate smoothing. For example, to specify that pressing either button will cause smoothing, use: 1> JOURNAL TO SMOOTH 0 TRIGGER 0x6000 To specify that left Amiga plus left shift together with either button should cause smoothing, use: 1> JOURNAL TO SMOOTH 0x0041 TRIGGER 0x6000 The complete set of qualifier values is listed in the include file "DEVICES/INPUTEVENT.H". Important values are listed here: Left Shift 0x0001 Right Shift 0x0002 Caps Lock 0x0004 Control 0x0008 Left ALT 0x0010 Right ALT 0x0020 Left Amiga 0x0040 Right Amiga 0x0080 Left Button 0x2000 Right Button 0x4000 To determine the mask value, take the bitwise OR of the values for the qualifiers you want to use. Note that the SMOOTH and TRIGGER masks should be specified in HEX, not decimal. HOW TO USE PLAYABCK: To use playback, type: 1> RUN PLAYBACK FROM where is the name of a journal file recorded with the JOURNAL command. PLAYBACK should print a message telling you its version number and how to abort the playback, and then should begin playing back the recorded events. All you have to do is sit back and watch. When PLAYBACK is running, you will not be able to control the mouse yourself, and the keyboard will have no effect (except for CTRL-C, which cancels PLAYBACK). This is so that you do not disturb the sequence of the journal being played back. When the last event is played back, PLAYBACK will inform you that it is done. To cancel PLAYBACK at any time, press CTRL-C. This is the only key that has any effect while PLAYBACK is running. HOW PLAYBACK WORKS: PLAYBACK installs an input handler into the handler chain of the Input.Device. This handler's priority puts it ahead of Intuition, so it can insert new events into or remove events from the stream seen by Intuition. PLAYBACK reads packed events from the journal file and unpacks them into an event buffer where the input handler adds them to the event stream. Since multiple mouse movements are compressed into single journal records, PLAYBACK must uncompress these by extrapolating intermediate mouse positions. The input handler removes all keyboard and mouse events sent to it by the Input.Device so that these do not interfere with the journal being played back. If the handler sees a CTRL-C it signals PLAYBACK that the user wants to abort the playback before it is complete. PLAYBACK then requests the input.Device to remove the handler. PLAYBACK uses a FIFO event queue to supply events to the input handler. Since the handler may have to wait for some time to pass before it posts the next event in the queue, this allows PLAYBACK to "read ahead" in the journal file, and prepare additional events for posting. This makes the mouse movements smooth and un-interrupted. When PLAYBACK fills the queue, it waits for the handler to post some events (freeing space in the queue). You can control the size of the queue via the EVENTS command-line option. PLAYBACK OPTIONS: PLAYBACK supports a number of command-line options that modify its behavior: FROM Specifies the journal file to be played back (the keyword "FROM" is optional). EVENTS n Specifies the size (in events) of the events buffer used to pass events from PLAYBACK to the input handler. EVENTS must be at least two. The default value is 50, but it can be set as low as 10 and still provide acceptable performance for some tasks. The number of events may need to be increased if you have many other tasks running, or are accessing the disk containing the journal file frequently, or have specified small DX and DY values when you recorded the journal file. SMOOTH Specifies that compressed mouse moves should be expanded into multiple mouse moves of smaller offsets. This makes the playback look smoother, and makes precise mouse moves possible without taking up space in the journal file. The default is SMOOTH. NOSMOOTH Specifies that compressed mouse moves should be left compressed (i.e., no extrapolated events should be posted). This may be necessary if you need extremely quick response time or if you have specified a small DX and DY during recording and do not need to uncompress mouse moves. The default is SMOOTH. HOW TO COMPILE AND LINK JOURNAL AND PLAYBACK: JOURNAL AND PLAYBACK were developed using the Lattice C compiler version 3.10. I have tried to make it as generic as possible, but since I don't have the Aztex C compiler, I don't know whether it works with Manx. For Lattice C, all you have to do is: 1> lc -v journal playback 1> asm handlerstub 1> blink with journal.lnk 1> blink with playback.lnk The '-v' option is so that no stack checking code will be produced. Since the input handler runs on the Input.Device's stack, this would confuse the stack check code and probably crash the system (I never tried it, though). USAGE NOTES: Since PLAYBACK plays back exactly what was recorded by JOURNAL, it is important that the initial conditions be the same for both JOURNAL and PLAYBACK. If even one window is not where it was when your ran JOURNAL, then PLAYBACK may become hopelessly out of synchronization. It is best to run JOURNAL from a freshly booted system, or a newly opened NewCLI or AmigaDOS window. If the journal needs programs or other windows to be open, don't open them first and then run JOURNAL. Instead, run JOURNAL and then open the windows or run the programs. This way you can be sure that what you want will be there, and in the proper places. If you are recording actions on the Workbench, you should start with all the disk windows closed, and the disks in their default positions then open them within the journal. Beware that disk positions may change depending on the order in which they were inserted. One "feature" of JOURNAL and PLAYBACK is that they do not know about disk insert requesters. If a disk requester comes up, JOURNAL keeps right on recording mouse moves and key strokes. If you cancel the requester, so will PLAYBACK. But if you put in a disk and the requester goes away, there is no guarantee that the user who is playing back your journal will replace the disk in the same amount of time you did (in fact, he may never replace it), so the rest of the journal may become out-of-synch. Worse yet, the user can pop a disk out of the drive at any time, which may cause a disk requester to come up that did not appear when you recorded the journal, or the user might have fewer disk drives than you do, so he may have to swap drives differently from how you did. All of these cases cause trouble for JOURNAL and PLAYBACK, so be careful when you are using multiple disks with journal. (See FUTURES for additional comments on disk-requesters). Since JOURNAL will be writing lots of data to its output file, and PLAYBACK will be reading losts of data from the journal file, the journal file must be on a disk that can remain in a drive. RAM: is a good candidate for small journals, but may not have room for a large journal plus the programs that will be running. JOURNAL's input handler allocates memory for the events as it copies them. This memory is not freed again until JOURNAL actually records the event. If events are coming in very fast, JOURNAL may not be able to keep up with them. This may use up considerable memory until JOURNAL can catch up. If you are having memory problems while using JOURNAL, try slowing down your mouse movements to give JOURNAL some time to catch up. You may need to run JOURNAL and PLAYBACK at higher priorities than your normal processes in order to give them enough time to get the events to and from the input handler in a timely fashion. Both progams use the Wait() function and neither "busy waits," so they should cooperate with other tasks even when they are at a higher priority. If your journal runs a program that has to be loaded from disk, be sure to wait long enough for it to be loaded during the PLAYBACK. Some disks take longer than others, and sometimes there are slight timing differences between JOURNAL and PLAYBACK. Give a little extra time after disk accesses before you move the mouse or press a key. JOURNAL only records mouse and keyboard events that come through the input device. It does NOT record events that are received directly by a program through a message port from devices opened explicitly by the program. For example, if your program opens the timer device and gets timer messages, these are NOT recorded by JOURNAL. Similarly, JOURNAL does not record messages from the serial port, parallel port, or second mouse port. Note that this means that JOURNAL will not record joystick motions from the second mouse port, so PLAYBACK can not reproduce them. This may make it impossible to make a journal record of some games. FUTURES: The disk insert problem mentioned in USAGE NOTES above needs to be fixed. The only solution I can think of is to use SetFunction to replace AutoRequest with a function that signals the JOURNAL or PLAYBACK process that a request has occured, then calls the original AutoRequest, then signals when the request is finished. JOURNAL and PLAYBACK would "pause" until the AutoRequest was done, and then continue recording or playing back. Since AutoRequest allows you to specify what kinds of flags will cancel the request, the replacement routine could check these to see if DISKINSERTED messages will satisfy it. If not, then the original AutoRequest could be called without signalling the JOURNAL or PLAYBACK processes. This way we would not be trapping the wrong requesters. Unfortunately, Workbench disk requests do not seem to use the DISKINSERTED flag, so something more sophsticated may be needed. I am open to suggestions. In the future (if there is enough interest), I plan to write a journal editor that allows you to step through a recorded journal and modify it by changing the events, adding new events, or deleting events. Also, you will be able to add "special effects" like pop-up windows that contain explanations of what your program is doing, what qualifier keys are being pressed, etc. I also hope to allow you to do this via the narrator device rather than through a window, if desired. If I get real ambitious, I might even add something to play music from a file, but that will have to be far future for now. If you want these features, please let me know. AUTHOR: Davide P. Cervone University of Rochester Computing Center DPVC@UORDBV.BITNET Taylor Hall dpvc@tut.cc.rochester.EDU Rochester, New York 14627 dpvc@ur-tut.UUCP (716) 275-2811 SHAR_EOF # End of shell archive exit 0