- 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.
- 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.
+ 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.
+
+ 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. +
+ +| Option | Name | Description |
|---|---|---|
| 9 | +X10 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). + | +
| 1000 | +Normal 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). + | +
| 1002 | +Button-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). + | +
| 1003 | +Any-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). + | +
| 1004 | +Focus 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.
+ |
+
+ The following schemes can be used with any of the tracking modes (except Focus tracking, which is not affected). +
+ +| Option | Name | Description |
|---|---|---|
| N/A | +Normal 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.
+ |
+
| 1005 | +UTF-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. + | +
| 1006 | +SGR 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.
+ |
+
| 1015 | +URXVT 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.
+ |
+