Skip to content

Fix help menu key binding - enable both Ctrl+? and Ctrl+H #211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

PierrunoYT
Copy link

@PierrunoYT PierrunoYT commented Jun 8, 2025

Problem

The help menu was not responding when users pressed Ctrl+? as documented, particularly affecting Windows/PowerShell users. This was due to terminal key mapping differences where Ctrl+? gets interpreted as different key codes than expected.

Root Cause Analysis

Through debugging, we discovered that:

  • Ctrl+? was being interpreted as ESC (key code 27) in Windows/PowerShell
  • Ctrl+H was being interpreted as backspace (key code 127) which works reliably
  • Different terminals handle control key combinations with special characters inconsistently

Solution

Enhanced key binding system that supports both shortcuts:

  • Ctrl+? - Now works via intelligent ESC key handling when no dialogs are open
  • Ctrl+H - Works reliably as primary alternative across all terminals
  • Multiple fallbacks - ctrl+/, ctrl+_, delete, backspace for maximum compatibility

Smart ESC handling:

  • When ESC is pressed and no dialogs are open, it's treated as potential Ctrl+? for help
  • Preserves normal ESC behavior when dialogs are active
  • Provides seamless user experience

Updated documentation and UI:

  • Status bar shows ctrl+?/ctrl+h help indicating both shortcuts work
  • README.md documents Ctrl+? / Ctrl+H as working help shortcuts
  • Help dialog displays both shortcuts in the keyboard shortcuts list
  • Fixed unrelated documentation issue: corrected switch session shortcut from Ctrl+A to Ctrl+S

Testing Results

  • Ctrl+? now works on Windows/PowerShell (via intelligent ESC handling)
  • Ctrl+H works reliably across all terminal environments
  • ✅ Help menu displays correctly with all keyboard shortcuts
  • ✅ Application builds successfully
  • ✅ Other keyboard shortcuts remain unaffected
  • ✅ No breaking changes to existing functionality
  • ✅ ESC key still works normally for closing dialogs

Technical Implementation

Key Binding Strategy

Help: key.NewBinding(
    key.WithKeys("ctrl+?", "ctrl+/", "ctrl+_", "ctrl+h", "delete", "backspace"),
    key.WithHelp("ctrl+?/ctrl+h", "toggle help"),
),

Intelligent ESC Handling

// Special handling for Ctrl+? which might be interpreted as ESC in some terminals
if msg.Type == tea.KeyEsc && !a.showQuit && !a.showHelp && !a.showSessionDialog && !a.showCommandDialog && !a.showFilepicker && !a.showModelDialog && !a.showMultiArgumentsDialog {
    // If ESC is pressed and no dialogs are open, treat it as potential Ctrl+? for help
    a.showHelp = !a.showHelp
    return a, nil
}

Impact

  • ✅ Fixes accessibility issue for Windows users who couldn't access the help menu
  • ✅ Maintains backward compatibility by keeping multiple key binding options
  • ✅ Improves user experience with reliable, documented shortcuts that actually work
  • ✅ Cross-platform compatibility - works on Windows, Linux, macOS terminals
  • ✅ No breaking changes to existing functionality
  • ✅ Enhanced documentation reflects actual working shortcuts

Files Changed

  • internal/tui/tui.go - Enhanced help key bindings + intelligent ESC handling
  • internal/tui/components/core/status.go - Updated status bar to show both shortcuts
  • README.md - Updated documentation for correct shortcuts

User Experience

Users can now reliably access the help menu using either:

  • Ctrl+? (the originally documented shortcut) ✅
  • Ctrl+H (reliable cross-platform alternative) ✅

Both shortcuts display a comprehensive help dialog with all available keyboard shortcuts.


Closes: Issue where help menu was inaccessible to Windows/PowerShell users
Resolves: Cross-platform terminal key mapping inconsistencies for help access

- Fix key binding for help menu to use ctrl+? instead of ctrl+_
- Update README.md to correct switch session shortcut from Ctrl+A to Ctrl+S
- Ensures help menu shows up when users press Ctrl+? as expected
- Resolves issue where help menu was not responding to the documented shortcut
- Add multiple key binding alternatives for help menu (ctrl+h, ctrl+?, ctrl+/, ctrl+_, delete, backspace)
- Fix issue where Ctrl+? was being interpreted as ESC (key code 27) in Windows/PowerShell
- Discover that Ctrl+H sends backspace (key code 127) which works reliably
- Update status bar help text to show 'ctrl+h help' instead of 'ctrl+?'
- Update README.md to document Ctrl+H as the working help shortcut
- Resolves help menu accessibility issue for Windows users
- Add intelligent ESC key handling to support Ctrl+? in terminals that interpret it as ESC
- Maintain multiple key binding alternatives (ctrl+h, ctrl+?, ctrl+/, ctrl+_, delete, backspace)
- Update UI text to show both shortcuts: 'ctrl+?/ctrl+h help'
- Update README.md to document both working shortcuts
- Ensure help menu works reliably across different terminal environments
- Resolves cross-platform accessibility issues for help menu access

Both Ctrl+? and Ctrl+H now work reliably for toggling the help menu.
@PierrunoYT PierrunoYT changed the title Fix help menu key binding for Windows/PowerShell users Fix help menu key binding - enable both Ctrl+? and Ctrl+H Jun 8, 2025
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