Contents

Mouse()

Usage:

Str <- Mouse([getpoints:T or getlines:T or getbox:T] [,xyonly:T or n:N]\
  [,cancelok:T] [graphics keyword phrases]), positive integer N <= 20

Keywords: plotting

Mouse() provides a way to get x-y coordinates from a graphics window so
that you can add points, lines, boxes or character information at points
whose x- and y-coordinates are chosen interactively.

Mouse() is implemented only in windowed versions (Macintosh, Windows and
Motif) and on Unix/Linux versions implementing Tektronix 4014 emulation.
And of course, it cannot work with a Tektronix terminal emulator that
does not allow graphical input (GIN) mode.

In a Unix/Linux version with Tektronix emulation, Mouse() automatically
activates the graphics screen.  In windowed versions, you have to select
the graphics window where you want to get x-y coordinates.  In some
versions, pressing 'q' at any time before the operation is finished
aborts Mouse() and pressing 'r' restarts it, forgetting any coordinates
already selected.

The basic usages of Mouse() are as follows
    Usage                                      Returns
  Str <- Mouse([xyonly:T])                   x-y coordinates of 1 point
  Str <- Mouse(getpoints:T [,xyonly:T])      x-y coordinates of 1 point
  Str <- Mouse(getpoints:T, n:N [,xyonly:T]) x-y coordinates of N points
  Str <- Mouse(getlines:T [,xyonly:T])       2 endpoints of a line
  Str <- Mouse(getlines:T, n:N [,xyonly:T])  N+1 points defining seg-
                                             mented line
  Str <- Mouse(getbox:T [,xyonly:T])         x-y coordinates of the cor-
                                             ners of a rectangular box,
                                             plus the first corner
                                             repeated.
N must be an integer between 1 and 20.

With each of these usages, you can also use keyword phrase 'cancelok:T';
without 'cancelok:T', cancelling Mouse() by pressing 'q' is considered
an error; with 'cancelok:T', pressing 'q' causes Mouse() immediately to
return NULL.

After you select one or more positions in graphics window I, Str becomes
a structure whose first two components, 'x' and 'y', are REAL scalars or
vectors containing the x- and y-coordinates being returned.

With keyword phrase 'xyonly:T', 'x' and 'y' are the only components.
Otherwise the structure also has component 'window' with integer value
I, and component 'add', a LOGICAL scalar with value True.  With
getlines:T and getbox:T, 'lines' is an additional LOGICAL scalar
component having value True.

When 'xyonly:T' is not an argument, you can include additional "extra"
keyword phrases, usually graphics keyword phrases, after the Mouse()
keyword phrases just described.  These will be made part of the output
structure.  For example, Mouse(getbox:T,linetype:2,thickness:3) returns
structure(x:xcoord, y:ycoord, window:I, add:T,lines:T, linetype:2,
thickness:3).  If keyword 'add' is among these "extra" keywords, Mouse()
does not include its own component 'add' in the structure returned, and
similarly for keywords 'lines' and 'window'.  For example,

  Cmd> Str <- Mouse(getlines:T, symbols:"\1",add:F, lines:F)

sets Str to structure(x:xcoord, y:ycoord, window:I, symbols:"\1", add:F,
lines:F).

Using Mouse() differs slightly among different versions.  On windowed
versions you select positions by clicking and releasing the mouse button
with the cursor or pointer in a graphics window.  In a version running
under Xterm on a Unix/Linux workstation, you need to press Enter or
Return after releasing the mouse button.  On other Tektronix terminal
emulators pressing the mouse button may be sufficient.  On some
emulators, it may not work at all.

The action of Mouse() starts when you click and release the mouse with
the cursor or pointer in a graphics window.  The action then taken
depends on whether 'getpoints:T', 'getlines:T' or 'getbox:T' is an
argument to Mouse() (default is 'getpoints:T').  The action ends when
you depress and release the button the final time.  In the windowed
versions, Mouse() draws temporary lines as you move the mouse in the
window, erasing them before it returns.

In windowed versions, at any time before the final click you can restart
selection of locations by moving the cursor outside the window.
Temporary lines or marks are erased and you can select a different
window if you want.

In windowed versions, you can interrupt and terminate the action at any
time by selecting Interrupt on the File menu or pressing Ctrl+I
(Command+I on Macintosh).  In Unix/Linux pressing the interrupt key
(usually Ctrl-C) terminates the action.

Mouse(getpoints:T [,n:N] ...) and Mouse([n:N] ...).
 As you move the mouse, cross hairs (horizontal and vertical lines)
 appear and follow the cursor until you click and release at which time
 the point selected is marked temporarily.  When N > 1, the cross hairs
 appear again until you click and release to mark the next point.  This
 continues for N points.  After the final click, Mouse() erases the
 marked points and returns structure(x:xcoord, y:ycoord, window:I,
 add:T) where xcoord and ycoord are the x- and y-coordinates of the
 point or points selected.

 Mouse(getpoints:T,xyonly:T [,n:N]) or Mouse(xyonly:T [,n:N]) returns
 only structure(x:xcoord, y:ycoord).

Mouse(getlines:T [,n:N])
 As you move the mouse until you click and release it again, a contin-
 uously updated line is drawn between the current position of the mouse
 and the first location clicked.  When N > 1, another continuously
 updated line is drawn between the current position and the second
 location selected, and so on until N connected line segments have been
 drawn.  After the final click and release, Mouse() erases the lines
 drawn and returns structure(x:xcoord, y:ycoord, window:I, add:T,
 lines:T) where xcoord and ycoord contain the x- and y-coordinates of
 the N+1 points defining the segmented line.

 Mouse(getlines:T,xyonly:T [,n:N]) returns only structure(x:xcoord,
 y:ycoord).

 If you press the shift key while tracing a line, the line being drawn
 if forced to be either horizontal or vertical.

Mouse(getbox:T)
 As you move the mouse, a continuously updated rectangular box is drawn.
 One corner is at the first position clicked on and the opposite corner
 is the current position.  After a second and final click and release,
 Mouse() returns structure(x:vector(x1,x1,x2,x2,x1), y:vector(y1, y2,
 y2,y1,y1),window:I, add:T,lines:T), where (x1,y1) is the initial
 position clicked on and (x2,y2) is the final position of the opposite
 corner.  Note that the initial position is repeated as the last point
 and that the points trace out the entire border of the box.  Keyword
 phrase 'n:N' is illegal with 'getbox:T'.

 Mouse(getbox:T,xyonly:T) returns only
   structure(x:vector(x1,x1,x2,x2,x1),y:vector(y1,y2,y2,y1,y1))

 If you press the shift key while moving the mouse, the rectangle drawn
 is forced to be square (not in Tektronix emulation).

The form of the output from Mouse() is designed to make it easy inter-
actively to add information to a plot, either using one of the graphics
commands (see topic 'graphs') or assignment to GRAPHWINDOWS (see topic
'graph_assign').

                                Examples
  Cmd> s <- Mouse(getpoints:T, symbols:"*") # or s <- Mouse(symbols:"*")

  Cmd> GRAPHWINDOWS[s$window] <- s

This plots "*" at the position selected with the cross hairs.  The
second command can be replaced by addpoints(GRAPHWINDOWS[s$window],
keys:s).

  Cmd> s <- Mouse(getlines:T, linetype:2); GRAPHWINDOWS[s$window] <- s

This draws in the window the line determined by two click and releases
of the mouse in a graphics window.

  Cmd> s <- Mouse(getbox:T); GRAPHWINDOWS[s$window] <- s

This draws in the window the box determined by the mouse positions.

If you know the window you will draw into, say window 1, you can plot a
point, line or box simply by GRAPHWINDOWS[1] <- Mouse(KEY:T ...), where
KEY is 'getpoint', 'getline' or 'getbox':

  Cmd> s <- Mouse(getlines:T, n:5, linetype:2,thickness:3)

  Cmd> addlines(GRAPHWINDOWS[s$window], keys:s)

This draws 5 connected line segments with line type 2 and thickness 3.

  Cmd> s <- Mouse(getlines:T, show:F)

  Cmd> addlines(GRAPHWINDOWS[s[3]], keys:s[-3])

  Cmd> addstrings(s$x[1],s$y[1], "Interesting feature",\
       window:s$window, justify:"l")

This draws the line and then draws "Interesting feature" at the first
position clicked on.  Component 'window' is omitted in addlines() (by
using s[-3] as an argument) because 'window:n' can't be used with
'show:F'.

See also 'structures', strconcat(), addlines(), addstrings().