See espterm.github.io
espterm-demo-website/docs/Locator Input Model for ANS...

464 lines
25 KiB

7 years ago
<!doctype html>
<html>
<meta charset="UTF-8">
<title>Locator Input Model for ANSI Terminals (sixth revision)</title>
</head>
<style>
body {
background: white;
color: black;
width: 800px;
margin:0 auto;
font-family:monospace;
white-space: pre;
line-height: 1.35em;
font-size: 12pt;
}
</style>
<body>
<p><b>Locator Input Model for ANSI Terminals (sixth revision)</b>
<hr><p><i>File originally captured 3 Jan, 2011
at http://web.eecs.utk.edu/~shuford/terminal/dec_vt_mouse.html</i>
<p><i>Retrieved from archive and restored by Ondřej Hruška &lt;ondra@ondrovo.com&gt;, 2017</i>
<hr>
<p>This information has been circulated to other terminal vendors
and people outside of Digital, but I'm not sure whether it has
been formally published (the DECterm manual includes some of it).
<p>I hope you find this helpful.
<p>- - Peter Sichel
<p> C&amp;P VT Architecture
<p> Digital Equipment Corp
<p><tt> _ _ _ _ _ _ _ </tt>
<tt> | | | | | | | | </tt>
<tt> |d|i|g|i|t|a|l| INTEROFFICE MEMORANDUM</tt>
<tt> |_|_|_|_|_|_|_|</tt>
<p> TO: Locator Support on DATE: 23 Jun 1989
<p> Terminals Interest List FROM: Peter Sichel
<p> DEPT: Video Architecture
<p> DTN: 223-5162
<p> LOC: PKO3-1/10C
<p> NET: VIDEO::SICHEL<hr>
<p><a href="#Overview">Overview</a>
<p><a href="#LOCATOR_INPUT_MODEL">Locator Input Model</a>
<p><a href="#Enabling_Locator_Reporting">Enabling Locator Reporting</a>
<p><a href="#Locator_Position_Reporting">Locator Position Reporting</a>
<p><a href="#Selecting_Locator_Events">Selecting Locator Events</a>
<p><a href="#LOCATOR_SUPPORT_FOR_GRAPHICS">LOCATOR SUPPORT FOR GRAPHICS</a>
<p><a href="#Locator_Key_Definition">Locator Key Definition (DECLKD)</a>
<p><a href="#Locator_Key_Definition">DECLKD - DEC Locator Key Definition</a>
<p><a href="#LOCATOR_DEVICE_SUPPORT">LOCATOR DEVICE SUPPORT</a>
<p><a href="#Locator_Device_Status_Report_DSR_">Locator Device Status Report (DSR)</a>
<p><a href="#Locator_Controller_Mode">Locator Controller Mode</a>
<p><isindex>
<hr>
<p>SUBJECT: Locator Input Model for ANSI Terminals (sixth revision)
<p>This memo defines support for locator input devices on ANSI text
and graphics terminals. The goal is to make terminals able to
support the same class of applications popular on PCs and Workstations.
This is not meant to imply terminals must be compatible with
workstations, some limitations are unavoidable. The intent is
to provide a minimal set of locator functions which make sense
for terminals. Comments are welcome.
<p><b><a name="Overview">Overview</a></b>
<p>The terminal is supplied with a locator port which can be used
to connect an optional <i>mouse</i> or tablet. When locator reporting
is enabled, a seperate input cursor appears, and the terminal
tracks the locator locally with no host intervention. Individual
locator events such as locator button transitions or movement
may be programmed to send locator reports to the host.
<p>Each locator report includes the specific event which initiated
the report, the current state of the locator keys, and the coordinates
of the input cursor at the time of the event.
<p>The locator is treated as a manual input device similar to a keyboard.
Locater events are queued in the keyboard input silo along with
keystrokes.
<p><b><a name="LOCATOR_INPUT_MODEL">LOCATOR INPUT MODEL</a></b>
<p><i><a name="Enabling_Locator_Reporting"></a>Enabling Locator Reporting</i>
<p>Locator reporting can be selectively enabled from the host using
a DEC private control sequence. When disabled (the power up default),
the locator cursor does not appear, and the locator buttons are
inactive. When enabled, the locator cursor is visible, and the
terminal tracks the locator locally with no host intervention.
Individual locator events such as locator button transitions
or movement may be programmed to send locator reports to the host.
<p>DECELR - DEC Enable Locator Reports
<p>CSI Ps ; Pu ' z
<p> 2/7 7/10
<p>Ps may assume the following values
<p> 0 locator disabled (default)
<p> 1 locator reports enabled
<p> 2 one shot (allow one report, then disable)
<p>Pu specifies the coordinate units for locator reports
<p> 0 (or omitted) default to character cells
<p> 1 device physical pixels
<p> 2 character cells
<p>One shot mode is provided for applications that desire simple
graphics input similar to Tektronix GIN mode (no unsolicited reports).
If parameter value 2 is selected, the next trigger event that
occurs will generate a single locator report. No further locator
reports will occur (the locator will be disabled), until another
DECELR sequence is received.
<p>The coordinate units for locator position reports may be selected
to either of two coordinate systems used by terminal software
at the lowest level. Physical pixels is the &quot;least common
denominator&quot;, and is useful for computing sixel positions.
<p><i><a name="Locator_Position_Reporting">Locator Position Reporting</a></i>
<p>When a selected trigger event occurs such as a button press or
release, the terminal transmits a locator position report as follows.
<p> DECLRP - DEC Locator Report
<p> CSI Pe ; Pb ; Pr ; Pc ; Pp &amp; w
<p> 2/6 7/7
<p> Pe is the event code
<p> Pb is the button code
<p> Pr is the row coordinate
<p> Pc is the column coordinate
<p> Pp is the third coordinate (page number)
<p>Pe, the event code indicates what event caused this
report to be generated. The following event codes are defined:
<p> 0 - request, the terminal received an explicit request
<p> for a locator report, but the locator is unavailable
<p> 1 - request, the terminal received an explicit
<p> request for a locator report
<p> 2 - left button down
<p> 3 - left button up
<p> 4 - middle button down
<p> 5 - middle button up
<p> 6 - right button down
<p> 7 - right button up
<p> 8 - fourth button down
<p> 9 - fourth button up
<p> 10 - locator outside filter rectangle
<p>Pb is the button code, ASCII decimal 0-15 indicating which buttons
are down if any. The state of the four buttons on the locator
correspond to the low four bits of the decimal value, &quot;1&quot;
means button depressed
<p> 0 - no buttons down
<p> 1 - right
<p> 2 - middle
<p> 4 - left
<p> 8 - fourth
<p>Pr is the row coordinate of the locator position in the page,
encoded as an ASCII decimal value. If Pr is omitted, the locator
position is undefined (outside the terminal window for example).
<p>Pc is the column coordinate of the locator position in the page,
encoded as an ASCII decimal value. If Pc is omitted, the locator
position is undefined (outside the terminal window for example).
<p>Pp is the page coordinate of the locator position encoded as an
ASCII decimal value. The page coordinate may be omitted if the
locator is on page one (the default).
<p>Each locator report includes both the specific transition which
caused this event, and the current button state. This allows
software to determine what event just occured and which buttons
are down without keeping track of previous events or button state.
In a multiprocess shared locator environment, an application
may not know the previous button state. This dual reporting also
allows applications to recover from lost locator reports.
<p>Each locator event generates a single report. In the rare situation
where two events occur simultaneously (within a single sampling
period), the terminal will report this as two separate events.
The order of reporting shall be by increasing event code number
(left button first).
<p>Locator events are queued in the keyboard input silo just like
keystrokes. Each locator event occupies one position in the silo
(the keyboard silo currently must have at least 9 positions).
If the input silo becomes full, the locator and keyboard are
locked until there is again room in the silo. The sequential
order of keystroke and locator events is strictly maintained.
<p>It is the responsibility of the host to accept data fast enough
to avoid locking the locator unintentionally. The limited buffering
inside the terminal gives the host a little more time to process
locator events smoothly.
<p>When the keyboard is locked, the &quot;wait&quot; indicator on
the keyboard turns on. The keyboard is automatically locked any
time the keyboard input silo is full. The keyboard can be locked
explicitly using the keyboard action mode (KAM) control function.
<p>When the locator is locked, the terminal continues to track the
locator, but the input cursor changes shape to appear as a wristwatch
(or other shape indicating to wait). The wristwatch cursor indicates
that locator button transitions will be ignored, but allows the
user to continue positioning in anticipation of the locator being
unlocked. The locator is automatically locked any time the input
silo is full.
<p>Locator-ahead, analogous to keyboard type-ahead is supported by
having each report include the locator position at the time of
the event, and maintaining the sequential order of keystroke and
locator events.
<p>A final implication of using the keyboard silo to buffer text
locator events is that locator and keyboard input should be associated
with the same session at all times. The session to receive these
events is sometimes called the &quot;active session&quot; or &quot;input
focus&quot;. In a multi-session windowing environment, the input
cursor is allowed to roam freely over the entire screen in response
to locator movement. The input cursor is never occluded when
locator reporting is enabled in one or more sessions. Each session
enables locator reporting independently. The following cases
describe the locator interaction with session viewports and scroll
regions.
<p>1. The input cursor is within the active session's viewport.
Pressing a button on the locator sends a locator report when enabled.
<p>2. The input cursor is inside the active session's viewport,
but outside the range of defined coordinates for that session.
Pressing a button on the locator will generate a report with omitted
coordinates (position undefined). An example would be when the
input cursor is outside the active scrolling region, and the origin
mode has been set to relative. To use the locator to adjust scroll
margins, the origin mode must be absolute.
<p>3. The input cursor is not contained in any viewport. Pressing
a button on the locator will have no effect. To support &quot;pop
up&quot; menus anywhere on the screen, the entire screen must
be a viewport for at least one session.
<p>4. The input cursor is within a viewport of a session which is
not the active session. Pressing a button on the locator will
normally make the session containing the input cursor the active
session (possibly changing the occlusion order of viewports, and
the shape of the locator). This case is the responsibility of
the &quot;window manager&quot; which is free to define its own
user interface. Two recommendations are: (1) No locator report
should be sent to the previous active session, since the locator
is not in its viewport; and (2) If locator reporting is enabled
in the new session, a locator report should not be transmitted
to avoid application side affects when selecting another window.
<p>Requesting A Locator Position Report
<p>The host may explicitly request a locator position report any
time locator reporting is enabled (DECELR). Upon receiving such
a request, the terminal will immediately send a single locator
report (DECLRP) with event code 1 indicating the current locator
position.
<p>If the session receiving the request is the active session, but
the locator is not within the defined coordinate range for that
session, the terminal will respond with omitted coordinates (locator
position undefined).
<p>If the session receiving the request is not currently active (the
locator is being used in another session), the report will specify
event code 0 (locator unavailable). Locator state from the active
session should not be made available to inactive sessions.
<p>If the locator is disabled (DECELR), the terminal should still
respond with event code 0 (to avoid timing out the application).
<p> DECRQLP - DEC Request Locator Position
<p>CSI Ps ' |
<p> 2/7 7/12
<p>Ps:
<p> 0 (or omitted) default to 1
<p> 1 transmit a single DECLRP locator report all
others ignored
<p>Filter Rectangles
<p>Filter Rectangles add filtered movement events to the list of
locator transitions that can generate reports.
<p>DECEFR - DEC Enable Filter Rectangle
<p> CSI Pt ; Pl ; Pb ; Pr ' w
<p> 2/7 7/7
<p> Pt - Top boundary of filter rectangle
<p> Pl - Left boundary of filter rectangle
<p> Pb - Bottom boundary of filter rectangle
<p> Pr - Right boundary of filter rectangle
<p>The DECEFR control sequence defines the coordinates of a filter
rectangle, and activates it. Anytime the locator is detected
to be outside a filter rectangle, an outside rectangle event is
generated and the rectangle is disabled. Filter rectangles are
always treated as &quot;one-shot&quot; events. Defining a new
rectangle re-activates it.
<p>Applications can re-define the rectangle at any time even if its
already active. If a rectangle which does not contain the locator
is specified, the terminal will generate an outside rectangle
report immediately and deactivate it.
<p>Pt, Pl, Pb, and Pr are in coordinates units specified by the last
DECELR sequence. The filter rectangle includes the boundaries
(similar to other rectangular area operations). The origin is
coordinate pair 1:1 in the upper left corner. If any parameters
are omitted, they are defaulted to the current locator position.
Sending DECEFR with no parameters will cause the application to
be notified for any locator movement (&quot;unfiltered movement
event&quot;).
<p>DECELR always cancels any previous filter rectangle definition.
This gaurantees that when an application enables locator reports,
there will never be an outstanding filter rectangle.
<p>If a filter rectangle lies on the edge of the defined coordinate
space for the active session, and the locator crosses that edge,
the rectangle may be triggered to send a report with omitted coordinates
(locator position undefined).
<p>If the active session receives a filter rectangle with explicit
coordinates while the locator is outside the defined coordinate
space, the rectangle will be triggered to send a report with omitted
coordinates.
<p>If the active session receives a filter rectangle with omitted
coordinates (that is, use the current position) while the locator
is outside the defined coordinate space (position undefined),
the rectangle will be triggered the next time the locator is within
the defined coordinate space.
<p>If a session which is not the active session receives a filter
rectangle with explicit coordinates, it should trigger immediately
with position undefined. If a session which is not the active
session receives a rectangle with omitted coordinates, it should
trigger the next time the locator is within the defined coordinate
space for that session, which cannot happen until the session
becomes active.
<p><i><a name="Selecting_Locator_Events">Selecting Locator Events</a></i>
<p>The locator events which are allowed to generate unsolicited reports
may be individually selected using the Select Locator Events control.
The locator is capable of reporting both up and down transitions
for those situations where the exact sequence of button activiations
is significant. This control allows application software to select
which events it wants reported.
<p>DECSLE - Select Locator Events
<p> CSI P...P ' {
<p> 2/7 7/11
<p> P...P is one or more selective parameters which may
assume the following values:
<p> 0 respond only to explicit host requests
<p> (default, also cancels any pending filter rectangle)
<p> 1 report button down transitions
<p> 2 do not report button down transitions
<p> 3 report button up transitions
<p> 4 do not report button up transitions
<p><b><a name="LOCATOR_SUPPORT_FOR_GRAPHICS">LOCATOR SUPPORT FOR
GRAPHICS</a></b>
<p>The locator can be used in REGIS, and in Tektronix GIN mode during
Tektronix 401x emulation.
<p>REGIS One-shot Graphics Input Mode is provided for backward compatibility
with the VT240. When an application requests graphics input,
a cross hair cursor appears which may be positioned using either
the arrow keys (as on the VT240), or a locator device. Pressing
any non-arrow key on the keyboard which is not dead or a button
on the locator will cause the following actions:
<p>1. The ASCII code or codes for the non-arrow key that was pressed
is sent to the host. Each locator button can be programmed to
send a sequence of 0 to 6 characters. This allows the locator
to be programmed to work with existing applications (see DECLKD
below).
<p>2. The coordinates of the input cursor at the time that the non-arrow
key was depressed are sent to the host, expressed as an absolute
bracketed extent in user coordinates.
<p>3. The graphics input cursor disappears from the screen and the
terminal exits graphics input mode.
<p>While the terminal is in graphics input mode, no further data
from the application is processed until the locator input is complete
and a report is generated.
<p>The mouse and arrow keys may be intermixed freely in REGIS One-Shot
Graphics Input Mode. Since the tablet is an absolute positioning
device, use of the arrow keys in combination with the tablet would
cause inconsistent and confusing behavior. The arrow keys are
disabled for input cursor positioning when the tablet is in proximity
because the tablet establishes a unique screen position.
<p><i><a name="Locator_Key_Definition">Locator Key Definition</a>
(DECLKD)</i>
<p>The DECLKD device control string down line loads one or more definitions
for use by the Locator device during REGIS One-shot Graphics Input.
These definitions are called Locator Key Definitions (LKDs).
<p>DECLKD is intended for older applications that use ReGIS one-shot
input mode with keystroke commands like &quot;A&quot;, &quot;B&quot;,
&quot;C&quot;, etc. These commands can be re-bound to buttons
on the mouse by sending DECLKD (possibly before running the application).
<p>There are six bytes available to each of the locator keys (upto
four). A power-up restart or RIS will cause the LKDs to be set
to their default value. LKDs are not affected by DECSTR.
<p>Default Locator Key Definitions
<p> No button transition ESC [ 240 ~
<p> Ky1 down transition ESC [ 241 ~
<p> Ky2 down transition ESC [ 243 ~
<p> Ky3 down transition ESC [ 245 ~
<p> Ky4 down transition ESC [ 247 ~
<p>Where:
<p> Ky1 = B1 = Left = barrel button
<p> Ky2 = B2 = Middle = tip button
<p> Ky3 = B3 = Right
<p> Ky4 = B4 (tablet cursor only)
<p>Up Transitions are ignored by default.
<p><i>DECLKD - DEC Locator Key Definition</i>
<p> DCS Pc $ w Ky1 / Std1 / Stu1 ; ... ; Kyn / Stnd
/ Stnu ST
<p> 2/4 7/7
<p> Where:
<p>Pc - Clear parameter
<p>0 (or omitted) Clear all LKDs before loading new values. All button
definition strings are empty (not the default).
<p>1 Clear old definition only for keys that are redefined. Kyn /
Stnd / Stnu - Key selection code n, slash delimeter, and string
parameter n for down and up key transitions.
<p>Kyn is a single ASCII digit, and Std/Stu is a series of ASCII
hex pairs. If Std or Stu is omitted, the corresponding button
string will be empty. Key definition strings are delimited with
a semicolon (&quot;;&quot;).
<p>Graphics and ANSI Locator Input
<p>Support for graphics input in REGIS is extended by allowing ANSI
locator input to operate normally regardless of whether the host
output stream is being interpreted as ANSI or REGIS. If ANSI
locator reporting is enabled, keystrokes and locator position
reports may be generated without being solicited from the host.
Characters received from the host are executed instead of buffered,
so graphics output and graphics input may occur simultaneously.
<p>If one-shot graphics input mode is entered (REGIS report position
interactive) while ANSI locator reporting is enabled, the locator
cursor will change to a cross-hair. Pressing a non-arrow key
on the keyboard will send the character for that key followed
by the REGIS user coordinates as a bracketed extent. If a locator
button had been pressed instead, the characters for the locator
button (if any) would be sent followed by the REGIS position report,
and finally the ANSI locator report (DECLRP) if enabled. Upon
sending the REGIS position report, the terminal exits one-shot
input mode, and the input cursor returns to its previous state.
<p>The ANSI locator report should still be sent in the above situation
(if enabled) to keep the two modes independent. This allows filter
rectangles to continue operating, and also keeps the ANSI state
(last DECLRP seen) consistent with the last button transition.
<p>The order of reports is chosen to allow a subroutine to send
R(P(I)) and read the REGIS response that follows without regard
to whether ANSI locator reports are enabled.
<p>Since the ANSI locator report is in the form of a control sequence,
it should not inferfere with REGIS reports. No special procedure
is used to indicate REGIS data from the terminal. This is backward
compatible with the VT240 since ANSI locator reports can only
occur if ANSI locator reporting is enabled.
<p>The suspension of graphics output during REGIS one-shot graphics
input remains the same. This is necessary to support rubber-band
cursors. Rubber-band cursors use the REGIS output position as
one reference point, and the locator input position as the other.
Rubber-band cursors are specified as an option on the REGIS report
position interactive command.
<p><b><a name="LOCATOR_DEVICE_SUPPORT">LOCATOR DEVICE SUPPORT</a></b>
<p>Locator support is currently planned as an extension to the level
3 character cell architecture. The primary device attributes
response will report the locator extension as parameter value
15 (locator port), and 29 (text locator).
<p>Host software may request a Device Status Report (DSR) to determine
whether a locator is available. Upon receiving the appropriate
DSR request, the terminal will respond to indicate the locator
is ready if a locator device is plugged in, and has transmitted
a successful self test message.
<p><i><a name="Locator_Device_Status_Report_DSR_">Locator Device
Status Report (DSR)</a></i>
<p>Host request locator device status CSI ? 55 n
<p>No locator CSI ? 53 n
<p>Locator ready CSI ? 50 n
<p>Locator busy CSI ? 58 n
<p>The locator busy response can occur when an alternate session
has selected locator controller mode (see below).
<p><i><a name="Locator_Controller_Mode"></a>Locator Controller Mode</i>
<p>Locator Controller Mode allows the host to communicate directly
with the locator device without terminal intervention (similar
to printer controller mode). When locator controller mode is
set, all data received at the host port is transferred directly
to the locator port without interpretation by the display terminal.
<p>The only exceptions are the communications control characters
XON/XOFF (if enabled), and the control sequence to disabled locator
controller mode. All characters received at locator port are
transferred to the host port without interpretation. The host
assumes full responsibility for the locator device.
<p>Locator controller mode is desirable for two reasons:
<p>1. It allows the host to explicitly initialize or configure locator
devices. A foriegn locator device might not wake up in DEC format
for example.
<p>2. It allows the locator port to be used for other auxilliary
input devices. A bar code reader could be interfaced to the locator
port for example, allowing the terminal to support a bar code
reader without pre-empting the printer port.
<p>Turn off locator controller mode (MC) CSI 6 i
<p>Turn on locator controller mode (MC) CSI 7 i
<p><i>[End of memo]</i>
</body>
</html>