Skip to content
This repository has been archived by the owner on Sep 4, 2022. It is now read-only.

Mouse Tracking

Jump to bottom
Gustav Dersjö edited this page May 13, 2021 · 13 revisions

Mouse Tracking

Most linux terminals seem to have implemented support for mouse tracking, however most terminals intended for being used with BBS'es either don't, or they deviate from the standards set by Xterm. This page is intended to describe both the established standards, as well as most of the non-standard implementations out there.

Mouse tracking formats

Xterm

Xterm's mouse format is the most common standard. It supports a wide variety of mouse tracking modes, featuring motion tracking and selection features.

  • To enable mouse tracking: $CSI ? <mode (%d...)> h
  • To disable mouse tracking: $CSI ? <mode (%d...)> l

Mouse tracking modes

tbd.

NetRunner

NetRunner (a terminal for BBSing) deviates from the standard mouse protocols proposed by the xterm specifications.

  • Initiated by $CSI ? 1000 h.
  • Somewhat based on the Xterm spec, but not 100% compatible
    • Values are offset by 40 instead of 32.
    • The sequences are formatted as $CSI M 0 <x (%s)> <y (%s)>, does not follow Xterm specifications.
    • Only supports mode 1000, meaning there is no support for movement tracking.
    • Deviates from xterm standard by only sending the starting click, meaning there is no support for mouse drag.

SyncTERM

SyncTERM (a terminal for BBSing) deviates from the standard mouse protocols proposed by the xterm specifications.

I haven't managed to get SyncTERM's mouse tracking to work, but supposedly the following is true about it (take this with a grain of salt)...

  • Initiated by $CSI = 255 h $CSI ? 1000 h.
    • $CSI = 255 h enables doorway mode, which supposedly is needed for it to work.
  • Somewhat based on the Xterm spec, but not 100% compatible
    • The sequences are formatted the same as Xterm
    • Only supports mode 1000, meaning there is no support for movement tracking.
    • Deviates from xterm standard by only sending the starting click, meaning there is no support for mouse drag.

The modifier byte

The modifier byte tells us more information about the button press.

Mouse mod bits
             1
            2|
           4||
          8|||
        16||||
       32|||||
      64||||||
    128|||||||
      ||||||||
      vvvvvvvv
      00000000
      --^--^-^
        |  | |
more info  | |
   modifiers |
        button

Button options
0 = MB1 pressed
1 = MB2 pressed
2 = MB3 pressed
3 = released

Formatting Guidelines

The standards outlined here shall be used in all wiki pages for this project. They exist to improve readability and make it easier to understand the requirements for certain sequences, commands and arguments.

NOTE: Unless marked as literal, spaces are not to be taken literally, and are only there to improve readability.

Argument formatting and escaping

  • Escaping: \arg (read as arg)
  • Optional argument: [arg]
  • Required argument: <arg>
  • Default value: {arg}
  • Miscellaneous info: (arg)
  • Multiple arguments can be supplied: arg...
  • Literal "arg" or arg
  • Acronym or predefined value $arg

Value limits

  • %d: Single numeric only.
  • %a: Single alphanumeric character only.
  • %l: Single letter only.
  • %s: String (any length unless specified otherwise in a custom condition).
  • %(<custom condition>): Custom condition(s).
  • ... can be suffixed to indicate that any amount greater than 0 is accepted

Examples

  • Specify a custom length: %a(length 1-5)
  • Specify a custom range: %a(range 9-1005)

Some common predefined values

More values can be defined in each wiki page, these are just some common ones. Additional values are usually at the bottom of said pages, or explained in tables with acronyms. Uppercase letters are not required, but strongly recommended. If uppercase is not suitable then CamelCase is another option.

  • $ESC: "Escape", character 27.
  • $CSI: Control Sequence Inducer, AKA $ESC\[
  • $SP: "Space", character 32.

Project Accela

Specifications

Terminal

Network protocol

Clone this wiki locally