Anzio's Protocols for Sending Mouse Actions to the Host

I. Introduction

When you run Anzio (AnzioWin or Anzio Lite), you are communicating with a character-based application on a server (or host). Even though this is not a graphical environment, it is still possible, in some circumstances, to send mouse clicks to the host. This requires a protocol that is agreed upon between Anzio and the host.

There are several de facto standards for doing this, and Anzio implements these standards.

Some host-based programs and programming environments already support mouse actions, but they must be enabled through configuration options. Or, a programmer may wish to implement these actions on their own.

The availability of mouse-to-host protocols is dependent on the terminal type; that is, what kind of terminal Anzio is emulating. The protocols described below are available only in Anzio's ANSI-style emulations, which are VT-xxx, SCOANSI, Linux, AT386, and Anzio.

II. Concepts

A. PC side

Nothing has to be configured in Anzio to support these protocols. The program running on the host sends an initiation sequence that turns on a particular protocol, and may configure it for which mouse actions should be reported to the host. For instance, a mouse push might be reported, or
both a push and a release. Modifiers may be reported, such as if the Shift key is down.

When the user does a particular mouse action which the host has requested, Anzio sends a character sequence to the server. This sequence varies by protocol, but always starts with an Escape (hex 1B). The sequence will also contain the mouse position, in row and column units.

When Anzio is NOT sending actions to the host, it can be configured to do certain actions solely on the PC side. These are configured in Edit:Advanced Options:Mouse. When actions ARE being sent to the host, in some cases the PC-side actions are done also.

B. Host side

A program running on the host will generally rely on some configuration switch to indicate whether it should attempt requesting mouse actions from the PC. This configuration may be in the form of environment variables, and/or it may depend on certain configuration files on the host.

When the host program is listening for mouse actions, it is generally listening also for "special keys", such as <F1> or <up-arrow>. In fact, the logic for these is quite similar. If the host receives an escape character, it goes into logic that looks for additional characters, or times out in the case where the user has actually pressed the Escape key. The logic that identifies an <F1> sequence can very similarly recognize the first part of the mouse action sequence. Of course this logic must
then handle the variable parts of the mouse action sequence (the row and column, for instance).

For this to be effective in the host program, all input (keystroke) processing has to be done in the same place.

In at least one host language environment, AcuCobol, the runtime provides the recognition of special keys and also recognizes mouse sequences. These are converted to events that can be intercepted by the application programmer's code.

In other environments, if the runtime has keystroke logic but does NOT recognize mouse actions, the application programmer may need to bypass the built-in key recognition logic, by requesting keystrokes at some kind of lower level.

III. Existing Mouse Standards

For many years Anzio has supported mouse protocols that originated in Xterm, which is the program for "X", the graphical environment on Unix/Linux, which is used to run character-based programs in that graphical environment. One protocol, which we refer to as the "xterm-old" protocol, is documented in Xterm man (manual) pages. A different protocol, which we refer to as "xterm-new", was apparently never documented, but was supported by the Xterm provided with some
versions of UnixWare.

A separate protocol, which we refer to as the "vt420" protocol, is supported in certain VMS environments and on some other VT terminal emulators. It is sometimes referred to as the "locator" protocol. Anzio supports this starting in version 15.0h.

IV. Anzio's Implementation Protocols

Following are details on the mouse protocols that Anzio supports. This applies to Anzio Lite and AnzioWin, starting in 15.0h.

Note that none of these protocols, at least as Anzio implements them, sends mouse movement to the host. This precludes any sort of dragging operation on the host. However, if the host detects that a button-release happens in a different place on the screen than a button-press, it might conclude that a drag has occurred.

In the following, "ESC" represents the escape character (hex-1B). An item in the form "<x>" means a variable described as x; the less-than and greater-than are NOT part of the protocol.

A. Xterm-old Protocol

The host issues an initiation sequence

ESC [ ? 1000 h

to turn mouse actions on, and

ESC [ ? 1000 l

to turn them off (final character is an ell).

Anzio responds to mouse actions with

ESC [ M <button> <x> <y>

The <button> byte has these bits, represented as hex:

00 = button 1 pressed
01 = button 2 pressed
02 = button 3 pressed
03 = released
04 = shift is down
08 = meta (alt) is down
10 = Control is down

The <x> and <y> are one byte each. Value is "!" (hex 21) for the leftmost or topmost cell, and increase from there.

B. Xterm-new Protocol

The host issues an initiation sequence

ESC [ <options> Y

to turn on or off. The <options> is one or more ASCII digits, forming a decimal number. Use "0" to turn off. To turn on certain actions, the decimal number is converted to hex, and its value has these bits (in hex):

01 = button 1 released
02 = button 1 pushed
20 = button 2 released
40 = button 2 pushed
400 = button 3 released
800 = button 3 pushed

Also, the host can request the mouse position at any time with

ESC [ 492 Z

Anzio reports the mouse position as

ESC [ <hex-1F> <button> <action> <x> <y>

The <button> is an ASCII "1", "2", or "3" indicating which button, or "0" if position was requested.

The <action> is an ASCII "P" for push or "R" for release.

The <x> and <y> are one byte each, where space (hex 20) represents the leftmost or topmost location.

C. VT420 Locator Protocol

The host sends a sequence:

ESC [ <n> ; <m> ' Z

The <n> is a decimal number in ASCII. Values are:

0 = turn off
1 = not one-shot mode
2 = one-shot mode (not supported)

The <m> is a decimal number in ASCII. Values are:

1 = location is by pixel (not supported)
other = location by cell

The host indicates which actions it wants by sending

ESC [ <n1> ; <n2> ... ' {

Each <n1> etc. is a decimal number in ASCII. Values are:

0 = turn off mouse up and mouse down actions
1 = turn on mouse down action
2 = turn off mouse down action
3 = turn on mouse up action
4 = turn off mouse up action

On a mouse action, Anzio will send:

ESC [ <action> ; <state> ; <y> ; <x> ; <page> & w

All parameters are decimal represented as ASCII.

The <action> is

2 = left button down
3 = left button up
4 = middle button down
5 = middle button up
6 = right button down
7 = right button up

The <state> is a collection of bits. Values are:

1 = right button is down
2 = middle button is down
4 = left button is down

The <y> and <x> are based on 1.

The <page> is always reported as "1".

V. Custom Mouse Actions

It is also possible to create your own mouse actions. You can configure Anzio to run a particular macro on a particular mouse button click or double-click. When Anzio detects the mouse action, it will save in certain variables some conditions. These variables can then be expanded (dereferenced) inside the macro. Variables are:

ANZ_MOUSE_X

Contains the column number at which the mouse was clicked.

ANZ_MOUSE_Y

Contains the row number at which the mouse was clicked.

ANZ_MOUSE_WORD

Contains the word on the screen where the mouse was clicked.

For example, if you define the "D" macro as:

SEND/N "The mouse was dbl-clicked at row $~{ANZ_MOUSE_Y}"

then configure the left double-click to execute macro "D", then on a double click the host will receive, for instance The mouse was dbl-clicked at row 27

VI. Readily Available Mouse Support

Following are instances we know of where mouse support is built into host programs:

a) Pine and Pico

The Pine email program, from the University of Washington, and its editor, Pico, have support for mouse positioning from Xterm. They will activate this if the DISPLAY environment variable is set to anything. So for example, do the following before running Pine:

DISPLAY=dummy;export DISPLAY

b) AcuCobol (character-based)

The runtime for this language can be configured to allow mouse access. However, the information we have on this is quite dated. If you are interested in pursuing this, please contact Rasmussen Software.