Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/051.lha/Journal/journal.doc

Text File | 1986-11-20 | 17.1 KB | 344 lines

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 TO <file>

where <file> 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 <file>       Designates <file> 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 <file> SMOOTH 0 TRIGGER 0x6000

To specify that left Amiga plus left shift together with either button
should cause smoothing, use:

    1> JOURNAL TO <file> 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 <file>

where <file> 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 <file>     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        [e-mail]
Taylor Hall                                     [e-mail]
Rochester, New York  14627                      [e-mail]
[phone]