Support detailed wheel events in the kittens framework
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

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.
This commit is contained in:
Kovid Goyal 2026-11-16 09:32:24 +05:30
parent 693b5d44d6
commit c2df6fefeb
No known key found for this signature in database
GPG key ID: 06BC317B515ACE7C
5 changed files with 361 additions and 2 deletions

View file

@ -12,6 +12,7 @@ import (
"github.com/emmansun/base64"
"github.com/kovidgoyal/kitty/tools/tty"
"github.com/kovidgoyal/kitty/tools/tui/graphics"
"github.com/kovidgoyal/kitty/tools/tui/loop"
)
@ -136,6 +137,75 @@ func draw_rounded_box(lp *loop.Loop, width int, lines []string) {
lp.QueueWriteString("╰" + strings.Repeat("─", inner_width) + "╯\r\n")
}
// A block drawn with the graphics protocol that is moved up and down by
// scrolling, to demonstrate detailed wheel events
const (
block_image_id = 7523
block_columns = 8
block_rows = 4
lines_per_click = 3 // used when the terminal does not send its multiplier
block_color_red = 0x4a
block_color_green = 0x9e
block_color_blue = 0xff
)
type scroll_block struct {
y float64 // position of the top of the block in pixels
// The pixel data of the block and the size it was created for
pixels []byte
pixels_for_cell_width uint
pixels_for_cell_height uint
}
// scroll moves the block by the specified number of lines, keeping it on screen
func (b *scroll_block) scroll(lines float64, sz loop.ScreenSize) {
b.y += lines * float64(sz.CellHeight)
b.clamp(sz)
}
func (b *scroll_block) clamp(sz loop.ScreenSize) {
max_y := float64(int(sz.HeightPx) - block_rows*int(sz.CellHeight))
b.y = max(0, min(b.y, max_y))
}
// draw places the block at its current position. The image is a solid
// color, so it compresses to very little and is cheap to send with every
// placement. It is drawn below the text so as not to obscure it.
func (b *scroll_block) draw(lp *loop.Loop, sz loop.ScreenSize) {
if sz.CellHeight == 0 || sz.CellWidth == 0 || sz.WidthCells < block_columns {
return
}
width, height := block_columns*sz.CellWidth, block_rows*sz.CellHeight
if b.pixels_for_cell_width != sz.CellWidth || b.pixels_for_cell_height != sz.CellHeight {
b.pixels = make([]byte, 0, width*height*3)
for range width * height {
b.pixels = append(b.pixels, block_color_red, block_color_green, block_color_blue)
}
b.pixels_for_cell_width, b.pixels_for_cell_height = sz.CellWidth, sz.CellHeight
}
b.clamp(sz)
y := int(b.y)
row, offset := y/int(sz.CellHeight), y%int(sz.CellHeight)
lp.SaveCursorPosition()
defer lp.RestoreCursorPosition()
lp.MoveCursorTo(int(sz.WidthCells)-block_columns+1, row+1)
gc := &graphics.GraphicsCommand{}
gc.SetAction(graphics.GRT_action_transmit_and_display).SetFormat(graphics.GRT_format_rgb).SetDataWidth(uint64(width)).SetDataHeight(uint64(height))
gc.SetImageId(block_image_id).SetPlacementId(1).SetYOffset(uint64(offset))
gc.SetCursorMovement(graphics.GRT_cursor_static).SetQuiet(graphics.GRT_quiet_silent).SetZIndex(-1)
if err := gc.WriteWithPayloadToLoop(lp, b.pixels); err != nil {
debugprintln("Failed to draw the scroll block:", err)
}
}
func (b *scroll_block) delete(lp *loop.Loop) {
gc := &graphics.GraphicsCommand{}
gc.SetAction(graphics.GRT_action_delete).SetDelete(graphics.GRT_free_by_id).SetImageId(block_image_id).SetQuiet(graphics.GRT_quiet_silent)
if err := gc.WriteWithPayloadToLoop(lp, nil); err != nil {
debugprintln("Failed to delete the scroll block:", err)
}
}
func Run(args []string) (rc int, err error) {
all_pointer_shapes := []loop.PointerShape{
// start all pointer shapes (auto generated by gen-key-constants.py do not edit)
@ -183,9 +253,10 @@ func Run(args []string) (rc int, err error) {
if err != nil {
return 1, err
}
lp.MouseTrackingMode(loop.FULL_MOUSE_TRACKING)
lp.MouseTrackingMode(loop.FULL_MOUSE_TRACKING).DetailedWheelEvents()
var current_mouse_event *loop.MouseEvent
var dnd dnd_state
var block scroll_block
// build_box_lines computes the drop box content lines based on current state.
build_box_lines := func() []string {
@ -251,9 +322,15 @@ func Run(args []string) (rc int, err error) {
// and computing the drop box position.
y := 0
if s, err := lp.ScreenSize(); err == nil {
defer block.draw(lp, s)
}
if current_mouse_event == nil {
lp.Println(`Move the mouse or click to see mouse events`)
y++
lp.Println(`Scroll with a wheel or touchpad to move the block`)
y++
lp.Println("Hover the mouse over the names below to see the shapes")
y++
lp.Println()
@ -278,6 +355,10 @@ func Run(args []string) (rc int, err error) {
y++
lp.Printf("Type : %s\r\n", current_mouse_event.Event_type)
y++
if current_mouse_event.Event_type == loop.MOUSE_WHEEL {
lp.Printf("Wheel : %s\r\n", current_mouse_event.Wheel)
y++
}
if current_mouse_event.Buttons != loop.NO_MOUSE_BUTTON {
lp.Println(current_mouse_event.Buttons.String())
y++
@ -558,12 +639,25 @@ func Run(args []string) (rc int, err error) {
return "", nil
}
lp.OnFinalize = func() string {
block.delete(lp)
lp.SetCursorVisible(true)
lp.StopAcceptingDrops()
return ""
}
lp.OnMouseEvent = func(ev *loop.MouseEvent) error {
if sz, err := lp.ScreenSize(); err == nil {
switch {
case ev.Event_type == loop.MOUSE_WHEEL:
_, lines := ev.Wheel.Lines(int(sz.CellHeight), lines_per_click)
block.scroll(lines, sz)
case ev.Event_type == loop.MOUSE_PRESS && ev.Buttons&loop.MOUSE_WHEEL_UP != 0:
// The terminal does not support detailed wheel events
block.scroll(-lines_per_click, sz)
case ev.Event_type == loop.MOUSE_PRESS && ev.Buttons&loop.MOUSE_WHEEL_DOWN != 0:
block.scroll(lines_per_click, sz)
}
}
current_mouse_event = ev
draw_screen()
return nil

View file

@ -233,6 +233,20 @@ func MouseTrackingMode(self *Loop, mt MouseTracking) {
self.terminal_options.mouse_tracking = mt
}
// Have scroll events reported as MOUSE_WHEEL events with full detail, such as
// high resolution and pixel deltas, gesture phases and momentum, instead of
// as presses of the wheel buttons. Has an effect only if mouse tracking is
// enabled and the terminal supports it, otherwise, scroll events are still
// reported as wheel button presses, so kittens must handle both.
func (self *Loop) DetailedWheelEvents() *Loop {
self.terminal_options.detailed_wheel_events = true
return self
}
func DetailedWheelEvents(self *Loop) {
self.terminal_options.detailed_wheel_events = true
}
func NoMouseTracking(self *Loop) {
self.terminal_options.mouse_tracking = NO_MOUSE_TRACKING
}

View file

@ -19,6 +19,9 @@ const (
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 {
@ -31,6 +34,10 @@ func (e MouseEventType) String() string {
return "move"
case MOUSE_CLICK:
return "click"
case MOUSE_LEAVE:
return "leave"
case MOUSE_WHEEL:
return "wheel"
}
return strconv.Itoa(int(e))
}
@ -203,14 +210,155 @@ func (b MouseButtonFlag) String() string {
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)
}
@ -274,6 +422,47 @@ func decode_sgr_mouse(text string, screen_size ScreenSize, last_letter byte) *Mo
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
@ -285,6 +474,11 @@ func MouseEventFromCSI(csi string, screen_size ScreenSize) *MouseEvent {
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
}

View file

@ -0,0 +1,52 @@
// License: GPLv3 Copyright: 2026, Kovid Goyal, <kovid at kovidgoyal.net>
package loop
import (
"testing"
"github.com/google/go-cmp/cmp"
)
func TestDecodeWheelEvent(t *testing.T) {
sz := ScreenSize{WidthPx: 1000, HeightPx: 500, CellWidth: 10, CellHeight: 20}
ev := func(x, y int, mods KeyModifiers, w WheelEvent) *MouseEvent {
ans := &MouseEvent{Event_type: MOUSE_WHEEL, Mods: mods, Wheel: w}
ans.Pixel.X, ans.Pixel.Y = x, y
ans.Cell.X, ans.Cell.Y = x/10, y/20
return ans
}
for csi, expected := range map[string]*MouseEvent{
">45;65;0;120;1:5;1;0;0;1M": ev(45, 65, 0, WheelEvent{DY: 120, Unit: WHEEL_UNIT_V120, Multiplier: 5, Source: WHEEL_SOURCE_WHEEL}),
">45;65;-3;-42;2:1.5;2;2;0;5M": ev(45, 65, CTRL, WheelEvent{
DX: -3, DY: -42, Unit: WHEEL_UNIT_PIXELS, Multiplier: 1.5, Source: WHEEL_SOURCE_FINGER, Phase: WHEEL_PHASE_CHANGED}),
">45;65;0;0;2;2;3;3;1M": ev(45, 65, 0, WheelEvent{
Unit: WHEEL_UNIT_PIXELS, Source: WHEEL_SOURCE_FINGER, Phase: WHEEL_PHASE_ENDED, Momentum: true, Inverted: true}),
// Unknown parameters and sub-parameters are ignored
">45;65:7;0;120:3;1:5:9;1;0;0;1;99:1M": ev(45, 65, 0, WheelEvent{DY: 120, Unit: WHEEL_UNIT_V120, Multiplier: 5, Source: WHEEL_SOURCE_WHEEL}),
// Too few parameters or wrong final byte
">45;65;0;120;1;1;0;0M": nil,
">45;65;0;120;1;1;0;0;1m": nil,
">45;65;x;120;1;1;0;0;1M": nil,
"<64;45;65M": {Buttons: MOUSE_WHEEL_UP, Pixel: struct{ X, Y int }{45, 65}, Cell: struct{ X, Y int }{4, 3}},
">45;65;0;120;1:0;1;0;0;1M": ev(45, 65, 0, WheelEvent{DY: 120, Unit: WHEEL_UNIT_V120, Source: WHEEL_SOURCE_WHEEL}),
} {
actual := MouseEventFromCSI(csi, sz)
if diff := cmp.Diff(expected, actual); diff != "" {
t.Fatalf("Failed to decode %#v:\n%s", csi, diff)
}
}
// Lines conversion uses the multiplier when present
w := WheelEvent{DY: 240, Unit: WHEEL_UNIT_V120, Multiplier: 5}
if _, dy := w.Lines(20, 3); dy != 10 {
t.Fatalf("Wrong number of lines: %v", dy)
}
w.Multiplier = 0
if _, dy := w.Lines(20, 3); dy != 6 {
t.Fatalf("Wrong number of lines: %v", dy)
}
w = WheelEvent{DY: -30, Unit: WHEEL_UNIT_PIXELS}
if _, dy := w.Lines(20, 3); dy != -1.5 {
t.Fatalf("Wrong number of lines: %v", dy)
}
}

View file

@ -69,6 +69,7 @@ const (
PENDING_UPDATE Mode = 2026 | private
COLOR_SCHEME_CHANGE_NOTIFICATION Mode = 2031 | private
INBAND_RESIZE_NOTIFICATION Mode = 2048 | private
WHEEL_EVENTS Mode = 5523 | private
HANDLE_TERMIOS_SIGNALS Mode = kitty.HandleTermiosSignals | private
)
@ -105,6 +106,7 @@ type TerminalStateOptions struct {
kitty_keyboard_mode KeyboardStateBits
in_band_resize_notification bool
focus_tracking bool
detailed_wheel_events bool
color_scheme_change_notification bool
// Set this to true to avoid doing a query response loop to the terminal at
// exit. This loop is needed for most kittens to ensure that in-flight
@ -139,7 +141,7 @@ func (self *TerminalStateOptions) SetStateEscapeCodes() string {
sb.WriteString(DECSACE_DEFAULT_REGION_SELECT)
reset_modes(&sb,
IRM, DECKM, DECSCNM, BRACKETED_PASTE,
MOUSE_BUTTON_TRACKING, MOUSE_MOTION_TRACKING, MOUSE_MOVE_TRACKING, MOUSE_UTF8_MODE, MOUSE_SGR_MODE)
MOUSE_BUTTON_TRACKING, MOUSE_MOTION_TRACKING, MOUSE_MOVE_TRACKING, MOUSE_UTF8_MODE, MOUSE_SGR_MODE, WHEEL_EVENTS)
set_modes(&sb, DECARM, DECAWM, DECTCEM)
if self.focus_tracking {
set_modes(&sb, FOCUS_TRACKING)
@ -171,6 +173,9 @@ func (self *TerminalStateOptions) SetStateEscapeCodes() string {
case FULL_MOUSE_TRACKING:
sb.WriteString(MOUSE_MOVE_TRACKING.EscapeCodeToSet())
}
if self.detailed_wheel_events {
sb.WriteString(WHEEL_EVENTS.EscapeCodeToSet())
}
}
return sb.String()
}