From 6aa4747d3ec4054634c90dad4d1aa1d077e5176b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ond=C5=99ej=20Hru=C5=A1ka?= Date: Tue, 5 Sep 2017 17:52:13 +0200 Subject: [PATCH] Mouse tracking explained --- html_orig/pages/help.php | 129 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 123 insertions(+), 6 deletions(-) diff --git a/html_orig/pages/help.php b/html_orig/pages/help.php index cf42f87..16eff86 100644 --- a/html_orig/pages/help.php +++ b/html_orig/pages/help.php @@ -213,7 +213,7 @@
-

User Input

+

User Input: Keyboard, Mouse, Buttons

Keyboard

@@ -325,18 +325,135 @@

Action buttons

- The blue buttons under the screen send ASCII codes 1, 2, 3, 4, 5, which incidentally correspond to Ctrl+A,B,C,D,E. - This choice was made to make button press parsing as simple as possible. + The blue buttons under the screen send ASCII codes 1, 2, 3, 4, 5, which incidentally + correspond to Ctrl+A,B,C,D,E. This choice was made to make button press parsing as simple as possible.

Mouse

- ESPTerm implements standard mouse tracking schemes based on Xterm. Mouse tracking can be used to add - powerful user interactions such as on-screen buttons, draggable on-screen sliders or dials, menus etc. + ESPTerm implements standard mouse tracking schemes based on Xterm. Mouse tracking can be used to implement + powerful user interactions such as on-screen buttons, draggable sliders or dials, menus etc. ESPTerm's + mouse tracking was tested using vttest and should be compatible with all terminal applications + that request mouse tracking.

- TODO +

+ Mouse can be tracked in different ways; some are easier to parse, others more powerful. The coordinates + can also be encoded in different ways. All mouse tracking options are set using option commands: + CSI ? n h to enable, CSI ? n l to disable option n. +

+ +

Mouse Tracking Modes

+ +

+ All tracking modes produce three numbers which are then encoded and send to the application. + First is the event number (N), then the X and Y coordinates, 1-based. + Mouse wheel works as two buttons which generate only press events. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionNameDescription
9X10 mode + This is the most basic tracking mode, in which only button presses are reported. + N = button - 1: (0 left, 1 middle, 2 right, 3, 4 wheel). +
1000Normal mode + In Normal mode, both button presses and releases are reported. + The lower two bits of N indicate the button pressed: + 00b (0) left, 01b (1) middle, 10b (2) right, 11b (3) button release. + Wheel buttons are reported as 0 and 1 with added 64 (e.g. 64 and 65). + Normal mode also supports tracking of modifier keys, which are added to N as bit masks: + 4 Shift, 8 Meta/Alt, 16 Control/Cmd. Example: middle button with Shift = 1 + 4 = 101b (5). +
1002Button-Event tracking + This is similar to Normal mode (1000), but mouse motion with a button held is also reported. + A motion event is generated when the mouse cursor moves between screen character cells. + A motion event has the same N as a press event, but 32 is added. + For example, drag-drop event with the middle button will produce N = 1 (press), 33 (dragging) and 3 (release). +
1003Any-Event tracking + This mode is almost identical to Button Event tracking (1002), but motion events + are sent even when no mouse buttons are held. This could be used to draw on-screen mouse cursor, for example. + Motion events with no buttons will use N = 32 + 11b (35). +
1004Focus tracking + Focus tracking is a separate function from the other mouse tracking modes, therefore they can be enabled together. + Focus tracking reports when the terminal window (in Xterm) gets or loses focus, or in ESPTerm's case, when any + user is connected. This can be used to pause/resume a game or on-screen animations. + Focus tracking mode sends CSI I when the terminal receives, and CSI O when it loses focus. +
+ +

Mouse Report Encoding

+ +

+ The following schemes can be used with any of the tracking modes (except Focus tracking, which is not affected). +

+ + + + + + + + + + + + + + + + + + + + + + + +
OptionNameDescription
N/ANormal scheme + This is the default scheme used when no other option is selected. + A mouse report in this scheme has the format CSI M n x y, + where n, x and y are characters with ASCII value 32 + the respective number, e.g. + 0 becomes 32 (space), 1 becomes 33 (!). Example: \e[M !! - left button press at coordinates 1,1 when + using X10 mode. +
1005UTF-8 scheme + This scheme should encode each of the numbers as a UTF-8 code point, expanding the maximum possible value. + Since ESPTerm's screen size is limited and this has no practical benefit, this serves simply as an alias + to the normal scheme. +
1006SGR scheme + In SGR scheme, the response is a SGR sequence with the three numbers as ASCII values. In this case, + 32 is not added, like in the Normal and UTF-8 schemes. Also, button release is not reported as 11b, + but using the normal button code while changing the final SGR character: M for button press + and m for button release. Example: \e[2;80;24m - the right button was released + at row 80, column 24. +
1015URXVT scheme + This is similar to the SGR scheme, but the final character is always M and the numbers are + like in the Normal scheme, with 32 added. This scheme has no real advantage over the previous schemes and + was added solely for completeness. +