kitty/tools/tui/loop/mouse.go
Kovid Goyal 2d3ff7b240
Some checks are pending
CI / Linux (python=3.14 cc=clang sanitize=1) (push) Waiting to run
CI / Linux (python=3.12 cc=gcc sanitize=0) (push) Waiting to run
CI / Linux (python=3.13 cc=gcc sanitize=1) (push) Waiting to run
CI / Linux package (push) Waiting to run
CI / Bundle test (macos-latest) (push) Waiting to run
CI / Bundle test (ubuntu-latest) (push) Waiting to run
CI / macOS Brew (push) Waiting to run
CI / Test ./dev.sh and benchmark (push) Waiting to run
Support detailed wheel events in the kittens framework
Kittens can opt in with Loop.DetailedWheelEvents(), after which scroll
events arrive as MOUSE_WHEEL mouse events whose Wheel field has the
deltas, unit, multiplier, source, phase and momentum/inverted flags.
WheelEvent.Lines() converts the deltas to lines using the terminal's
multiplier when available.

The mouse-demo kitten uses this to move a block drawn with the graphics
protocol up and down with pixel precision, falling back to wheel button
presses in terminals without support, and shows the event details.
2026-11-16 13:43:41 +05:30

485 lines
12 KiB
Go

// License: GPLv3 Copyright: 2023, Kovid Goyal, <kovid at kovidgoyal.net>
package loop
import (
"fmt"
"strconv"
"strings"
)
var _ = fmt.Print
type MouseEventType uint
type MouseButtonFlag uint
const (
MOUSE_PRESS MouseEventType = iota
MOUSE_RELEASE
MOUSE_MOVE
MOUSE_CLICK
MOUSE_LEAVE
// A scroll event reported with detailed wheel events, see
// Loop.DetailedWheelEvents(). The details are in MouseEvent.Wheel.
MOUSE_WHEEL
)
func (e MouseEventType) String() string {
switch e {
case MOUSE_PRESS:
return "press"
case MOUSE_RELEASE:
return "release"
case MOUSE_MOVE:
return "move"
case MOUSE_CLICK:
return "click"
case MOUSE_LEAVE:
return "leave"
case MOUSE_WHEEL:
return "wheel"
}
return strconv.Itoa(int(e))
}
type PointerShape uint8
const (
// start pointer shape enum (auto generated by gen-key-constants.py do not edit)
DEFAULT_POINTER PointerShape = 0
TEXT_POINTER PointerShape = 1
POINTER_POINTER PointerShape = 2
HELP_POINTER PointerShape = 3
WAIT_POINTER PointerShape = 4
PROGRESS_POINTER PointerShape = 5
CROSSHAIR_POINTER PointerShape = 6
CELL_POINTER PointerShape = 7
VERTICAL_TEXT_POINTER PointerShape = 8
MOVE_POINTER PointerShape = 9
E_RESIZE_POINTER PointerShape = 10
NE_RESIZE_POINTER PointerShape = 11
NW_RESIZE_POINTER PointerShape = 12
N_RESIZE_POINTER PointerShape = 13
SE_RESIZE_POINTER PointerShape = 14
SW_RESIZE_POINTER PointerShape = 15
S_RESIZE_POINTER PointerShape = 16
W_RESIZE_POINTER PointerShape = 17
EW_RESIZE_POINTER PointerShape = 18
NS_RESIZE_POINTER PointerShape = 19
NESW_RESIZE_POINTER PointerShape = 20
NWSE_RESIZE_POINTER PointerShape = 21
ZOOM_IN_POINTER PointerShape = 22
ZOOM_OUT_POINTER PointerShape = 23
ALIAS_POINTER PointerShape = 24
COPY_POINTER PointerShape = 25
NOT_ALLOWED_POINTER PointerShape = 26
NO_DROP_POINTER PointerShape = 27
GRAB_POINTER PointerShape = 28
GRABBING_POINTER PointerShape = 29
// end pointer shape enum
)
func (e PointerShape) String() string {
switch e {
// start pointer shape tostring (auto generated by gen-key-constants.py do not edit)
case DEFAULT_POINTER:
return "default"
case TEXT_POINTER:
return "text"
case POINTER_POINTER:
return "pointer"
case HELP_POINTER:
return "help"
case WAIT_POINTER:
return "wait"
case PROGRESS_POINTER:
return "progress"
case CROSSHAIR_POINTER:
return "crosshair"
case CELL_POINTER:
return "cell"
case VERTICAL_TEXT_POINTER:
return "vertical-text"
case MOVE_POINTER:
return "move"
case E_RESIZE_POINTER:
return "e-resize"
case NE_RESIZE_POINTER:
return "ne-resize"
case NW_RESIZE_POINTER:
return "nw-resize"
case N_RESIZE_POINTER:
return "n-resize"
case SE_RESIZE_POINTER:
return "se-resize"
case SW_RESIZE_POINTER:
return "sw-resize"
case S_RESIZE_POINTER:
return "s-resize"
case W_RESIZE_POINTER:
return "w-resize"
case EW_RESIZE_POINTER:
return "ew-resize"
case NS_RESIZE_POINTER:
return "ns-resize"
case NESW_RESIZE_POINTER:
return "nesw-resize"
case NWSE_RESIZE_POINTER:
return "nwse-resize"
case ZOOM_IN_POINTER:
return "zoom-in"
case ZOOM_OUT_POINTER:
return "zoom-out"
case ALIAS_POINTER:
return "alias"
case COPY_POINTER:
return "copy"
case NOT_ALLOWED_POINTER:
return "not-allowed"
case NO_DROP_POINTER:
return "no-drop"
case GRAB_POINTER:
return "grab"
case GRABBING_POINTER:
return "grabbing"
// end pointer shape tostring
}
return strconv.Itoa(int(e))
}
const (
SHIFT_INDICATOR int = 1 << 2
ALT_INDICATOR = 1 << 3
CTRL_INDICATOR = 1 << 4
MOTION_INDICATOR = 1 << 5
SCROLL_BUTTON_INDICATOR = 1 << 6
EXTRA_BUTTON_INDICATOR = 1 << 7
LEAVE_INDICATOR = 1 << 8
)
const (
NO_MOUSE_BUTTON MouseButtonFlag = 0
LEFT_MOUSE_BUTTON MouseButtonFlag = 1 << iota
MIDDLE_MOUSE_BUTTON
RIGHT_MOUSE_BUTTON
FOURTH_MOUSE_BUTTON
FIFTH_MOUSE_BUTTON
SIXTH_MOUSE_BUTTON
SEVENTH_MOUSE_BUTTON
MOUSE_WHEEL_UP
MOUSE_WHEEL_DOWN
MOUSE_WHEEL_LEFT
MOUSE_WHEEL_RIGHT
)
var bmap = [...]MouseButtonFlag{LEFT_MOUSE_BUTTON, MIDDLE_MOUSE_BUTTON, RIGHT_MOUSE_BUTTON}
var ebmap = [...]MouseButtonFlag{FOURTH_MOUSE_BUTTON, FIFTH_MOUSE_BUTTON, SIXTH_MOUSE_BUTTON, SEVENTH_MOUSE_BUTTON}
var wbmap = [...]MouseButtonFlag{MOUSE_WHEEL_UP, MOUSE_WHEEL_DOWN, MOUSE_WHEEL_LEFT, MOUSE_WHEEL_RIGHT}
func (b MouseButtonFlag) String() string {
ans := ""
switch {
case b&LEFT_MOUSE_BUTTON != 0:
ans += "|LEFT"
case b&MIDDLE_MOUSE_BUTTON != 0:
ans += "|MIDDLE"
case b&RIGHT_MOUSE_BUTTON != 0:
ans += "|RIGHT"
case b&FOURTH_MOUSE_BUTTON != 0:
ans += "|FOURTH"
case b&FIFTH_MOUSE_BUTTON != 0:
ans += "|FIFTH"
case b&SIXTH_MOUSE_BUTTON != 0:
ans += "|SIXTH"
case b&SEVENTH_MOUSE_BUTTON != 0:
ans += "|SEVENTH"
case b&MOUSE_WHEEL_UP != 0:
ans += "|WHEEL_UP"
case b&MOUSE_WHEEL_DOWN != 0:
ans += "|WHEEL_DOWN"
case b&MOUSE_WHEEL_LEFT != 0:
ans += "|WHEEL_LEFT"
case b&MOUSE_WHEEL_RIGHT != 0:
ans += "|WHEEL_RIGHT"
}
ans = strings.TrimLeft(ans, "|")
if ans == "" {
ans = "NONE"
}
return ans
}
// The unit of the deltas in a WheelEvent
type WheelUnit uint8
const (
// Fractions of a wheel click, with one click being 120
WHEEL_UNIT_V120 WheelUnit = 1
// Pixels
WHEEL_UNIT_PIXELS WheelUnit = 2
)
func (u WheelUnit) String() string {
switch u {
case WHEEL_UNIT_V120:
return "v120"
case WHEEL_UNIT_PIXELS:
return "pixels"
}
return strconv.Itoa(int(u))
}
// The kind of device a WheelEvent comes from
type WheelSource uint8
const (
WHEEL_SOURCE_UNKNOWN WheelSource = iota
WHEEL_SOURCE_WHEEL
WHEEL_SOURCE_FINGER
WHEEL_SOURCE_CONTINUOUS
WHEEL_SOURCE_WHEEL_TILT
)
func (s WheelSource) String() string {
switch s {
case WHEEL_SOURCE_UNKNOWN:
return "unknown"
case WHEEL_SOURCE_WHEEL:
return "wheel"
case WHEEL_SOURCE_FINGER:
return "finger"
case WHEEL_SOURCE_CONTINUOUS:
return "continuous"
case WHEEL_SOURCE_WHEEL_TILT:
return "wheel-tilt"
}
return strconv.Itoa(int(s))
}
// Where a WheelEvent is in a scroll gesture, or in the momentum scrolling
// after it, when WheelEvent.Momentum is true
type WheelPhase uint8
const (
WHEEL_PHASE_NONE WheelPhase = iota
WHEEL_PHASE_BEGAN
WHEEL_PHASE_CHANGED
WHEEL_PHASE_ENDED
WHEEL_PHASE_CANCELLED
WHEEL_PHASE_MAY_BEGIN
)
func (p WheelPhase) String() string {
switch p {
case WHEEL_PHASE_NONE:
return "none"
case WHEEL_PHASE_BEGAN:
return "began"
case WHEEL_PHASE_CHANGED:
return "changed"
case WHEEL_PHASE_ENDED:
return "ended"
case WHEEL_PHASE_CANCELLED:
return "cancelled"
case WHEEL_PHASE_MAY_BEGIN:
return "may-begin"
}
return strconv.Itoa(int(p))
}
const (
WHEEL_FLAG_MOMENTUM = 1
WHEEL_FLAG_INVERTED = 2
)
// The details of a scroll event reported with detailed wheel events
type WheelEvent struct {
// Positive DY is downwards, towards the end of the content, positive DX is rightwards
DX, DY int
Unit WheelUnit
// The scroll multiplier the user has configured in the terminal for this
// kind of scrolling, or zero if the terminal did not send it
Multiplier float64
Source WheelSource
Phase WheelPhase
// Momentum is true for inertial scrolling, after the fingers are lifted.
// Inverted is true when the deltas are reversed relative to the physical
// movement of the device, for example, because of natural scrolling.
Momentum, Inverted bool
}
func (w WheelEvent) String() string {
ans := fmt.Sprintf("dx=%d dy=%d unit=%s source=%s phase=%s", w.DX, w.DY, w.Unit, w.Source, w.Phase)
if w.Multiplier > 0 {
ans += " multiplier=" + strconv.FormatFloat(w.Multiplier, 'f', -1, 64)
}
if w.Momentum {
ans += " momentum"
}
if w.Inverted {
ans += " inverted"
}
return ans
}
// Converts the deltas to a (fractional) number of lines, using the
// multiplier from the terminal, if any, otherwise default_lines_per_click for
// wheels. For pixel deltas cell_height is used.
func (w WheelEvent) Lines(cell_height int, default_lines_per_click float64) (dx, dy float64) {
switch w.Unit {
case WHEEL_UNIT_PIXELS:
m := 1.0
if w.Multiplier > 0 {
m = w.Multiplier
}
if cell_height > 0 {
return m * float64(w.DX) / float64(cell_height), m * float64(w.DY) / float64(cell_height)
}
default:
m := default_lines_per_click
if w.Multiplier > 0 {
m = w.Multiplier
}
return m * float64(w.DX) / 120, m * float64(w.DY) / 120
}
return 0, 0
}
type MouseEvent struct {
Event_type MouseEventType
Buttons MouseButtonFlag
Mods KeyModifiers
Cell, Pixel struct{ X, Y int }
// Set only for events of type MOUSE_WHEEL
Wheel WheelEvent
}
func (e MouseEvent) String() string {
if e.Event_type == MOUSE_WHEEL {
return fmt.Sprintf("MouseEvent{%s %s %s Cell:%v Pixel:%v}", e.Event_type, e.Wheel, e.Mods, e.Cell, e.Pixel)
}
return fmt.Sprintf("MouseEvent{%s %s %s Cell:%v Pixel:%v}", e.Event_type, e.Buttons, e.Mods, e.Cell, e.Pixel)
}
func pixel_to_cell(px, length, cell_length int) int {
px = max(0, min(px, length-1))
if cell_length > 0 {
return px / cell_length
}
return 0
}
func decode_sgr_mouse(text string, screen_size ScreenSize, last_letter byte) *MouseEvent {
text = text[:len(text)-1]
parts := strings.Split(text, ";")
if len(parts) != 3 {
return nil
}
cb, err := strconv.Atoi(parts[0])
if err != nil {
return nil
}
ans := MouseEvent{}
ans.Pixel.X, err = strconv.Atoi(parts[1])
if err != nil {
return nil
}
if len(parts[2]) < 1 {
return nil
}
if ans.Pixel.Y, err = strconv.Atoi(parts[2]); err != nil {
return nil
}
if last_letter == 'm' {
ans.Event_type = MOUSE_RELEASE
} else if cb&MOTION_INDICATOR != 0 {
ans.Event_type = MOUSE_MOVE
}
cb3 := cb & 3
switch {
case cb&LEAVE_INDICATOR != 0:
ans.Event_type = MOUSE_LEAVE
case cb&EXTRA_BUTTON_INDICATOR != 0:
ans.Buttons |= ebmap[cb3]
case cb&SCROLL_BUTTON_INDICATOR != 0:
ans.Buttons |= wbmap[cb3]
case cb3 < 3:
ans.Buttons |= bmap[cb3]
}
if cb&SHIFT_INDICATOR != 0 {
ans.Mods |= SHIFT
}
if cb&ALT_INDICATOR != 0 {
ans.Mods |= ALT
}
if cb&CTRL_INDICATOR != 0 {
ans.Mods |= CTRL
}
ans.Cell.X = pixel_to_cell(ans.Pixel.X, int(screen_size.WidthPx), int(screen_size.CellWidth))
ans.Cell.Y = pixel_to_cell(ans.Pixel.Y, int(screen_size.HeightPx), int(screen_size.CellHeight))
return &ans
}
// Decodes a detailed wheel event:
// CSI > x ; y ; dx ; dy ; unit[:multiplier] ; source ; phase ; flags ; mods M
// Unknown trailing parameters and sub-parameters are ignored, as required by
// the specification.
func decode_wheel_event(text string, screen_size ScreenSize) *MouseEvent {
parts := strings.Split(text[:len(text)-1], ";")
if len(parts) < 9 {
return nil
}
var subparams [9][]string
nums := [9]int{}
for i := range subparams {
subparams[i] = strings.Split(parts[i], ":")
n, err := strconv.Atoi(subparams[i][0])
if err != nil {
return nil
}
nums[i] = n
}
ans := MouseEvent{Event_type: MOUSE_WHEEL}
ans.Pixel.X, ans.Pixel.Y = nums[0], nums[1]
w := &ans.Wheel
w.DX, w.DY = nums[2], nums[3]
w.Unit = WheelUnit(nums[4])
if len(subparams[4]) > 1 {
if m, err := strconv.ParseFloat(subparams[4][1], 64); err == nil && m > 0 {
w.Multiplier = m
}
}
w.Source = WheelSource(nums[5])
w.Phase = WheelPhase(nums[6])
w.Momentum = nums[7]&WHEEL_FLAG_MOMENTUM != 0
w.Inverted = nums[7]&WHEEL_FLAG_INVERTED != 0
if nums[8] > 0 {
ans.Mods = KeyModifiers(nums[8] - 1)
}
ans.Cell.X = pixel_to_cell(ans.Pixel.X, int(screen_size.WidthPx), int(screen_size.CellWidth))
ans.Cell.Y = pixel_to_cell(ans.Pixel.Y, int(screen_size.HeightPx), int(screen_size.CellHeight))
return &ans
}
func MouseEventFromCSI(csi string, screen_size ScreenSize) *MouseEvent {
if len(csi) == 0 {
return nil
}
last_char := csi[len(csi)-1]
if last_char != 'm' && last_char != 'M' {
return nil
}
switch csi[0] {
case '<':
return decode_sgr_mouse(csi[1:], screen_size, last_char)
case '>':
if last_char == 'M' {
return decode_wheel_event(csi[1:], screen_size)
}
return nil
default:
return nil
}
}