Raxol.Terminal.Driver.EventTranslator (Raxol Terminal v2.6.1)

Copy Markdown View Source

Translates termbox NIF events into Raxol.Core.Events.Event structs.

Keycode source of truth

key_code values below are the REAL TB_KEY_* constants vendored at packages/raxol_terminal/lib/termbox2_nif/c_src/termbox2/termbox2.h, not assumed. Two earlier bugs, found by review, are fixed here:

  • Arrow keys were mapped from 65/66/67/68 -- the ANSI CSI final bytes for A/B/C/D -- instead of the real TB_KEY_ARROW_{UP,DOWN,LEFT,RIGHT} values (0xffff - {18,19,20,21} = 65517/65516/65515/65514).
  • F1/F2 were mapped from 265/266 -- ncurses' KEY_F(1)/KEY_F(2) (KEY_F0 + n, KEY_F0 = 264) -- instead of the real TB_KEY_F1/ TB_KEY_F2 (0xffff - {0,1} = 65535/65534).

Both bugs meant a REAL termbox event for an arrow key or F1/F2 would have normalized to key: :unknown while the ANSI parser (input_parser.ex) correctly produced :up/:down/.../:f1/:f2 for the same physical keypress -- exactly the cross-shape divergence Raxol.UI.Harness.InputEvent's normalizer is supposed to make impossible. See @key_codes below for the full corrected table (nav keys, F1-F12) plus the control-key-code handling for Enter/Tab/Escape/Backspace.

Control keys (Enter/Tab/Escape/Backspace) share their numeric value with a plain ASCII control byte (TB_KEY_ENTER = 0x0d, same as a raw \r). Since it is not settled by inspection alone whether a real termbox integration reports these via char_code (raw byte) or key_code (TB_KEY_* constant, numerically identical for these), translate_key/3 checks BOTH: char_code is checked for a known control byte before the generic "printable char" branch (so a control byte can never leak through as char: on a kind: :char event), and key_code is checked against the same values as a fallback. Either wiring convention lands on the correct special-key atom.

Summary

Functions

Translates a termbox event map into an Event struct. Returns {:ok, event}, :ignore, or {:error, reason}.

Functions

translate(event_map)

Translates a termbox event map into an Event struct. Returns {:ok, event}, :ignore, or {:error, reason}.