Locator Input Model for ANSI Terminals (sixth revision) +
File originally captured 3 Jan, 2011 +at http://web.eecs.utk.edu/~shuford/terminal/dec_vt_mouse.html +
Retrieved from archive and restored by Ondřej Hruška <ondra@ondrovo.com>, 2017 +
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). +
I hope you find this helpful. +
- - Peter Sichel +
C&P VT Architecture +
Digital Equipment Corp +
_ _ _ _ _ _ _ + | | | | | | | | + |d|i|g|i|t|a|l| INTEROFFICE MEMORANDUM + |_|_|_|_|_|_|_| +
TO: Locator Support on DATE: 23 Jun 1989 +
Terminals Interest List FROM: Peter Sichel +
DEPT: Video Architecture +
DTN: 223-5162 +
LOC: PKO3-1/10C +
NET: VIDEO::SICHEL
Overview +
LOCATOR SUPPORT FOR GRAPHICS +
Locator Key Definition (DECLKD) +
DECLKD - DEC Locator Key Definition +
Locator Device Status Report (DSR) +
SUBJECT: Locator Input Model for ANSI Terminals (sixth revision) +
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. +
Overview +
The terminal is supplied with a locator port which can be used +to connect an optional mouse 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. +
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. +
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. +
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. +
DECELR - DEC Enable Locator Reports +
CSI Ps ; Pu ' z +
2/7 7/10 +
Ps may assume the following values +
0 locator disabled (default) +
1 locator reports enabled +
2 one shot (allow one report, then disable) +
Pu specifies the coordinate units for locator reports +
0 (or omitted) default to character cells +
1 device physical pixels +
2 character cells +
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. +
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 "least common +denominator", and is useful for computing sixel positions. +
When a selected trigger event occurs such as a button press or +release, the terminal transmits a locator position report as follows. +
DECLRP - DEC Locator Report +
CSI Pe ; Pb ; Pr ; Pc ; Pp & w +
2/6 7/7 +
Pe is the event code +
Pb is the button code +
Pr is the row coordinate +
Pc is the column coordinate +
Pp is the third coordinate (page number) +
Pe, the event code indicates what event caused this +report to be generated. The following event codes are defined: +
0 - request, the terminal received an explicit request +
for a locator report, but the locator is unavailable +
1 - request, the terminal received an explicit +
request for a locator report +
2 - left button down +
3 - left button up +
4 - middle button down +
5 - middle button up +
6 - right button down +
7 - right button up +
8 - fourth button down +
9 - fourth button up +
10 - locator outside filter rectangle +
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, "1" +means button depressed +
0 - no buttons down +
1 - right +
2 - middle +
4 - left +
8 - fourth +
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). +
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). +
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). +
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. +
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). +
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. +
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. +
When the keyboard is locked, the "wait" 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. +
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. +
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. +
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 "active session" or "input +focus". 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. +
1. The input cursor is within the active session's viewport. +Pressing a button on the locator sends a locator report when enabled. +
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. +
3. The input cursor is not contained in any viewport. Pressing +a button on the locator will have no effect. To support "pop +up" menus anywhere on the screen, the entire screen must +be a viewport for at least one session. +
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 "window manager" 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. +
Requesting A Locator Position Report +
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. +
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). +
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. +
If the locator is disabled (DECELR), the terminal should still +respond with event code 0 (to avoid timing out the application). +
DECRQLP - DEC Request Locator Position +
CSI Ps ' | +
2/7 7/12 +
Ps: +
0 (or omitted) default to 1 +
1 transmit a single DECLRP locator report all +others ignored +
Filter Rectangles +
Filter Rectangles add filtered movement events to the list of +locator transitions that can generate reports. +
DECEFR - DEC Enable Filter Rectangle +
CSI Pt ; Pl ; Pb ; Pr ' w +
2/7 7/7 +
Pt - Top boundary of filter rectangle +
Pl - Left boundary of filter rectangle +
Pb - Bottom boundary of filter rectangle +
Pr - Right boundary of filter rectangle +
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 "one-shot" events. Defining a new +rectangle re-activates it. +
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. +
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 ("unfiltered movement +event"). +
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. +
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). +
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. +
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. +
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. +
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. +
DECSLE - Select Locator Events +
CSI P...P ' { +
2/7 7/11 +
P...P is one or more selective parameters which may +assume the following values: +
0 respond only to explicit host requests +
(default, also cancels any pending filter rectangle) +
1 report button down transitions +
2 do not report button down transitions +
3 report button up transitions +
4 do not report button up transitions +
LOCATOR SUPPORT FOR +GRAPHICS +
The locator can be used in REGIS, and in Tektronix GIN mode during +Tektronix 401x emulation. +
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: +
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). +
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. +
3. The graphics input cursor disappears from the screen and the +terminal exits graphics input mode. +
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. +
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. +
Locator Key Definition +(DECLKD) +
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). +
DECLKD is intended for older applications that use ReGIS one-shot +input mode with keystroke commands like "A", "B", +"C", etc. These commands can be re-bound to buttons +on the mouse by sending DECLKD (possibly before running the application). +
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. +
Default Locator Key Definitions +
No button transition ESC [ 240 ~ +
Ky1 down transition ESC [ 241 ~ +
Ky2 down transition ESC [ 243 ~ +
Ky3 down transition ESC [ 245 ~ +
Ky4 down transition ESC [ 247 ~ +
Where: +
Ky1 = B1 = Left = barrel button +
Ky2 = B2 = Middle = tip button +
Ky3 = B3 = Right +
Ky4 = B4 (tablet cursor only) +
Up Transitions are ignored by default. +
DECLKD - DEC Locator Key Definition +
DCS Pc $ w Ky1 / Std1 / Stu1 ; ... ; Kyn / Stnd +/ Stnu ST +
2/4 7/7 +
Where: +
Pc - Clear parameter +
0 (or omitted) Clear all LKDs before loading new values. All button +definition strings are empty (not the default). +
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. +
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 (";"). +
Graphics and ANSI Locator Input +
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. +
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. +
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. +
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. +
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. +
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. +
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). +
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. +
Locator Device +Status Report (DSR) +
Host request locator device status CSI ? 55 n +
No locator CSI ? 53 n +
Locator ready CSI ? 50 n +
Locator busy CSI ? 58 n +
The locator busy response can occur when an alternate session +has selected locator controller mode (see below). +
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. +
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. +
Locator controller mode is desirable for two reasons: +
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. +
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. +
Turn off locator controller mode (MC) CSI 6 i +
Turn on locator controller mode (MC) CSI 7 i +
[End of memo] + + +