keylayout

Documentation

Overview

Package keylayout maps keypresses between the player's physical keyboard layout and the QWERTY positions every binding is authored against (ADR 0022). Terminals deliver already-resolved characters, not physical scan codes, so all handling is character→character.

The model is "ingest-normalize + display-translate": a keypress is Normalize-d from the active layout back to its QWERTY-position rune before any binding match (so internal/tui/input.go's Keymap and every raw-string screen handler stay authored in QWERTY and need no changes), and key labels are Display-translated the other way at render time so the help overlay shows the player's actual keycaps.

Slice 1 ships QWERTY (identity) and QWERTZ (a single y↔z letter swap). The mechanism is general — adding a layout is a new injective rune map plus a test — but AZERTY, Dvorak, and punctuation position-mapping are deliberately out of scope (see ADR 0022). The package is a pure leaf: no imports, no upward dependency on settings or tui.

Index

• func Display(l Layout, r rune) rune
• func DisplayToken(l Layout, token string) string
• func Label(l Layout) string
• func Normalize(l Layout, r rune) rune
• func Valid(l Layout) bool
• type Layout
  • func All() []Layout
  • func Next(l Layout) Layout
  • func Resolve(s string) Layout

Functions

func Display

func Display(l Layout, r rune) rune

Display maps a QWERTY-authored rune to the rune that sits at the same physical key on layout l — the inverse of Normalize, used to translate key labels for rendering.

func DisplayToken

func DisplayToken(l Layout, token string) string

DisplayToken Display-translates every rune of a key-label token (e.g. "z / x" → "y / x" under QWERTZ). Apply only to the key-token field of a help row, never to its description — a description like "zoom in" must not have its letters swapped.

func Label

func Label(l Layout) string

Label returns the human-readable name shown in the Controls screen.

func Normalize

func Normalize(l Layout, r rune) rune

Normalize maps a rune typed on layout l back to its QWERTY-position rune. Runes the layout doesn't remap (and every rune under QWERTY) pass through unchanged.

func Valid

func Valid(l Layout) bool

Valid reports whether l is a known layout.

Types

type Layout

type Layout string

Layout identifies a physical keyboard layout. The string value is the stable key persisted in settings.json (settings.Settings.KeyboardLayout).

const (
	QWERTY Layout = "qwerty"
	QWERTZ Layout = "qwertz"
)

func All

func All() []Layout

All returns the layouts in cycle order. The caller must not mutate it.

func Next

func Next(l Layout) Layout

Next returns the layout after l in cycle order, wrapping around. An unknown l restarts the cycle at the first layout.

func Resolve

func Resolve(s string) Layout

Resolve coerces a persisted string to a known Layout, defaulting to QWERTY for the empty string (an absent settings.json field) or any unknown value (a newer build's layout this binary doesn't understand).