keys

Documentation

Overview

Package keys translates gocui key events into the byte sequences a terminal would have sent to a pty.

gocui hands us decoded events (a Key constant plus an optional rune), not raw input bytes: the terminal driver has already parsed the escape sequences on the way in. To drive a shell behind a pty we have to encode them back. This package is the whole of that translation, kept out of pkg/gui so it can be unit-tested without a terminal.

Index

• func EncodeMouse(ev MouseEvent, mode screen.MouseMode, sgr bool) []byte
• func Normalize(key gocui.Key, ch rune, mod gocui.Modifier) (gocui.Key, rune, gocui.Modifier)
• func Translate(key gocui.Key, ch rune, mod gocui.Modifier) []byte
• func TranslateWithMode(key gocui.Key, ch rune, mod gocui.Modifier, appCursorKeys bool) []byte
• type MouseButton
• type MouseEvent

Functions

func EncodeMouse

func EncodeMouse(ev MouseEvent, mode screen.MouseMode, sgr bool) []byte

EncodeMouse renders an event in the form the application asked for, or nil when this event is not one it asked to hear about.

Two encodings exist and the application picks. SGR (DECSET 1006) is the one everything modern sets, and the only one with no coordinate limit. The historical X10 form packs each coordinate into a single byte biased by 32, which caps it at column 223 — past that there is nothing correct to send, so nothing is sent rather than a wrong position.

func Normalize

func Normalize(key gocui.Key, ch rune, mod gocui.Modifier) (gocui.Key, rune, gocui.Modifier)

Normalize folds the several shapes a Ctrl-<letter> event can take into the single one the rest of the code expects: Key = gocui.KeyCtrl<X>, no rune, no control modifier.

This is not defensive programming, it is required: depending on the terminal and on which keyboard protocol it uses, the same Ctrl-B keypress reaches us either as KeyCtrlB with no modifier, or as the rune 'b' with ModCtrl set — and in the second shape it is indistinguishable from typing a plain "b".

func Translate

func Translate(key gocui.Key, ch rune, mod gocui.Modifier) []byte

Translate encodes a gocui key event as the bytes to write to a pty. It returns nil when the event has no meaningful encoding (mouse events, unknown keys), in which case the caller should drop it.

ModAlt is encoded the way terminals do it: an ESC prefix before the sequence.

It encodes in normal cursor mode; a caller that knows the target application's DECCKM state should use TranslateWithMode instead.

func TranslateWithMode

func TranslateWithMode(key gocui.Key, ch rune, mod gocui.Modifier, appCursorKeys bool) []byte

TranslateWithMode is Translate with the target application's cursor key mode taken into account: when appCursorKeys is set (the application sent ESC[?1h, which pkg/screen tracks as ApplicationCursorKeys), the arrows and Home/End are encoded as SS3 rather than CSI sequences.

Types

type MouseButton

type MouseButton int

MouseButton is which button an event is about, in the numbering the wire format itself uses — so the encoders below stay a formatting exercise rather than a translation one.

const (
	MouseButtonLeft      MouseButton = 0
	MouseButtonMiddle    MouseButton = 1
	MouseButtonRight     MouseButton = 2
	MouseButtonWheelUp   MouseButton = 64
	MouseButtonWheelDown MouseButton = 65
)

The buttons lazyshell can report. Wheel notches are buttons too in this protocol, from bit 6 upwards.

type MouseEvent

type MouseEvent struct {
	Button MouseButton
	X, Y   int
	// Press is false for a button being released. Ignored for wheel notches,
	// which have no release.
	Press bool
	// Motion marks the pointer having moved with the button held down.
	Motion bool
}

MouseEvent is one event to hand to the program running in a session. Coordinates are zero-based cells within the session's screen — EncodeMouse converts to the one-based numbering the wire format uses.