From c2df6fefeb764271f2a9ff4dc52a2e7c15b6cb8e Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Mon, 16 Nov 2026 09:32:24 +0530 Subject: [PATCH] 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. --- tools/cmd/mouse_demo/main.go | 96 ++++++++++++++- tools/tui/loop/api.go | 14 +++ tools/tui/loop/mouse.go | 194 +++++++++++++++++++++++++++++++ tools/tui/loop/mouse_test.go | 52 +++++++++ tools/tui/loop/terminal-state.go | 7 +- 5 files changed, 361 insertions(+), 2 deletions(-) create mode 100644 tools/tui/loop/mouse_test.go diff --git a/tools/cmd/mouse_demo/main.go b/tools/cmd/mouse_demo/main.go index 23fb1d4bb..c8313deb7 100644 --- a/tools/cmd/mouse_demo/main.go +++ b/tools/cmd/mouse_demo/main.go @@ -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 diff --git a/tools/tui/loop/api.go b/tools/tui/loop/api.go index d2efab6f5..3ca91ea11 100644 --- a/tools/tui/loop/api.go +++ b/tools/tui/loop/api.go @@ -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 } diff --git a/tools/tui/loop/mouse.go b/tools/tui/loop/mouse.go index 03f6adb8f..9a8f47cb5 100644 --- a/tools/tui/loop/mouse.go +++ b/tools/tui/loop/mouse.go @@ -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 } diff --git a/tools/tui/loop/mouse_test.go b/tools/tui/loop/mouse_test.go new file mode 100644 index 000000000..2123a3fb6 --- /dev/null +++ b/tools/tui/loop/mouse_test.go @@ -0,0 +1,52 @@ +// License: GPLv3 Copyright: 2026, Kovid Goyal, + +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) + } +} diff --git a/tools/tui/loop/terminal-state.go b/tools/tui/loop/terminal-state.go index 83389db1a..e7aa50994 100644 --- a/tools/tui/loop/terminal-state.go +++ b/tools/tui/loop/terminal-state.go @@ -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() }