Locator Input Model for ANSI Terminals (sixth revision)
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
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.
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
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]