'\"macro stdmacro
.if n .pH g1.xtmrec @(#)xtmrec	40.2 of 1/9/90
.nr X
.if \nX=0 .ds x} XTMRECORD 1 "9/1/88" "X\s-2WIN\s+2 3.0" "\&"
.if \nX=1 .ds x} XTMRECORD 1 "9/1/88" "X\s-2WIN\s+2 3.0"
.if \nX=2 .ds x} XTMRECORD 1 "" "\&"
.if \nX=3 .ds x} XTMRECORD "" "" "\&"
.TH \*(x}
.ad b
.SH NAME
xtmrecord \- interactive test script recorder
.SH SYNOPSIS
.B xtmrecord
\fIfile\fB.scr\fR
.br
.SH DESCRIPTION
.I Xtmrecord
records a copy of the user's actions with the keyboard and mouse
(called a test script) in
\fIfile.scr\fR.
This test script will contain a record of which keys and mouse buttons were
pressed and released, where the mouse was moved to, and how long it took for
the user to do it.
.I Xtmexecute(1)
can then be invoked to play back what was recorded in the test script.
.PP
While recording a test script the user may request that the
image data within a window be recorded in the test script.
When the recording is played back this recorded data is compared
to the new data from the corresponding window.
.PP
This allows an interactive test to be recorded and replayed,
and the results of the test to be automatically verified.
This also allows the construction of automated demonstrations, with no
human attention needed to manipulate almost any X clients.
.SS File Name Syntax
The file name given to 
.I xtmrecord
must end in ".scr".
Thus:
.PP
.RS
xtmrecord file.scr
.RE
.PP
records an interactive test in 
.I file.scr.
If an incorrect file name or no file name is given,
.I xtmrecord
will display the correct invocation syntax.
.SS Running Xtmrecord
.I Xtmrecord
may be run in an X terminal emulator window or on a terminal.
If you run
.I xtmrecord
on a terminal, make sure that the
.SM
.B DISPLAY
environment variable is set to the name of the desired X server.
.PP
.I Xtmrecord
requires that the X server support the
.I Input Synthesis
extension.  This extension supplies the additional capabilities needed to
record a test script.
.PP
.I Xtmrecord
will communicate with the X server to start recording the user's actions as
soon as it is invoked.
The initial position of the mouse will be recorded, and the mouse will be moved
to that position when the recording is replayed.
.PP
The user's actions are recorded until the user wishes to
record some part of the display or terminate the recording.
At that point, 
.I xtmrecord
is placed in command mode by pressing the "command" key on the keyboard of the
X server.
.PP
The "command" key will vary from X server to X server
(on the AT&T XWin GWS server the "command" key is F12.)
The "command" key may be specified by the
.I CommandKey
.I .Xdefaults
variable.
.PP
While in command mode keyboard and mouse input are not passed on to the
clients that would otherwise see them but instead are only passed on
to 
.I xtmrecord.
Five
commands are available in command mode, each invoked by pressing a single key:
.TP
.B m
Cause the contents of the window containing the mouse to be recorded in 
.I file.scr
for later comparison.
.TP
.B s
Cause the contents of the entire screen to be recorded in 
.I file.scr
for later comparison.
.TP
.B t
Cause the contents of the top window (as defined by the X server) to be
recorded in 
.I file.scr
for later comparison.
.TP
.B r
Cause 
.I xtmrecord
to leave command mode and resume recording keyboard and mouse input.
.TP
.B q
Cause the recording (and \fIxtmrecord\fR) to be terminated.
.PP
The keys associated with the commands may be changed by using the appropriate
.I .Xdefaults
variables.
.PP
If no error occurs during recording, 
.I xtmrecord
will terminate with an exit status of zero.
If an error occurs during recording,
.I xtmrecord
will terminate with a non-zero exit status.
.PP
If the user wishes to see what was recorded without replaying the test script,
the test script may be converted to human-readable form by
.I xtmconvert(1).
.sp
.SS .Xdefaults Variable Usage
.I Xtmrecord
recognizes the following
.I .Xdefaults
variables (shown with their default values):
.PP
.RS
xtmrecord.CommandKey:         KP_F1
.RE
.RS
xtmrecord.MatchMouseKey:      m
.RE
.RS
xtmrecord.MatchScreenKey:     s
.RE
.RS
xtmrecord.MatchTopKey:        t
.RE
.RS
xtmrecord.ResumeKey:          r
.RE
.RS
xtmrecord.QuitKey:            q
.RE
.RS
xtmrecord.MatchRetries:       3
.RE
.RS
xtmrecord.RetryInterval:      5000
.RE
.RS
xtmrecord.MatchBufferSize:    32760
.RE
.PP
The
.I CommandKey
variable specifies the name of the key on the X server that
is the "command" key.
The default value is the name for the first function key on the numeric keypad,
which is the left-most blank key on most Hewlett Packard X servers.
Some other X servers may not have this key,
in which case some other key was chosen.
The name given here must match the key chosen by the X server you are going
to record from.
.PP
The
.I MatchMouseKey
variable specifies the name of the key on the X server that causes the contents
of the window containing the mouse to be recorded for later comparison.
.PP
The
.I MatchScreenKey
variable specifies the name of the key on the X server that causes the contents
of the entire screen to be recorded for later comparison.
.PP
The
.I MatchTopKey
variable specifies the name of the key on the X server that causes the contents
of the top window to be recorded for later comparison.
.PP
The
.I ResumeKey
variable specifies the name of the key on the X server that causes
.I xtmrecord
to leave command mode and resume recording keyboard and mouse input.
.PP
The
.I QuitKey
variable specifies the name of the key on the X server that causes the
recording (and \fIxtmrecord\fR)
to be terminated.
.PP
The
.I MatchRetries
variable controls the number of times a failing image data comparison will be
retried when the test script is executed using
.I xtmexecute(1).
.PP
The
.I RetryInterval
variable controls the interval in milliseconds between each retry when the
test script is executed using
.I xtmexecute(1).
It has a range of 0 to 2,147,483,647 milliseconds (approximately 25 days).
.PP
The
.I MatchBufferSize
variable controls the size in bytes of the buffer that is used to hold the
data read from the display.
It does not limit the amount of data that can be read from the display, but
only determines how much of the data can be read at one time.
.PP
The value of this variable must be divisible by 8 and
at least large enough to hold one line
of pixels the width of the X server's display.
Larger than default values of this variable
may increase the performance of display reads
on machines with large amounts of memory.
It has a range of 0 to one-half the maximum value an unsigned integer can hold.
.SH SEE ALSO
xtmexecute(1), xtmconvert(1).


