Skip to content

Comments

GUACAMOLE-2220: Support Shift/Alt/Ctrl/Meta sequences for terminal navigation and function keys. #637

Draft
bbennett-ks wants to merge 1 commit intoapache:staging/1.6.1from
bbennett-ks:GUACAMOLE-2220-terminal-modifier-keys
Draft

GUACAMOLE-2220: Support Shift/Alt/Ctrl/Meta sequences for terminal navigation and function keys. #637
bbennett-ks wants to merge 1 commit intoapache:staging/1.6.1from
bbennett-ks:GUACAMOLE-2220-terminal-modifier-keys

Conversation

@bbennett-ks
Copy link
Contributor

@bbennett-ks bbennett-ks commented Feb 20, 2026

Overview

This change improves terminal keyboard interoperability by making special keys modifier-aware.

Arrows, function keys, and keypad variants now emit xterm-style modified escape sequences for Shift/Alt/Ctrl/Meta, while existing unmodified key behavior is preserved. It also cleans up key handling by replacing raw keysym literals with named constants and centralized helper logic, making behavior clearer and easier to maintain.

Detail of Changes

  • Introduces named keysym constants for modifier, navigation, function, editing, and keypad keys in src/terminal/terminal.c.
  • Adds helper logic to classify arrow/function keysyms and build xterm modifier parameters.
  • Encodes modified arrow keys as CSI sequences (for example, ESC [ 1 ; A/B/C/D).
  • Encodes modified function keys as CSI sequences (F1-F4 with P/Q/R/S, F5-F12 with ~ params).
  • Preserves Alt-prefix behavior for normal keys while avoiding duplicate ESC when modifiers are encoded directly in CSI sequences.
  • Expands modifier tracking to include additional alt/meta-related keysyms (including ISO level keys, Super, and Hyper).

Testing

Use showkey -a inside SSH or Telnet session to verify output.


  Press keys (Ctrl+D to exit)```

## Modifier Summary
  - No modifier: existing baseline sequences remain (for example arrows like ESC [ A/B/C/D).
  - Shift: modified special keys use CSI modifier ;2 (example Shift+Left -> ESC [ 1 ; 2 D).
  - Alt/Option: modified special keys use CSI modifier ;3 (example Alt+Left -> ESC [ 1 ; 3 D).
  - Ctrl: mapped printable combos still produce C0 control bytes; modified arrows/functions use CSI modifier ;5 (example Ctrl+Left -> ESC [ 1 ; 5 D).
  - Meta/Command: tracked and encoded in modifier parameter (+8, e.g. ;9 when Meta alone) for modified arrows/functions.

## Notes
  - Test both physical keyboard and Guacamole on-screen keyboard (OSK), since they can differ by platform/browser and help verify modifiers that are hard to produce physically.
  - Some combinations may be intercepted by host OS/window manager/browser before reaching Guacamole (common for Command+..., Ctrl+F4, global shortcuts, workspace switching, etc.).

@bbennett-ks bbennett-ks changed the title I choase 1. Now give a description of the changesGUACAMOLE-2220: Support Shift/Alt/Ctrl/Meta sequences for terminal navigation and function keys. GUACAMOLE-2220: Support Shift/Alt/Ctrl/Meta sequences for terminal navigation and function keys. Feb 20, 2026
@bbennett-ks bbennett-ks changed the title GUACAMOLE-2220: Support Shift/Alt/Ctrl/Meta sequences for terminal navigation and function keys. GUACAMOLE-2220: Support Shift/Alt/Ctrl/Meta sequences for terminal navigation and function keys. Feb 20, 2026
@bbennett-ks bbennett-ks force-pushed the GUACAMOLE-2220-terminal-modifier-keys branch from ce6b350 to 2c34445 Compare February 20, 2026 16:53
@bbennett-ks bbennett-ks marked this pull request as draft February 20, 2026 16:56
@bbennett-ks
Copy link
Contributor Author

I'm keeping this as a draft until I finish re-testing after a few more changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant