path: root/unix/sun/gterm.man

." @(#)gterm.1	1.1 28-Jul-87 DCT
.TH GTERM 1 "31 December 1987"
.SH NAME
gterm \- virtual graphics terminal for the SunView environment
.SH SYNOPSIS
.B gterm
[
.B \-C
] 
[
.B \-T
] 
[
.B \-B
\fIboldstyle\fR
] 
[
.B \-I
\fIcommand\fR
] 
.if n .ti +0.5i
[
.B \-ignore
]
[
\fIttyargs\fR
] 
.ti +.5i
[
.B \-G
[
.B \-Gopen
\fR(\fP\fBnoaction\fR | \fBshow\fR | \fBexpose\fR\fR)\fP
]
.if n .ti +1.0i
[
.B \-Gclose
\fR(\fP\fBnoaction\fR | \fBblank\fR | \fBhide\fR\fR)\fP
]
.ne 4
.ti +1.0i
[
.B \-\fR[\fPno\fR]\fPpause
]
[
.B \-\fR[\fPno\fR]\fPretain
]
[
.B \-\fR[\fPno\fR]\fPclip
]
.if n .ti +1.0i
[
.B \-\fR[\fPno\fR]\fPreverse
]
[
.B \-color
|
.B \-mono
]
.ti +1.0i
[
.B \-ginterm
\fR[\fIchar \fR[\fIchar\fR]]
]
[
\fIgioargs\fR
] 
]
.ti +.5i
[
\fIprogram\fR
[
\fIargs\fR
]
]
.SH GETTING STARTED
\fIgterm\fR is a virtual graphics terminal implemented as a set of windows
running within the SunView environment.  The graphics terminal consists of
two primary windows, the main \fBtext window\fR and a \fBgraphics subwindow\fR.
The text window is a standard SunView TTY subwindow, identical to that used
in \fIshelltool\fR.  The graphics window is a Tektronix 4012 compatible
graphics window.  The two windows may be moved and sized independently.
Terminal i/o may be directed to either window, but to only
one window at a time.  When i/o is directed to the text window the terminal
is said to be in \fBtext mode\fR, and when i/o is directed to the graphics
window the terminal is said to be in \fBgraphics mode\fR.  Mode switching
may be performed either manually or under program control.
\fIgterm\fR is upwards compatible with \fIshelltool\fR.
.SH OPTIONS
.TP
.B \-C
Redirect system console output to this instance of \fIgterm\fR.
.TP
.B \-T
Run \fIgterm\fR with the graphics plane disabled.  Any graphics commands
embedded in the input data stream will appear as printable characters in the
text window.  This option is useful when using \fIgterm\fR for a nongraphics
session over a noisy line, or when debugging a graphics program and switching
back and forth between text and graphics mode would interfere with the
operation of the debugger.
.TP
\fB\-B\fP \fIboldstyle\fR
Sets the \fIboldstyle\fR
(rendering of boldface type in the text window)
for this instance of \fIgterm\fR.
The choices are the same as for any tool based
on a SunView tty subwindow: see \fIshelltool\fR(1) for a description of the
\fIboldstyle\fR options.
.TP
\fB\-I\fP \fIcommand\fR
Input the given command to the program or shell run in the \fIgterm\fR window,
as if it had been typed into the window.  Spaces in the command must be
escaped, or the command string must be quoted.
.TP
.B \-ignore
Ignore the suspend control characters (SIGTSTP), \fIif\fR the process being
run in the \fIgterm\fR window is not the default SHELL process.
If this option is in effect, typing one of the \fIstty\fR suspend-process
control characters \fBsusp\fR or \fBdsusp\fR while the terminal is not in raw
mode will cause the character to be echoed in the text window, but to be
otherwise ignored.  This may be desirable if the process being run in the
\fIgterm\fR window is not capable of restarting itself after it has been
suspended (see also the \fBcontinue\fR frame menu option).
.TP
\fIttyargs\fR
\fIgterm\fR also takes generic tool arguments; see \fIsuntools\fR(1) for a
list of these arguments.  The \fIttyargs\fR generic tool arguments affect
only the text window.
.TP
.B \-G
Generic tool arguments preceding this optional placeholder switch affect only
the text window; those following the switch affect only the graphics window.
.TP
\fB-Gopen \fR(\fPnoaction \fR|\fP show \fR|\fP expose\fR)\fP
Specifies the action to be taken when graphics mode is entered, i.e., when
terminal i/o is redirected from the text window to the graphics window.
\fBnoaction\fR means do nothing which visibly affects the screen.
\fBshow\fR means display the graphics frame if it is not already visible on
the screen, i.e., because the graphics window has been closed.
\fBexpose\fR means move the graphics window, if already displayed, to the
top of the stack of open windows.
.TP
\fB-Gclose \fR(\fPnoaction \fR|\fP blank \fR|\fP hide\fR)\fP
Specifies the action to be taken when graphics mode is exited, restoring
terminal i/o to the text window.
\fBnoaction\fR means do nothing which visibly affects the screen.
\fBblank\fR means close the graphics subwindow, causing the window to
disappear from the screen (the closed window can be redisplayed at any time
provided the contents are \fIretained\fR).
\fBhide\fR means move the graphics window to the bottom of the stack of
open windows.
.TP
\fB\-\fR[\fPno\fR]\fPpause
Pause before closing the graphics window and returning to text mode,
after opening the graphics frame to display a plot noninteractively
(no cursor reads).  If \fB\-nopause\fR is specified and the \fB\-Gclose\fR
option is \fBblank\fR, a newly plotted graph will disappear immediately after
the plotting operation is completed, assuming no blocking operation such as
a cursor read occurs while in graphics mode.  If \fB\-pause\fR is specified
\fIgterm\fR will detect this condition and pause for a keystroke to be typed
before exiting graphics mode.
.TP
\fB\-\fR[\fPno\fR]\fPretain
Specifies whether or not the contents of the graphics frame are to be retained.
If \fB\-noretain\fR is specified plotting will be somewhat faster, but any
window event which affects the region of the workstation screen occupied by
the graphics frame will cause the plot to be lost.
.TP
\fB\-\fR[\fPno\fR]\fPclip
Specifies whether or not clipping of graphics vectors is to be performed.
If \fB\-noclip\fR is specified plotting will be somewhat faster, but vectors
may be drawn outside the graphics window if the screen changes while a graph
is being drawn.
.TP
\fB\-\fR[\fPno\fR]\fPreverse
Specifies whether the graphics frame is to be displayed in normal or reverse
video.  What constitutes normal video depends upon whether color or monochrome
is specified, and upon what has been specified for the foreground and
background colors.  Reverse video swaps the foreground and background colors
within the graphics window.
.TP
.B \-color
Display the graphics frame in two colors, if \fIgterm\fR is run on a color
workstation.
.TP
.B \-mono
Display the graphics frame in monochrome, using the foreground and background
colors specified when \fIsuntools\fR(1) was started.
.TP
.B \-ginterm \fR[\fIchar \fR[\fIchar\fR]]
Set the GIN terminator character or characters (used to delimit the value
returned for a cursor read) to the indicated octal values \fIchar\fR.
If a \fIchar\fR value is omitted the corresponding GIN mode terminator will
be omitted when a cursor value is returned.  For example, "\-ginterm" causes
both GIN delimiter characters to be omitted, and "\-ginterm 015" causes the
single GIN terminator character CR (carriage return) to be transmitted.
.TP
\fIgioargs\fR
\fIgterm\fR also takes generic tool arguments; see \fIsuntools\fR(1) for a
list of these arguments.  The \fIgioargs\fR generic tool arguments affect
only the graphics subwindow, and are recognized only after the \fB\-G\fR
placeholder argument.
.TP
[\fIprogram\fP [\fIargs\fP]]
If a \fIprogram\fR argument is present, the named program is run in the
\fIgterm\fR window without spawning an intermediate shell.
If no \fIprogram\fR is specified,
\fIgterm\fR runs the shell specified by your \fLSHELL\fR environment
variable.  If this environment variable is not defined, \fIgterm\fR runs
\fB/bin/sh\fR.
.LP
Minimum match abbreviations are permitted for all \fIgterm\fR arguments except
the generic tool arguments, which have two character aliases.  Use of the full
names is however recommended, as the number of characters required for minimum
matching a specific argument may change in a future release of \fIgterm\fR
when new command line arguments are added.
.if t .sp 0.08i
.SH DESCRIPTION
.SS Virtual Graphics Terminal
.LP
\fIgterm\fR is a virtual graphics terminal implemented as a set of windows
running within the SunView environment.  The terminal consists of two primary
windows, a \fBtext window\fR and a \fBgraphics window\fR, and several special
purpose subwindows, the most important of which is the \fBsetup panel\fR,
used to dynamically change \fIgterm\fR options at runtime, or to reset the
terminal to a known state.  The virtual terminal is interfaced to applications
programs via the UNIX pseudoterminal or \fIpty\fR(4) interface, providing an
applications interface identical to that provided for ordinary terminals,
allowing applications running either on the local machine or on a remote
node communicating via a network interface (\fItelnet\fR, \fIrlogin\fR,
modem etc.) to communicate transparently with the \fIgterm\fR virtual terminal.
.if t .sp 0.08i
.SS Text Window
.LP
The text window is a standard SunView TTY subwindow, as used in
\fIshelltool\fR, \fIgfxtool\fR, and so on.  Documentation for tty subwindows,
including both user documentation and a description of the special escape
sequences recognized by tty subwindows, is given in \fIshelltool\fR(1).  
In particular, note that a \fB.ttyswrc\fR file may be placed in one's login
directory to set tty subwindow parameters, and to map function keys to control
sequences to be sent either to the tty subwindow or to the program running in
the tty subwindow.  The \fBselection service\fR can be useful for passing
text to programs via the mouse instead of the keyboard, and numerous terminal
\fBescape sequences\fR are defined for resizing the text window, setting the
frame label, and so on.
.if t .sp 0.08i
.SS Graphics Window
The graphics window emulates a Tektronix 4012 terminal with minor differences,
e.g., the screen size is 35x80 rather than 35x75, and some significant
extensions, e.g., graphics and text can be selectively erased, and support
is provided for a \fBstatus line\fR at the bottom of the screen, in which text
can be dynamically read and written without affecting the contents of the
graphics plane.  Although nonstandard, these features are very useful when
designing interactive user interfaces, and they can be emulated on most
modern graphics terminals (hence programs which use these features need not
be device dependent).
.LP
The position and size of the graphics window may be set at startup time via
the generic tool arguments \fIgioargs\fR.  A number of preprogrammed sizes
may also be selected via the setup panel at runtime, or the mouse may be used
to directly resize the window to produce a window of any size and aspect ratio.
The standard graphics window sizes range from very small to the full screen
and all share the same standard landscape mode aspect ratio; users should note
that manually adjusting the window size usually results in a window with a
nonstandard aspect ratio, which may cause graphics programs which assume the
standard aspect ratio to misbehave, producing oddly shaped objects, or poorly
centered text strings.
.LP
\fIgterm\fR will automatically detect any changes in the size of the graphics
window, adjusting the transformation from 4012 coordinates (780x1024) to
screen coordinates so that subsequent graphics and text will be drawn at the
correct relative position within the window.  The best text font for the new
window size is also selected; if the window is of an arbitrary size it will
not in general be possible to select a font which provides exactly 35x80
characters on the screen without overlap, since there are only a limited number
of fixed size fonts to choose from.  If the window is especially wide and
short text lines may overlap vertically.  After resizing the graphics window,
the previously displayed graph \fImust\fR be redrawn under program control to
adjust the graph to fit the new window.
.LP
By default, the graphics window overlaps the text window, with eight or ten
characters of text visible to the left of the graphics window.  If the graphics
window is left in its default position and the text window is repositioned on
the workstation screen, the graphics window will "track" the text window,
i.e., retain its position relative to the text window (this is desirable when
there are multiple instances of \fIgterm\fR in use at one time to avoid losing
track of which graphics frame goes with which text window).  If the graphics
window is manually repositioned, however, then thereafter the positions of
the two windows are completely independent.
.LP
Although the graphics window is normally used only for graphics (plotting),
one should not forget that the graphics window emulates an (80 column wide)
Tektronix 4012 terminal, and hence may be used as a terminal for ordinary
text i/o, as well as for graphics.  The TTY subwindow will normally be
superior for terminal graphics, but the extra page of text and the larger,
brighter font typically used in the graphics window may occasionally be useful
for some applications.  Text i/o may easily be switched back and forth between
the text and graphics windows via the function keys described below,
transparently to most applications software.
.if t .sp 0.08i
.SS Active Window
.LP
At any one time, terminal output is always directed to either the text window
or the graphics window, but never to both at the same time.  When output is
directed to the text window the terminal is said to be in \fBtext mode\fR,
and when output is directed to the graphics window the terminal is said to
be in \fBgraphics mode\fR, although either text or graphics may be written
into the graphics plane.  Mode switching is normally in response to control
codes embedded in the input data stream from the applications program being
run, but keyboard function keys may be used to manually perform mode switching
if desired.
.LP
Keyboard \fIinput\fR may be directed to either window at any time, regardless
of which window is currently active, i.e., text may be typed into one window
but echoed in the other window.  This can be confusing if the window in which
text is echoed is not currently displayed; one types and nothing seems to be
happening, but in fact commands are being input and executed normally.
For example, if the \fB\-Gclose\fR option is set to \fBnoaction\fR and the
graphics window is adjusted to fill the full screen, then when graphics mode
is exited terminal output will be directed to the text window, but the text
window will be covered by the graphics window, and subsequent commands and
textual output will not be visible without manually redisplaying the text
window (or undisplaying the graphics window) with a function key.
.if t .sp 0.08i
.SS The Frame Menu
.LP
\fIgterm\fR uses a special frame menu which may be called up by the mouse
at any time, by placing the cursor on the border of the \fItext window\fR and
holding down the right mouse button.
The items in the \fIgterm\fR frame menu are as follows:
.RS
.IP "\fBFrame\fP" 15
Access the standard SunView frame menu.
.IP "\fBSetup\fP"
Display the setup panel.
.IP "\fBContinue\fP"
Send the SIGCONT signal to the process group attached to the \fIgterm\fR
window, e.g., after accidentally suspending a process which cannot otherwise
restart itself.  See also the \fB\-ignore\fR command line option.
.IP "\fBShow graph\fP"
Display the graphics window.
.IP "\fBTextcopy\fP"
Make a hardcopy of the text window.
.IP "\fBGraphcopy\fP"
Make a hardcopy of the graphics window.
(IRAF users should use the cursor mode \fIsnap\fR function instead).
.IP "\fBScreencopy\fP"
Make a hardcopy of the full screen.
.RE
.LP
The textcopy, graphcopy, and screencopy selections are all entry points to the
general screen capture utility, discussed in the next section.
.if t .sp 0.08i
.SS Hardcopy Output
.LP
The hardcopy functions produce a "what you see is what you get" bitmap of the
rectangular region of the screen occupied by the indicated object of interest.
If the region of interest is partially covered by another window, then the
hardcopy will be a picture of a partially covered window.
If the window is displayed in reverse video, the hardcopy will also be
rendered in reverse video.
.LP
The screen capture software reads out the full memory of the workstation in
the region of interest, and in the case of a color workstation, processes the
screen pixels through the colortable to produce an image corresponding to what
appears on the screen.  No full color output options
are currently provided, hence the average of the red, green, and blue color
values is next computed.  If a bitmap output image is desired a simple
thresholding algorithm is used to produce the final bitmap image,
otherwise a greyscale image is produced.  If rasterfile output
is being generated, the raw pixel values and RGB color table entries are saved
directly in the rasterfile, rather than applying the tables in software to
produce a monochrome or bitmap image.
.LP
Two output options are currently provided, i.e., \fBPostscript\fR output
suitable for output directly to a laser writer to produce the final graphics
hardcopy, or \fBSun rasterfile\fR output.  The default action is to output a
Postscript program to the device "lw", e.g., the Apple Laserwriter
(any 300 dpi Postscript device should do).
These defaults may be changed by defining the following environment variables:
.IP R_RASTERFILE
If this variable is defined a Sun rasterfile will be generated, otherwise a
Postscript plotfile is generated.  The string value of the variable is a
\fIprintf\fR style format string to be used to generate the filename of
the rasterfile.  If multiple rasterfiles are to be generated, the format
string may contain a decimal integer field (e.g., "\fLframe.%d\fR") to be
replaced by the \fIfile number\fR of the current rasterfile.  The first file
generated will be number zero, with the file number being incremented once
for every rasterfile produced.  If Postscript plotfile output is desired,
the plotfile will be a uniquely named temporary file in \fB/tmp\fR.
.IP R_DISPOSE
The string value of this variable is a \fIprintf\fR style format string with
one string valued subfield to be replaced by the plotfile or rasterfile name,
to be used to generate the command used to dispose of the output file.
If this variable is not defined and the output file is a Postscript plotfile,
the default format string \fL"lpr -Plw -r -s %s"\fR will be used.
If the variable is not defined and the output file is a rasterfile,
no action is taken.  It is the responsibility of the dispose command to
delete the output file.
.LP
It should only take several seconds to capture the screen and produce the
output rasterfile or queue the Postscript job to the printer.  The screen
is flashed to indicated when the operation has completed.  The Postscript
processing time may take up to several minutes (of laserwriter time) in the
worst case, i.e., a hardcopy of the full workstation screen.
.if t .sp 0.08i
.SS The Setup Panel
.LP
The setup panel is used to dynamically change terminal options while the
terminal is in use.  In general, nearly any terminal option which can be
set on the command line when \fBgterm\fR is started can also be set via the
setup panel, and vice versa.  The setup panel can also be used to reset
the terminal to the startup or "power on" state.
The setup panel may be called up at any time via the frame menu; it is normally
closed after the desired setup action has been performed.  By default the setup
panel is located within the text window, but it may be moved anywhere else on
the workstation screen if desired.
.LP
There are two types of items in the setup panel: multiple choice options and
"push buttons".  To see what the choices are in a multiple choice option,
position the mouse to the area where the current choice is displayed and
depress the right mouse button.  At this point a selection may be made by
moving the mouse to the desired selection and releasing the mouse button.
Alternatively, the left mouse button may be used to cycle through the choices.
To perform the action indicated on a push button, place the mouse cursor on
the button and press the left mouse button.
.LP
The multiple choice options in the setup panel are the following:
.IP "\fBGraphics plane"
These options determine what the terminal does when graphics data and
control instructions are encountered in the input stream.
\fBDisable\fR means disable the graphics plane, causing the terminal to
output graphics control codes and data as printable characters
in the text window.
\fBEnable\fR means enable the graphics plane for normal mixed text and
graphics operation.
\fBDiscard Graphics Data\fR means discard all graphics data, effectively
disabling the graphics plane.
.IP "\fBOpen workstation action\fR"
These options determine the action taken by the terminal when graphics mode
is entered.  Some visible action is generally desirable to render the graphics
window fully visible, and to indicate that a mode switch has occurred.
\fBNo action\fR means do nothing which visibly affects the workstation.
\fBShow graphics\fR means open the graphics window, e.g., if the graphics
window is to be closed (not displayed) when the terminal is in text mode.
\fBExpose graphics\fR means move the graphics window to the top of the stack
of open windows, displaying any portions of the graphics window which may have
been covered by other windows (such as the text window).
.IP "\\fBClose workstation action\\fR"
These options determine the action taken by the terminal when graphics mode
is exited, returning the terminal to text mode.
\fBNo action\fR means do nothing.
\fBBlank graphics\fR means close the graphics window, i.e., remove the window
from the screen.
\fBHide graphics\fR means move the graphics window to the bottom of the stack
of open windows, allowing any overlapping windows to cover the graphics window.
.IP "\\fBPause on close workstation\\fR"
This boolean option determines whether or not the terminal displays the
\fBpause panel\fR, waiting for a key to be typed, before exiting graphics
mode following a noninteractive graphics session (no cursor input).
.IP "\\fBRetain graphics frame\\fR"
This boolean option determines whether or not the contents of the graphics
window are \fIretained\fR.  Graphics drawing will be somewhat faster if the
graphics plane is not retained, but almost any event which affects the region
of the screen occupied by the graphics window will cause the contents
of an unretained window to be lost.
.IP "\\fBClip graphics\\fR"
This boolean option determines whether or not graphics vectors are clipped
to the boundaries of the visible portions of the graphics window.  Graphics
drawing will be somewhat faster if clipping is disabled, but
vectors may be drawn in nearby, unrelated windows,
especially if the graphics window is partially covered by other windows.
.IP "\\fBGraphics screen type\\fR"
This option determines whether the graphics plane is to be displayed in color
or monochrome on a color workstation.  If \fBmono\fR is selected the foreground
and background colors specified when \fIsuntools\fR was started are used.
If \fBcolor\fR is specified graphics will be rendered in color, with the
colors used being specified by the \fB\-Wb\fR and \fB\-Wf\fR generic tool
arguments in \fIgioargs\fR.  On a monochrome workstation the only option
displayed will be \fBmono only\fR, indicating that color is not available.
.IP "\\fBGraphics video\\fR"
This option specifies whether graphics are to be rendered in \fBnormal\fR or
\fBreverse\fR video.  Specifying reverse video causes the foreground and
background colors of the graphics window to be reversed.
This option may not work on some monochrome workstations.
.IP "\fBGraphics font and screen sizes\fR"
This option is used to select at runtime the size of graphics window to be used.
The graphics window may be resized at any time, including while graphics is
being drawn or during a cursor read, but any displayed graphics should always
be redrawn following a window resize to ensure that the graph reflects the new
coordinate system.
The graphics window configurations currently available are listed below
in the form ``\fIpointsize\fR:[\fIwidth\fRx\fIheight\fR]'',
where \fIwidth\fR and \fIheight\fR are in pixels.  The size of the full screen
is workstation dependent, the most common size currently being 1152x900.
The exact set of fonts and screen sizes may change in the future as new
fonts become available and workstations increase in resolution.
.if t .sp 0.05i
.ti +0.3i
10:[560x420] 12:[640x490] 14:[720x560] 16:[800x630] 18:[880x665] 24:fullscreen
.if t .sp 0.05i
All choices represent 35x80 windows with the standard landscape mode aspect
ratio.  The size of the graphics window is the size in pixels of a character
of the fixed width font used, scaled by 35 vertically and by 80 horizontally.
Arbitrary sized windows may also be created by manually sizing the window
with the mouse, but this is bound to result in windows with a nonstandard
number of lines or columns of text, or a nonstandard aspect ratio.
.IP "\fBGIN mode terminators\fR"
Set the GIN (graphics or cursor mode input) terminator characters to the
indicated octal values.  When a key is hit to terminate a cursor read, the
terminal transmits a 5 character cursor value sequence to the applications
program, following by one or two GIN mode terminator characters.
The required GIN mode terminator(s) will in general depend upon the
applications program being run.  Some programs require no terminators,
others require a single CR (octal 015), and so on.
The default GIN mode terminator is a single CR.
.if t .sp 0.05i
To enter a new value, select the value box with the left mouse button,
rubout the old value, and type in the new value as a string, with zero, one,
or two octal values denoting the desired terminator characters, then hit
return to establish the new value.  Entering a blank string disables both
terminators.
.LP
The following "push buttons" are also provided in the setup panel:
.RS
.IP \fBReset\fR 15
Reset the terminal to the "power on" state, preserving the values of any
options set on the command line, but cancelling any options selected via
the setup panel.  A \fBsetup reset\fR is indicated if the terminal does not
seem to be behaving correctly.  Resetting the internal state of the terminal
has no effect on the operation of any applications program being run from
the terminal.
.IP \fBClear\fR
Clear the text window (the F9 function key performs the same function).
.IP \fBGclear\fR
Clear the graphics window, leaving the terminal in graphics mode
(the F8 function key performs the same function).
.IP "\fBShow graphics\fR"
Open (display) or close (undisplay) the graphics frame.  The contents of the
graphics frame are not affected.
.IP \fBQuit\fR
Close the setup panel.
.RE
.LP
Closing and opening either the text or graphics frame has no effect on the
state of the terminal or on the applications program running within it,
even while a cursor read is in progress.
.if t .sp 0.08i
.SS Function Keys
.LP
The following function keys have special significance to \fIgterm\fR:
.RS
.IP F8 15
In text mode, causes a switch to graphics mode.
When already in graphics mode, causes the graphics frame to be cleared.
.IP F9
In graphics mode, causes a switch to text mode.
When already in text mode, causes the text frame to be cleared.
.RE
.LP
To momentarily view the graphics frame while in text mode, one can type F8
followed by F9, without affecting the contents of either window.
Commands may be entered in either window, hence to direct the output of
a command to the graphics window, one could hit F8, execute the command,
and then hit F9 to return to the text window.  The standard SunView L7 key,
used to close a window, is also detected by \fIgterm\fR,
hence closing the graphics
window with L7 while in graphics mode will automatically cause the terminal
to revert to text mode.
.LP
Manual control of the terminal mode is sometimes necessary when running
naive graphics programs in a \fIgterm\fR window.
When running a graphics program
which uses only standard 4012 instructions, it may be necessary to manually
put the terminal into graphics mode with the F8 function key before running the
program, or part of the program output may be "lost" (directed to the text
window and discarded).  Similarly, naive programs will not return the terminal
to text mode after generating a plot, hence it will be necessary for the
user to hit the F9 key to return to text mode.
.LP
Additional function keys may be defined in the user \fB~/.ttyswrc\fR file.
For example, the function key definitions
.if t .sp 0.05i
.if n .sp
.RS
.nf
mapo R1 ^[[8;24;80t
mapo R2 ^[[8;34;80t
mapo R3 ^[[8;40;80t
.fi
.RE
.if t .sp 0.05i
.if n .sp
will program the R1, R2, and R3 function keys to set the size of the text
window to 24, 34, or 40 lines by 80 columns when the corresponding function
key is typed.  These definitions are handy for rapidly resizing the text
window to one of the "standard" terminal sizes; this is especially useful
when executing programs remotely over the network, as most such programs
assume some standard size terminal screen.
.if t .sp 0.08i
.SS Mouse Buttons
.LP
The significance of the mouse buttons depends upon which window the mouse is
in, and upon whether or not the terminal is in GIN mode, i.e., in the process
of reading the graphics cursor.  When the terminal is in text mode and the
mouse is in the text window, the mouse buttons are used only for the
\fBselection service\fR, as described in \fIshelltool\fR(1).
The functions of the mouse buttons while the mouse is in the graphics window
are outlined below.
.RS
.IP "Left button" 15
Ignored except in GIN mode, when it may be aliased to a keyboard key and used
to terminate a cursor read.
.IP "Middle button"
Ignored except in GIN mode, when it may be aliased to a keyboard key and used
to terminate a cursor read.
.IP "Right button"
In GIN mode, may be aliased to a keyboard key and used to terminate a cursor
read.  When not in GIN mode, causes the cursor crosshairs to be displayed
while the button is depressed.
.RE
.LP
The ability to \fBalias\fR mouse buttons to keyboard keys is a very important
one as it allows arbitrary graphics programs which are driven via an
interactive graphics cursor loop to be controlled completely from the mouse,
rather than having to position the mouse and then hit a key on the keyboard
to terminate each cursor read.  For example, to alias \fIkey\fR to the left
mouse button, one would depress the control key and tap the left mouse button
twice, immediately after hitting \fIkey\fR to terminate a normal cursor read.
Thereafter, either \fIkey\fR or the left mouse button may be used equivalently
to terminate a cursor read.  The alias remains in effect until the terminal is
\fIreset\fR or the alias is reassigned to a different key.
.if t .sp 0.08i
.SS The Terminal Emulator
.LP
The normal function of the terminal is to simultaneously listen for input
(program output) on the pseudoterminal file descriptor, while servicing
asynchronous keyboard and mouse events generated by the user.
The input data stream from the applications program consists of a mixture
of text and graphics data transmitted as an ASCII byte stream with no record
boundaries.  Null bytes in the input data stream are ignored, and no programmed
delays are needed for proper terminal operation.  As input data is received
asynchronously it is copied into a circular buffer and a synchronous event is
queued to call a routine which subsequently processes the input characters
onto the screen.  If input data arrives faster than it can be processed onto
the screen \fB<ctrl/s>\fR is transmitted to the \fIpty\fR terminal driver,
followed by \fB<ctrl/q>\fR once the circular buffer empties.
Characters typed by the user are transmitted directly to the terminal driver,
which in normal operation will echo the characters back to the terminal as
ordinary data.
.LP
The initial state of the terminal is text mode.  Transition to graphics mode
occurs when the GS character is encountered in the input data stream.
Transition back to text mode occurs when the CAN character is encountered in
the input stream.  While text mode is in effect all input is passed on to the
TTY subwindow; while graphics mode is in effect all input is passed on to the
graphics subwindow.  The behavior of the ANSI standard TTY subwindow is
documented elsewhere (e.g., \fIshelltool\fR(1), \fIcons\fR(4s), and Chapter 10
of the \fISunView Programmer's Guide\fR) hence will not be discussed further
here.  Likewise, the basic Tektronix 4012 protocol is a well known standard
and need not be documented in detail here.
.LP
The control codes and escape sequences recognized by the \fIgterm\fR graphics
window are summarized below.  Sequences marked with a \(**\(** at the right
are nonstandard extensions, although all except the status line feature are
fairly common extensions.
.if t .sp 0.05i
.ta +0.5i +1.5i +3.5i
.nf
	GS (035)	\fBopen workstation\fR, start normal vector drawing sequence
	CAN (030)	\fBclose workstation\fR	**
	FS (034)	start pointmode vector
	US (037)	set alpha mode
	CR (015)	set alpha mode and execute carriage return
	BEL (007)	ring bell and/or flash screen
.if t .sp 0.05i
	ESC CR	set status line mode (ESC = 033)	**
	ESC ENQ	inquire graphics state and cursor position
	ESC SUB	initiate a cursor read (SUB = 032)
	ESC FF	clear screen, home alpha cursor (FF = 014)
	ESC / f	set cursor position to current drawing coordinates	**
	ESC 0	set character size 0
	ESC 1	set character size 1 [not implemented]
	ESC 2	set character size 2 [not implemented]
	ESC 3	set character size 3 [not implemented]
	ESC / 0 d	set data level 0 (clear bits)	**
	ESC / 1 d	set data level 1 (set bits)	**
	ESC / 2 d	set data level 2 (toggle bits)	**
	ESC `	set line style 0 (solid)
	ESC a	set line style 1 (dashed)
	ESC b	set line style 2 (dotted)
	ESC c	set line style 3 (dashdot)
	ESC d	set line style 4 (dash3dot)
	ESC / 0 w	set line width 0 (1 pixel)	**
	ESC / 1 w	set line width 1 (2 pixels)	**
	ESC / 2 w	set line width 2 (3 pixels)	**
.fi
.if t .sp 0.05i
.LP
Both text and vectors may be erased by setting the data level to 0 and
redrawing the objects to be erased.  Erasing points which are common to more
than one object will cause gaps in other objects sharing the erased point.
.LP
Setting \fBstatus line\fR mode causes the region of the graphics frame
occupied by the status line to be saved in a memory pixrect, after which the
status line is cleared and the status line alpha cursor positioned to the
start of the line (the status line is a single 80 character line of text at
the bottom of the graphics window).  While output is directed to the status
line, data characters are output in the status line as for a terminal.
BS and DEL behave as expected, allowing characters to be erased.
Lines longer than 80 characters are truncated at the right margin.
LF (newline) is treated the same as CR, causing the entire line to be erased,
and if multiple lines of text are rapidly written to the status line
they will scroll as on a one-line terminal.  Status line mode is terminated
by any control character in the input data stream, e.g., GS, FS, CAN, ESC,
and so on.  Note that terminating status line mode does not in itself erase
the status line, restoring the saved region of the graphics frame to the
screen; this is done by transmitting newline or CR to the terminal.
.if t .sp 0.08i
.SH SEE ALSO
suntools(1), shelltool(1), tektool(1), cmdtool(1), pty(4), cons(4s)
.br
\fISunView Programmer's Guide\fR, Chapter 10 \- TTY Subwindows
.br
\fIWindows and Window-Based Tools: Beginner's Guide\fR
.if t .sp 0.08i
.SH FILES
.LP
.nf
~/.ttyswrc
/usr/bin/suntools
/usr/lib/rootmenu
/usr/lib/fonts/fixedwidthfonts/*
$iraf/local/sun/gterm.c
.fi
.if t .sp 0.08i
.SH BUGS
.IP (1)
\fIgterm\fR is a complex program operating in an extremely dynamic environment.
The program has been thoroughly tested and is quite reliable, but it is
nonetheless possible for the program to get into peculiar states where it
does not behave as expected.  Should this happen, a \fIsetup reset\fR should
restore the terminal to a known state.
.IP (2)
If more than 256 characters are input to a terminal emulator subwindow without
an intervening newline, the terminal emulator may hang (to demonstrate this,
hold any key down until the autorepeat generates sufficient characters).
If this occurs, display the tty subwindow menu and select the \fBflush input\fR
item to correct the problem.
.IP (3)
When using a terminal emulator to execute a program on a remote node via a
network interface (rlogin, telnet, etc.), and the remote program continuously
outputs a large amount of data, the terminal will occasionally hang up for
several seconds, after which normal output will resume.  Typing any character
will cause output to resume immediately, but the character will later be
delivered to the remote program as normal input hence should be selected with
care (\fB<ctrl/q>\fR is always harmless).  The origin of this bug is not clear,
but since all terminal emulators are equally affected, it must be something
in the terminal driver, or elsewhere in the SunOS kernel.
.IP (4)
The hardcopy functions assume a 1 or 8 bit frame buffer and will not work
properly on a Sun-3/110, 3/60, etc., unless the \fB\-8bit_color_only\fR option
is specified to \fIsuntools\fR [\fIfixed in Gterm V1.2]\fR.
.IP (5)
Reverse video does not work on a monochrome workstation as there is no
colortable and no way to exchange the foreground and background colortable
entries; try the \fB\-i\fR option to \fIsuntools\fR instead.
.IP (6)
\fIgterm\fR modifies the keyboard translation table entries for the arrow keys
while a cursor read is in progress, restoring the translation table entries
when done (this is necessary to allow the arrow keys to be used to terminate
cursor reads).  If something should happen to \fIgterm\fR while it is waiting
for cursor input, it is possible that the arrow key translation table entries
may not be restored.  If this should happen, executing \fBsetkeys reset\fR will
fix things.  Note also that changes to the keyboard translation tables are
global, i.e., all windows are affected, hence while a cursor read is in
progress in a \figterm\fR window, the arrow keys may not be usable with a
program running in a different window.
.IP (7)
When plotting with clipping disabled there are cases where it is possible for
\fIgterm\fR to coredump with a segmentation violation, killing any interactive
subprocesses running within the terminal.
.SH AUTHOR
Doug Tody, National Optical Astronomy Observatories (NOAO), IRAF project.