diff options
Diffstat (limited to 'vendor/x11iraf/man/xgterm.1')
| -rw-r--r-- | vendor/x11iraf/man/xgterm.1 | 981 |
1 files changed, 981 insertions, 0 deletions
diff --git a/vendor/x11iraf/man/xgterm.1 b/vendor/x11iraf/man/xgterm.1 new file mode 100644 index 00000000..5ed5163d --- /dev/null +++ b/vendor/x11iraf/man/xgterm.1 @@ -0,0 +1,981 @@ +.\" @(#)xgterm.1 1.1 16-Dec-96 MJF +.TH XGTERM 1 "16 Dec 1996" "X11IRAF Project" +.SH NAME +xgterm \- terminal emulator for X with graphics and imaging capability +.SH SYNOPSIS +\fBxgterm\fP [\-\fItoolkitoption\fP ...] [\-\fIoption\fP ...] +.SH DESCRIPTION +The \fIxgterm\fP program is a terminal emulator for the X Window System +based largely on \fIxterm\fP but with a completely new graphics and imaging +widget. It provides DEC VT102 and Tektronix 4014 compatible terminals for +programs that can't use the window system directly. \fIXGterm\fP also +serves as a prototype for the \fIWidget Server\fP being developed by the +IRAF Project at NOAO. The \fIObject Manager Library\fP it uses implements a +window system toolkit as an interpreted window-object language, allowing +application GUIs to be defined and executed at runtime without compiling +any code, and with minimal dependence upon the underlying window system +toolkit library. We will concentrate here, however, on it's use as a terminal +emulator and a description of the new \fIGterm\fP widget. +.PP +The Gterm graphics window operates almost identically to the \fIxterm\fP Tek +window, however there are extensions for implementing full-screen cursors, +imaging, area fills, colors, graphics erasure, a "status line" and so on. +Any graphics application capable of running under an \fIxterm\fP Tek window +should also be able to use \fIxgterm\fP as well. Client programs wishing to +make use of the extended features, or those wishing to implement a GUI, are +advised to use the OBM (\fIObject Manager\fP) library supplied with the XGterm +source as part of the X11IRAF package. This provides a much better +programmatic interface to all of the features available; however, as of +this writing it is not yet fully documented. Users are referred to the +\fIXImtool\fP task as an example of a more complex application using the +\fIOBM Library\fP and \fIGterm\fP widget, as well as demo tasks in the +\fIguidemo\fP directory of the X11IRAF sources. Questions or comments may +also be sent to \fIiraf@noao.edu\fP. +.PP +The VT102 text window is unchanged from the original \fIxterm\fR application. +All of it's resources, command-line options and operation are identical to +that used by \fIxterm\fP. The \fItermcap(5)\fP entry for \fIxterm\fP may +be used for \fIxgterm\fP as well. See the \fIxterm(1)\fP man page for details. +.SH OPTIONS +All \fIxterm(1)\fP and X Toolkit command line options are supported, there +are no additional options. +.SH RESOURCES +The program understands all of the core X Toolkit resource names and +classes, all text window resources known to \fIxterm(1)\fP, as well as +the \fIGterm\fP (graphics and imaging widget) resources. The proper Class +name for all resources described here is \fIGterm\fP. A table of +available \fIGterm\fP resources and their defaults may be found below, +some of the more interesting resources are described here in detail: +.TP 5 +\fIbasePixel\fP +Base cell of the custom colormap. This essentially allows you +to reserve \fIbasePixel\fP colors in the global colormap for other +applications. The default is 38, if changed you'll need to also enable +the \fIcmapInitialize\fP resource to force the Gterm widget to +update it's global colormap resource in the X server. +.TP 5 +\fIcmapInitialize\fP +Initialize the ximtool colormap at startup. When resetting the \fIbasePixel\fP +resource or colormap this is required in order to force the Gterm widget to +update it's global colormap resource in the X server. The default is False. +.TP 5 +\fIcmapInterpolate\fP +Interpolate the colormap to the number of display colors. The default is +True. +.TP 5 +\fIcmapName\fP +Name used for private colormap. The default for all IRAF imaging +applications is \fIimage\fP. Gterm widget based imaging applications +which have the same value of cmapName will share the same colormap, +minimizing colormap flashing and allowing multiple applications to be +run at the same time. +.TP 5 +\fIcolor0\fP +The widget background color. The default is black. +.TP 5 +\fIcolor1\fP +The widget foreground color. The default is white. +.TP 5 +\fIcolor2\fP thru \fIcolor9\fP +Optional drawing colors. The line color used for graphics is set using +an escape sequence to select the current color index. See \fIGterm I/O +Escape Sequences\fP below for more details. +.TP 5 +\fIcrosshairCursorColor\fP +Color of the full screen crosshair cursor. +.TP 5 +\fIdefaultMarker\fP +Default marker type. Options include \fItext\fP, \fIline\fP, \fIpolyline\fP, +\fIrectangle\fP, \fIbox\fP, \fIcircle\fP, \fIellipse\fP, and \fIpolygon\fP. +The default is \fIrectangle\fP. +.TP 5 +\fIdeiconifyWindow\fP +De-iconify the Gterm graphics window when activated. The default is False. +.TP 5 +\fIdialogBgColor\fP +Dialog box (i.e. the status line) background color. Dialog text is text which +is drawn into the dialog area at the bottom of the gterm window, it is +transient and is not a permanent part of the graphics being drawn. Dialog +text is normally used to interact with the user or to display messages +during program operation, without affecting the graphics being drawn. +.TP 5 +\fIdialogFgColor\fP +Dialog box (i.e. status line) foreground color. +.TP 5 +\fIginmodeBlinkInterval\fP +Graphics cursor blink interval, time is specified in milliseconds. The +default is 0. +.TP 5 +\fIginmodeCursor\fP +Graphics mode cursor type. The default is a full screen cursor custom to +the widget. +.TP 5 +\fIheight\fP +Height of the Gterm window. The default is 480. +.TP 5 +\fIidleCursor\fP +Cursor to use when not in graphics mode. The default is a plus sign. +.TP 5 +\fImarkerHighlightColor\fP +Highlight color for the active marker. When the pointer moves into a marker +is it marked "active", the highlight color and width change to which marker +is active. The default is green. +.TP 5 +\fImarkerHighlightWidth\fP +Highlight width for the active marker. The default is 2. +.TP 5 +\fImaxColors\fP +The maximum number of colors to use in the private global colormap, the +default is 216. Out of this number 10 colors (the \fIcolor0\fP thru +\fIcolor9\fP values) are reserved by the widget as static colors, the +remainder may be allocated for images. +.TP 5 +\fIraiseWindow\fP +Raise the window when active. The default is False. +.TP 5 +\fIwarpCursor\fP +Warp the cursor to the window when active. The default is False. +.TP 5 +\fIwidth\fP +Width of the Gterm window. The default is 640. + +.SH "GTERM WIDGET RESOURCES" + +.SS "Class Hierarchy" +.PP +\fBCore -> Gterm\fP +.SS "Resources" +.PP +When creating a Gterm widget instance, the following resources are retrieved +from the arguments list or from the resource database: + +.TS +center; +lB lB lB lB +l l l l. +Name Class Type Default Description += +alphaFont1 XFontStruct nil2 Graphics fonts +alphaFont2 XFontStruct 5x8 " +alphaFont3 XFontStruct 6x10 " +alphaFont4 XFontStruct 7x13 " +alphaFont5 XFontStruct 8x13 " +alphaFont6 XFontStruct 9x15 " +alphaFont7 XFontStruct 9x15 " +alphaFont8 XFontStruct 9x15 " +basePixel Int 38 Base of private global colormap +busyCursor String watch Cursor to use when application is busy +busyCursorBgColor Foreground white Busy cursor background color +busyCursorFgColor Foreground black Busy cursor foreground color +cacheRasters String whenNeeded Save rasters as server pixmaps for faster access +cmapInitialize Boolean False Initialize colormap at startup +cmapInterpolate Boolean True Interpolate colormap +cmapName String default Custom colormap name +cmapShadow Int 10 Colormap shadow interval +cmapUpdate Int 60 Colormap update interval +color0 Background black Default graphics background color +color1 Foreground white Default graphics foreground color +color2 Foreground red Optional drawing color +color3 Foreground green " +color4 Foreground blue " +color5 Foreground cyan " +color6 Foreground yellow " +color7 Foreground magenta " +color8 Foreground purple " +color9 Foreground darkslategray " +copyOnResize Boolean True Copy raster when resized +crosshairCursorColor Foreground red Full-screen cursor color +defaultMarker String rectangle Default marker type +deiconifyWindow Boolean False Deiconify window when active +dialogBgColor Foreground yellow Status line background color +dialogFgColor Foreground black Status line foreground color +dialogFont1 XFontStruct nil2 Status line fonts +dialogFont2 XFontStruct 5x8 " +dialogFont3 XFontStruct 6x10 " +dialogFont4 XFontStruct 7x13 " +dialogFont5 XFontStruct 8x13 " +dialogFont6 XFontStruct 9x15 " +dialogFont7 XFontStruct 9x15 " +dialogFont8 XFontStruct 9x15 " +ginmodeBlinkInterval Int 0 Graphics cursor blink interval +ginmodeCursor String full_crosshair Graphics cursor type +ginmodeCursorBgColor Foreground black Graphics cursor background color +ginmodeCursorFgColor Foreground white Graphics cursor foreground color +height Dimension 480 Height of graphics window +idleCursor String Plus Idle cursor type +idleCursorBgColor Foreground white Idle cursor background color +idleCursorFgColor Foreground black Idle cursor foreground color +markerBoxKnotColor Foreground blue Vertex knot color +markerBoxKnotSize Int 0 Vertex knot size +markerBoxLineColor Foreground green Marker border color +markerCircleKnotColor Foreground blue Vertex knot color +markerCircleKnotSize Int 0 Vertex knot size +markerCircleLineColor Foreground green Marker border color +markerCursorBgColor Foreground black Cursor background when in marker +markerCursorFgColor Foreground yellow Cursor foreground when in marker +markerEllipseKnotColor Foreground blue Vertex knot color +markerEllipseKnotSize Int 0 Vertex knot size +markerEllipseLineColor Foreground green Marker border color +markerFill Boolean False Flood fill marker area with \fImarkerFillColor\fP +markerFillBgColor Foreground black Fill area background color +markerFillColor Foreground slategray Flood fill color +markerFillStyle Int FillSolid Fill area style +markerHighlightColor Foreground green Marker highlight color +markerHighlightWidth Int 2 Marker highlight line width +markerLineKnotColor Foreground blue Vertex knot color +markerLineKnotSize Int 5 Vertex knot size +markerLineLineColor Foreground green Line marker color +markerLineStyle Int LineSolid Line marker line style +markerLineWidth Int 1 Line marker width +markerPgonKnotColor Foreground blue Vertex knot color +markerPgonKnotSize Int 5 Vertex knot size +markerPgonLineColor Foreground green Marker border color +markerRectKnotColor Foreground blue Vertex knot color +markerRectKnotSize Int 0 Vertex knot size +markerRectLineColor Foreground green Marker border color +markerTextBgColor Foreground slategray Text marker background color +markerTextBorder Int 2 Text marker border width +markerTextColor Foreground yellow Text marker text color +markerTextFont XFontStruct 6x13 Text marker font +markerTextLineColor Foreground green Text marker line color +markerTextString String NULL Text string +markerTranslations String default Marker event-to-actions translations +maxColors Int 216 Max colors in custom colormap +maxMappings Int 32 Max image mappings +maxRasters Int 512 Max image rasters +nearEdge Int 1 T{ +Distance, in pixels, between pointer and marker edge required +for translation actions for be in effect. +T} +nearVertex Int 4 T{ +Distance, in pixels between pointer and marker vertex (i.e. \fIknot\fP) +required for translation actions for be in effect. +T} +raiseWindow Boolean False Raise window when active +translations String default Event-to-actions translations +useTimers Boolean True Ok to use timers +warpCursor Boolean False Enable warp cursor when active +width Dimension 640 Height of graphics window +xorFill Boolean False Fill with GXxor +xorFillBgColor Int 255 Xor-fill background color +xorFillColor Int 2 Xor-fill color +.TE + +.SH "GTERM WIDGET TRANSLATIONS AND ACTIONS" + +.LP +The default translations for a Gterm window are: +.TS +center; +r l. +<Btn1Down>: m_create() +<Btn2Down>: crosshair(on) +<Btn2Motion>: crosshair(on) +<Btn2Up>: crosshair(off) +<EnterWindow>: enter-window() +<LeaveWindow>: leave-window() +<KeyPress>: graphics-input() +<Motion>: track-cursor() +.TE +.LP +The available action procedures for a Gterm window are: +.RS +.TP 20 +\fIignore()\fP +Ignore an event. +.TP 20 +\fIgraphics-input()\fP +Handle a graphics input request. +.TP 20 +\fIcrosshair(on|off)\fP +Display a crosshair cursor. +.TP 20 +\fItrack-cursor()\fP +Track crosshair cursor position. +.TP 20 +\fIenter-window()\fP +Handle an EnterWindow event. +.TP 20 +\fIleave-window()\fP +Handle an LeaveWindow event. +.TP 20 +\fIreset()\fP +Do a soft reset of the Gterm widget. +.TP 20 +\fIm_create()\fP +Create a new marker. Valid types include +.TS +center; +l l l l. +\fItext line polyline rectangle +box circle ellipse polygon\fP +.TE +The default is \fIrectangle\fP, if no type is given the default type +specified by the \fImarkerType\fP resource will be used. +.RE + +.SH "GTERM MARKER TRANSLATIONS AND ACTIONS" + +.LP +The default translations for a marker are: + +.TS +center; +r l. +!Shift <Btn1Motion>: m_rotateResize() +<Btn1Motion>: m_moveResize() +!Shift <Btn1Down>: m_raise() m_markpos() +<Btn1Down>: m_raise() m_markposAdd() +<Btn1Up>: m_redraw() m_destroyNull() +<Btn2Down>: m_lower() +<Key>BackSpace: m_deleteDestroy() +<Key>Delete: m_deleteDestroy() +<KeyPress>: m_input() +<Motion>: track-cursor() +.TE + +Translations affect only the currently active marker, the cursor must be +within \fInearEdge\fP pixels of a marker edge, or \fInearVertex\fP pixels +of a marker vertex to take effect. + +The available action procedures for a marker are +.RS +.TP 18 +\fIm_create(type)\fP +Create a new marker. Valid types include +.TS +center; +l l l l. +\fItext line polyline rectangle +box circle ellipse polygon\fP +.TE +The default is \fIrectangle\fP, if no type is given the default type +specified by the \fImarkerType\fP resource will be used. +.TP 18 +\fIm_destroy()\fP +Destroy the active marker. +.TP 18 +\fIm_destroyNull()\fP +Destroy the active marker if it is null sized. +.TP 18 +\fIm_set(attribute, value, ....)\fP +Set a marker attribute. Valid attributes include + +.TS +center; +l l l l. +\fIactivated autoRedraw fill fillBgColor +fillColor fillPattern fillStyle font +height highlightColor imageText knotColor +knotSize lineColor lineStyle lineWidth +rotangle sensitive textBgColor textBorder +textColor translations type visible +width x y \fP +.TE +.TP 18 +\fIm_raise()\fP +Raise the active marker to the top of the display list. +.TP 18 +\fIm_lower()\fP +Lower the active marker to the bottom of the display list. +.TP 18 +\fIm_notify(event, event, ....)\fP +Notify any clients that have registered callbacks for the specified type +of events. Recognized events include +.TS +center; +l l l. +\fInotify \fImoveResize \fImodify +\fIredraw \fIdestroy \fIinput +\fIfocusIn \fIfocusOut \fIconstraint\fP +.TE +.TP 18 +\fIm_input()\fP +Notify any clients that have registered a input callback that a input event +has occurred. +.TP 18 +\fIm_markpos()\fP +Mark the current position of the marker, e.g., so that it can later be erased. +.TP 18 +\fIm_markposAdd()\fP +Execute either the markpos or add action, depending upon +the pointer location. If the pointer is over an active marker at a +location where the add action can be executed this is done, otherwise the +markpos action is executed. +.TP 18 +\fIm_redraw()\fP +Redraw the active marker. +.TP 18 +\fIm_addPt()\fP +Add a point (i.e. vertex knot). \fIPolyline\fP and \fIpolygon\fP markers only. +.TP 18 +\fIm_deletePt()\fP +Delete a point (i.e. vertex knot). +.TP 18 +\fIm_movePt()\fP +Move a point (i.e. vertex knot). \fIPolyline\fP and \fIpolygon\fP markers only. +.TP 18 +\fIm_deleteDestroy()\fP +Delete a point or destroy a marker, depending upon the pointer position. +.TP 18 +\fIm_move()\fP +Move a marker. +.TP 18 +\fIm_resize()\fP +Resize a marker. +.TP 18 +\fIm_moveResize()\fP +Move a point or marker, or resize a marker, depending upon the pointer +position. +.TP 18 +\fIm_rotate()\fP +Rotate a marker. +.TP 18 +\fIm_rotateResize()\fP +Rotate or resize a marker. A marker is rotated if near a vertex know, or +resized if near an edge. +.RE + +.SH "GTERM I/O ESCAPE SEQUENCES" +XGterm uses escape sequences to provide graphics emulation. +This protocol is an extension of the Tektronix 4012 graphics protocol. +The basic extensions are patterned after the Retrographics VT640 graphics +terminal, using GS (octal \\035, aka Ctrl-]) and CAN (octal \\030, aka +Ctrl-x) to switch between vt100 and graphics modes. +Additional extensions are defined to support advanced features such as +color, area fills, graphics erasure, setting the cursor location under +program control, interactive dialog via the "status line", and so on. + +While these escape sequences can be used directly, the best programmatic +interface is to use the OBM (\fIObject Manager\fP) library supplied with +the XGterm source as part of the X11IRAF package. Any Tektronix-compatible +graphics library will suffice for producing vector graphics, the added +escape sequences used by the Gterm widget are required to make use of +imaging, area fills, the status line, etc. + +All escape sequences begin with an \fBESC\fP character (octal \\033), followed +by up to three characters defining the action to be taken. All strings in +capital letters refer to the ASCII code (e.g. \fILF\fP is the ASCII linefeed +code), a three digit number preceeded by a '\' refers to an octal code (e.g. +"\012" is octal 12) , all others are characters in the escape code (e.g. +"/bc" are the three characters '/', 'b', and 'c'). + +.SS "ESCAPE SEQUENCES" + +.RS +.TP 15 +\fBUS\fP +.sp -0.5 +.TP 15 +\fBCR\fP +Switch to alpha mode. Characters are drawn in the graphics window at the +"current" position (normally set beforehand with a GS/US vector move), +using the alpha mode font. Receipt of any control code causes alpha mode to be +exited. + +.TP 15 +\fBGS\fP +Switch to vector polyline mode. +.sp -0.5 +.TP 15 +\fBFS\fP +Switch to vector polypoint mode. +.sp -0.5 +.TP 15 +\fBRS\fP +Switch to vector mode, vertices are joined as a polygon. + +With all three codes, vertices and points are accumulated in a buffer and +displayed when the buffer fills or when vector mode is terminated by receipt +of any control code. A workstation open will be done if it hasn't already +been opened, no-op sequences GS-CAN are filtered out, since they would only +cause a pointless switch to the graphics frame and back without drawing. +The open workstation sequence is GS,US, or by the \fIxterm\fP graphics start +escape sequence "[?38h". + +.TP 15 +\fBEM\fP +Enter message mode. In message mode input text is accumulated in a buffer +and eventually passed to the object manager, which delivers the message to +the referenced object. Messages are used to download the user interface to +be executed by the object manager. During execution, messages are used +to set the values of user interface parameters to allow the UI to track +the state of the client application. + +.TP 15 +\fBCAN\fP +Close workstation and enter command mode. +.TP 15 +\fBBEL\fP +Ring the screen bell. + +.TP 15 +\fBENQ\fP +Return terminal status. Returned values include the terminal mode, and alpha +cursor x and y position. +.TP 15 +\fBSUB\fP +Initiate a cursor read, values are returned in window coordinates. +.TP 15 +\fB/SUB\fP +Return window cursor position in raster coordinates. +.TP 15 +\fBFF\fP +Clear the screen. +.TP 15 +\fB/f\fP +Set current cursor position. +.TP 15 +\fB0\fP +Set character size 0. (Currently ignored). +.sp -0.5 +.TP 15 +\fB1\fP +Set character size 1. (Currently ignored). +.sp -0.5 +.TP 15 +\fB2\fP +Set character size 2. (Currently ignored). +.sp -0.5 +.TP 15 +\fB3\fP +Set character size 3. (Currently ignored). +.TP 15 +\fB/0d\fP +Set color index. +.sp -0.5 +.TP 15 +\fB/1d\fP +Clear graphics screen. +.sp -0.5 +.TP 15 +\fB/2d\fP +Invert graphics screen +.TP 15 +\fB`\fP +Select line style 0. (Solid) +.sp -0.5 +.TP 15 +\fBa\fP +Select line style 1. (Dashed) +.sp -0.5 +.TP 15 +\fBb\fP +Select line style 2. (Dotted) +.sp -0.5 +.TP 15 +\fBc\fP +Select line style 3. (DashDot) +.sp -0.5 +.TP 15 +\fBd\fP +Select line style 4. (Dash3Dot) +.TP 15 +\fB/0w\fP +Select line width 0. +.sp -0.5 +.TP 15 +\fB/1w\fP +Select line width 1. +.sp -0.5 +.TP 15 +\fB/2w\fP +Select line width 2. +.sp -0.5 +.TP 15 +\fB/nw\fP +Select line width 3. +.TP 15 +\fB/0c\fP +Select line color 0. +.sp -0.5 +.TP 15 +\fB/1c\fP +Select line color 1. +.sp -0.5 +.TP 15 +\fB/2c\fP +Select line color 2. +.sp -0.5 +.TP 15 +\fB/3c\fP +Select line color 3. +.sp -0.5 +.TP 15 +\fB/4c\fP +Select line color 4. +.sp -0.5 +.TP 15 +\fB/5c\fP +Select line color 5. +.sp -0.5 +.TP 15 +\fB/6c\fP +Select line color 6. +.sp -0.5 +.TP 15 +\fB/7c\fP +Select line color 7. +.sp -0.5 +.TP 15 +\fB/8c\fP +Select line color 8. +.sp -0.5 +.TP 15 +\fB/9c\fP +Select line color 9. +.RE + +.SS "IMAGING ESCAPE SEQUENCES" + +These are encoded as follows: + + \fBESC\fP <code> [ \fIP ; P\fP ; ... ] <\fIdata\fP> + +where \fIcode\fR is a character sequence and \fIP\fP is an ASCII encoded +parameter described below. +.RS +.TP 15 +\fB/nc\fP +Select line color. Parameter is the color number in the range 0-9. +.TP 15 +\fBsre\fP +\fIReset\fP. Parameters are "reset-str". +.TP 15 +\fBssz\fP +\fIResize\fP. Parameters are "resize-str". +.TP 15 +\fBrir\fP +\fIInitialize raster\fP. +.TP 15 +\fBrcr\fP +\fICreate a raster\fP. Parameters are raster number, type, width, height, and +depth. Type is 1 for a normal (client) raster, 2 for cached in server memory, +or 0 if you don't care. Depth may be 1, 8, 16, or 32. +.TP 15 +\fBrde\fP +\fIDestroy a raster\fP. Parameter is raster number. +.TP 15 +\fBrqr\fP +\fIQuery a raster\fP. Parameter is raster number. +Output parameters are status, type, width, height, and depth encoded in the +string ""\\033[5;%d;%d;%d;%d;%d]". +.TP 15 +\fBrsr\fP +\fISelect a raster\fP. Parameter is raster number. +.TP 15 +\fBrwr\fP +\fIWrite pixels to a rectangular region of a raster\fP. Parameters are raster +number, encoding type (not used), x1, y1, nx, ny, and depth followed by +(nx*ny) data pixels. +.TP 15 +\fBrrd\fP +\fIRead from a rectangular region of a raster\fP. Parameters are raster +number, encoding type (not used), x1, y1, nx, ny, and depth followed by (nx*ny) +data pixels. +.TP 15 +\fBrrp\fP +\fIRefresh raster pixels\fP. Parameters are raster number, coordinate type (0 +for pixel, 1 for NDC), x1, y1, nx, ny. +.TP 15 +\fBrsp\fP +\fISet all the raster pixels in a region to a single color\fP. Parameters are +raster number, coordinate type (0 for pixel, 1 for NDC), x1, y1, nx, ny, +color, and raster operand. If nx=ny=0 the entire raster will be written. +Raster operands include transient (octal 020), refresh_all (octal 040), +or refresh_none (octal 100). +.TP 15 +\fBrco\fP +\fICopy a region of the source raster to a region of the +destination raster\fP. Parameters are raster operand, source raster number, +source type, source x coord, source y coord, source width, source height, +destination raster number, destination type, destination x coord, destination +y coord, destination width, destination height, If the input and output +regions are not the same size the subimage is automatically scaled to fit +the destination region. If the destination extent DNX or DNY is negative, +the image is flipped in that axis. The type of spatial scaling performed is +determined by the scale factors (zoom, dezoom, or no scaling). The rasterop +argument is used to exercise fine control over how the mapping is performed, +e.g. to force a refresh, implement a transient mapping, or in the case of a +dezoom (many-to-one) mapping, select the antialiasing technique to be used. +.TP 15 +\fBrwc\fP +\fIWrite a colormap\fP. Parameters are colormap number, first color and the +number of colors followed by NC colors triples in the data. +.TP 15 +\fBrrc\fP +\fIReturn the color assignments for a region of the named colormap\fP. +Parameters are colormap number, first color and the number of colors followed +by NC colors triples in the data. +.TP 15 +\fBrlc\fP +\fILoad a colormap into the display\fP, optionally scaling the colormap via a +linear transformation in the process. Parameters are the colormap number, the +offset value, and the cursor x and Y coordinates in NDC units. The colormap is +unaffected if offset=0.5, scale=1.0. A negative scale inverts the image. +If map=0 the linear transformation is applied directly to the display colormap. +.TP 15 +\fBrfc\fP +\fIFree a colormap\fP. Parameter is the colormap number. +.TP 15 +\fBrwo\fP +\fIWrite the IOmap\fP. Parameters are the first color and the number of colors, +followed by NC color triples in the data. An iomap is an optional lookup +table used to isolate the client application from the color model used within +the Gterm widget. To simplify color allocation the Gterm widget defines a +logical color space where color 0 is the background, 1 the foreground, 2-N are +statically allocated standard colors, and colors N+1 and above are dynamically +allocated by the graphics application. Less-demanding applications use +only the statically allocated, shared colors. The widget internally maps +these logical colors to whatever the window system requires, but providing +a well-defined logical color space isolates the client from the details of +color allocation in the underlying window system. + +An iomap can be used to define a mapping between the color model of the +client application and the Gterm color model (when we say color model here +we mean color allocation schemes for 8 bit pseudocolor). By default the +iomap is one-to-one. The use of an iomap frees the client from having to +worry about color index translations, and allows color tables to be +combined in the widget for greater efficiency when color tables are serially +applied. The iomap applies to all color indices or pixel values passed +in i/o operations between the client and the Gterm widget. +.TP 15 +\fBrro\fP +\fIRead the IOmap\fP. Return values are the first color and the number of +colors, followed by NC color triples in the data. +.TP 15 +\fBrim\fP +\fIDelete all mappings\fP and initialize the mapping subsystem. +.TP 15 +\fBrsm\fP +\fIDefine a new mapping function\fP, or modify an old one. +If a new mapping is defined it is merely enabled, and no refreshing +of the screen takes place until either some mapped data is written +to or the mapping is explicitly refreshed. If an existing mapping is +modified the old and new mappings are examined and only those portions +of the destination rect for which the mapping changed are updated. +This permits minor changes to a mapping (e.g. moving an edge) without +having to redraw the entire region. Regions of the destination drawable +which were previously covered by the mapping but which were exposed by +modifying the mapping are redrawn. +.TP 15 +\fBrgm\fP +\fIReturn the external parameters of a mapping\fP. Parameter is the mapping +number, values returned (in the string +"\\033[6;%d;%d %d;%d;%d;%d;%d;%d %d;%d;%d;%d;%d;%d]") are the mapping +number, rasterop, source mapping, type, x, y, width, height, and destination +mapping, type, x, y, width and height. +.TP 15 +\fBrem\fP +\fIEnable a mapping\fP. Parameters are the mapping number and an integer +flag indicating whether to refresh the mapping. +.TP 15 +\fBrdm\fP +\fIDisable a mapping\fP. Disabling a mapping does not +affect the mapping definition, hence a disabled mapping may later be +reenabled. Parameters are the mapping number and an integer flag indicating +whether to erase the mapping. +.TP 15 +\fBrrm\fP +\fIRefresh a mapping\fP. Parameter is the mapping number. +.TP 15 +\fBrfm\fP +\fIFree a mapping\fP. Parameter is the mapping number. +.RE + +.SH "MORE ON IMAGING" +The imaging model of the Gterm widget defines the following key object or +data types: \fIrasters\fP, \fImappings\fP, and \fIcolors\fP. +.TP 10 +.B "raster" +A raster is a MxN array of pixels. At present pixels are 8 bits deep but +hooks are built into the widget to expand this in the future. Pixel +values are indices into the Gterm virtual colormap, with values starting at +zero. A raster may be any size. A raster is merely a two-dimensional array +in the graphics server; it is not displayed unless mapped. An exception is +raster zero, which is the graphics window. Rasters are referred to by number, +starting with zero. Initially only raster zero exists; new rasters are created +with the create raster escape code \fBrcr\fP. Space for rasters may be +allocated either in the graphics server, or in the X server. This has +implications on performance but is otherwise transparent to the client. +By default rasters are allocated in the graphics server, i.e., in the X client. +.TP 10 +.B "mapping" +A mapping defines a projection of a rectangle of the source raster onto a +rectangle of the destination raster. Mappings may be either enabled (active) +or disabled. When a mapping is enabled, any change to a pixel in the source +rect will cause the corresponding pixels in the destination rect to be +updated. Mappings are referred to by number starting with one. Initially +no mappings are defined. If the size of the input and output rect is not +the same the input rect will be scaled by pixel replication or subsampling +to fill the output rect. If the argument DW (destination width) or DH +(destination height) of the destination rect is negative, the image will be +flipped around the corresponding axis when copied to the destination; the +region of the destination drawn into is the same in either case. Multiple +mappings may reference the same source or destination raster. Mappings are +refreshed in order by the mapping number. Modifying a mapping causes the +changed regions of the destination rect to be refreshed. +.TP 10 +.B "color" +The \fIGterm\fP widget provides a fixed number of preassigned colors +corresponding to pixel values 0 through 9. Zero is the background color, +one is the foreground color, and 2-9 (8 colors) are arbitrary colors defined +by Gterm widget resources. These static colors are normally used to draw +the background, frame, axes, titles, etc. of a plot, or to draw color +graphics within the drawing area. The advantage of static colors is that +they are shared with other X clients, and the values of these colors may be +assigned by the user to personalize the way plots look. + +The \fIGterm\fP widget also allows any number (up to about 200 or so) additional +colors to be defined at runtime by the client application. These color +values start at pixel value 10 and go up to the maximum pixel value assigned +by the client. The client application allocates colors with the +write colormap escape code \fBrwc\fP. Attempts to overwrite the values of +the static colors are ignored. The values of already allocated colors may +be changed dynamically at runtime using write colormap code to write the +desired range of color values. + +Applications should not assume that there are 10 static colors and 200 or +so allocatable colors. The IRAF graphcap entry for the logical device in use, +and resources set for the widget, +defines these parameters for the device. Alternatively, the read colormap +code may be used to dynamically determine how many colors the server has +preallocated when the application starts up. + +An image may use either static and dynamic pixel values or both types of +values, but in most cases imaging applications involve smoothly shaded +surfaces hence will require dynamically assigned private colors. + +If for some reason the client application cannot use the \fIGterm\fP widget +color model, the IOMAP feature can be used to make the widget appear to have +some externally defined (i.e., client defined) color model. +.LP +The maximum number of rasters and maximum number of mappings is defined by +the Gterm widget resources \fImaxRaster\fP and \fImaxMappings\fP (or in the +GUI file) when the graphics application starts up. The maximum values should +be much larger than most applications require. Applications should allocate +raster or mapping numbers sequentially starting at 1 (more or less) to avoid +running out of raster or mapping descriptors. + +The {read|write}pixels escape codes operate directly on +raster pixels. The mapping escape codes support two alternative coordinate +systems, raster pixels and NDC (normalized device coordinates), as indicated +by the ST or DT argument (source or destination coordinate type). Note +that the origin of the pixel coordinate system is the upper left corner of +the display window (consistent with most graphics systems), whereas the origin +of the NDC coordinate system is the lower left corner (consistent with IRAF). + +Pixel coordinates allow precise control of imaging but require the +application to know the window size, and may result in complications e.g. if +the window is resized. NDC coordinates pretty much guarantee that a mapping +will involve sampling, hence are not the most efficient, but the graphics +will be drawn correctly no matter how the window is resized and for most +applications the performance difference is negligible. Most applications +should use NDC coordinates for raster 0 (the display window), and pixel +coordinates for rasters 1-N. + +Although the size of rasters 1 and higher are defined by the client +application, the size of raster zero, the actual gterm display window, is +subject to the constraints of the window system. The client can attempt to +reset the size of the gterm window using create raster escape with raster=0, +however the Gterm widget, UI containing the \fIGterm\fP widget, and the window +manager are all free to deny such a request. The query raster escape should be +called to determine the actual size of the window one will be drawing into. + +.SS AN EXAMPLE IMAGING APPLICATION + +.LP +An example of a simple imaging application might be one that downloads an +image and displays it in the gterm window, filling the window. This could +be done as follows (following a graphics open and other escape codes to +prepare the drawing surface). + +.TP 15 +\fIcreate raster\fP +Create raster 1 the size of the pixel array to be displayed. This need not +be the same as the size of the gterm display window. +.TP 15 +\fIset mapping\fP +Define a mapping between raster 1 and raster 0, the display window, using +NDC coordinates to define the region of the display window to be +filled. The mapping number is arbitrary but mappings should normally be +allocated starting with 1. The mapping is automatically enabled +when first defined. +.TP 15 +\fIwrite colormap\fP +(Optional). Define the pixel value to RGB color assignments for the image +pixels. +.TP 15 +\fIwrite pixels\fP +This escape is called one or more times to write pixels into raster 1. +At most 32K pixels can be written in each call. As each write is +made the affected region of the display window will be updated. +.LP +Alternatively, one could write the pixels and then define the mapping to +cause the entire image to be displayed at once. + +Note that the imaging escape can be combined with normal graphics to draw text +and graphics around or on top of an image region. The order in which drawing +operations occur is important, e.g., to draw graphics or text on top of an +image the image should be drawn first. + +.SH "MARKERS" +Markers are a general feature of the \fIGterm\fP widget and are used more +extensively in other programs (e.g. the prototype IRAF science GUI +applications), but they have no real use in \fIxgterm\fP when used as +simply a graphics terminal. All markers share some of the same characteristics, +so it is worthwhile learning basic marker manipulation keystrokes (as defined +using the default marker translations), especially how to delete an +accidentally created marker: +.RS +.TP 3 +\fBo\fP +\fIDelete\fP or \fIBackspace\fP in a marker deletes it. +.TP 3 +\fBo\fP +MB1 anywhere inside a marker may be used to drag the marker. +.TP 3 +\fBo\fP +MB1 near a marker corner or edge, depending on the type of marker, +resizes the marker. +.TP 3 +\fBo\fP +Shift-MB1 on the corner of most markers will rotate the marker. +.TP 3 +\fBo\fP +Markers stack, if you have several markers and you put one on top of +the other. The active marker is highlighted to tell you which of the +stacked markers is active. If the markers overlap, this will be marker +"on top" in the stacking order. +.TP 3 +\fBo\fP +MB2 in the body of a marker "lowers" the marker, i.e. moves it to the +bottom of the stacking order. +.RE + +.SH ENVIRONMENT +.I XGterm +sets the environment variables ``TERM'' and ``TERMCAP'' properly for the +size window you have created. +It also uses and sets the environment +variable ``DISPLAY'' to specify which bit map display terminal to use. +The environment variable ``WINDOWID'' is set to the X window id number +of the \fIxgterm\fP window. + +.SH "SEE ALSO" +xterm(1), resize(1), X(1), pty(4), tty(4) +.br +\fIXterm Control Sequences\fP (in the \fIxterm\fP source directory) + +.SH BUGS +Many of the same bugs affecting \fIxterm\fP also apply here. + +\fIXgterm\fP is not normally installed with setuid permissions. On some +Linux systems, for example, where the /dev/tty and /dev/pty devices have +root ownership and permission 600 this can cause problems. Workarounds +are to either install \fIXGterm\fP with setuid permissions or modify the +/dev/tty and /dev/pty devices to have permission 666. + +.SH COPYRIGHT +Copyright(c) 1986 Association of Universities for Research in Astronomy Inc. + |