Visualize Keyboard Shortcuts for Emacs Commands

Overview

keyboard-visualizer is an Emacs package that allows users to visualize keyboard shortcuts as key sequences on a keyboard layout. This package can highlight keys for single or multi-chord commands and display side-by-side layouts for all chords in a sequence.

Whether you’re a new user learning Emacs keybindings or an advanced user customizing your workflows, keyboard-visualizer provides an intuitive way to understand and practice keyboard shortcuts.

Potential names

Not sure I’m completely happy with the name “keyboard-visualizer.” It seems a bit mundane. I’d like something a bit more memorable. The ideas are…

• KeyViz - Short and catchy, indicating “Key Visualization.”
• ChordView - Emphasizes the multi-chord visualization aspect.

My current inclination is for KeyViz.

Screenshots

Features

• Visualize keyboard shortcuts with real-time highlighting on a keyboard layout.
  • Supports single-chord and multi-chord commands.
  • Displays side-by-side layouts for multi-chord commands.
• Fuzzy search for commands with natural language queries:
  • Example: Type “save file”, and the package visualizes the `C-x C-s` keybinding.
• Save keyboard layouts to files for later reference.
• Randomized practice mode to learn and memorize keybindings.
• Toggleable “insert mode” to show layouts for recent commands as you type.
• Highly customizable:
  • Define custom keyboard layouts.
  • Full control over displayed faces and styles.

Whats New

<2025-01-28>

Added shift key and lambda function support

• Add shift key mapping to properly visualize shifted characters (e.g., “!” -> “Shift-1”)
• Enhance command visualization to handle and display lambda functions
• Improve documentation display to show lambda function definitions

<2025-01-27>

A major refactor and some functional improvements

Functionality Improvements:

• Simplified and optimized keyside determination with `keyboard-visualizer–key-sides`.

User Interaction:

• Enhanced `keyboard-visualizer-menu` with clearer navigation:
  • Toggle ergonomic indicators, documentation display, and visualizer mode.
  • Explore commands via fuzzy search (`keyboard-visualizer-learn-command-by-query`) or random steps (`keyboard-visualizer-learning-step`).
  • Save the current layout with a dedicated option.
• Added `keyboard-visualizer-documentation-toggle` to enable/disable displaying command documentation.

Refactoring:

• Consolidated and streamlined redundant functions for simplicity and readability.
• Improved buffer management for visualizer output:
  • Handles layout buffer cleanup when disabling.
  • Ensures exclusive usage of the visualizer buffer.

Keybindings:

• Updated keybindings:
  • `C-c b` for opening `keyboard-visualizer-menu`.

<2025-01-26>

Added ergonomic indicator

• Enhanced `keyboard-visualizer–draw-single-layout` to optionally highlight non-ergonomic key combinations based on chord-side alignment.
• Added `keyboard-visualizer–key-side` helper function to determine if a key belongs to the left or right side of the keyboard layout.
• Implemented `keyboard-visualizer-ergonomic-indicator-toggle` to allow toggling ergonomic highlighting via user interaction.
• Added a new customizable variable `keyboard-visualizer-ergonomic-indicator` to manage the state of the ergonomic indicator.
• Updated the interactive command menu to include the ergonomic indicator toggle `[e]`.

<2025-01-24>

Enhanced with natural language query commands and new features

• Added a `keyboard-visualizer-query-command-map` to map natural language queries to Emacs commands.
  • Examples: “open file” → `find-file`, “undo” → `undo`, “search” → `isearch-forward`, etc.
• Implemented a new command `keyboard-visualizer-learn-command-by-query`:
  • Allows users to search for commands via fuzzy queries and visualize their keybindings.
• Added `keyboard-visualizer-save-layout`:
  • Saves the current keyboard layout buffer to a file and opens it in a buffer.
• Modified key bindings in the shell menu:
  • Added `[j]` for searching commands via natural language queries.
  • Added `[s]` for saving the keyboard layout.
  • Removed `[l]` and deprecated learning mode toggle.

<2025-01-24>

Enhance keyboard visualizer with learning mode and user interface improvements

• Added a new `keyboard-visualizer-learning-mode` to help users learn keybindings via random command prompts.
• Introduced new commands:
  • `keyboard-visualizer-learning-step` for manual stepping through commands.
  • `keyboard-visualizer-learning-mode-toggle` to enable/disable learning mode.
  • `keyvis-menu` to provide an interactive menu for visualizer-related actions.
• Updated the keyboard layout to reflect more accurate key representations (e.g., renamed “RET” and “SPC”).
• Improved documentation display within the keyboard visualizer buffer.
• Enhanced UI:
  • Used bold styling for section headers (e.g., “Description:”).
  • Adjusted layout buffer display settings for better usability.
• Added customization options:
  • `keyboard-visualizer-learning-exclude-commands` to exclude certain commands from learning mode.
  • `keyboard-visualizer-monospace-face` face includes adjustable height.
• Various refactoring and bug fixes, such as filtering unnecessary characters from key descriptions.

Kanban

Here is a kanban of the features that will be (hopefully) added in due cours, and visually demonstrating their current status via a kanban board

DOING	DONE
Show random functions and their keybindings for learning	Add transient like menu to activate different functionality
Fuzzy search on simple command description for Emacs transition
Save keybindings that are discovered through random learning
Warning when keys in visualized command are not ergonomic
Key visualization to accomodate ergonomic keybinding setup

Installation

You can install keyboard-visualizer from MELPA (if published) or manually:

Manual Installation

1. Download or clone the repository:

   git clone https://github.com/yourusername/keyboard-visualizer.git
       

2. Add the directory to your `load-path` and load the package:

   (add-to-list 'load-path "/path/to/keyboard-visualizer/")
   (require 'keyboard-visualizer)
       

Customization

Custom variable	Description
keyboard-visualizer-query-command-map	Mapping of natural language queries to Emacs commands.
keyboard-visualizer-show-documentation	When non-nil, show command documentation in the keyboard layout buffer.
keyboard-visualizer-layout	Keyboard layout.
keyboard-visualizer-ergonomic-indicator
keyboard-visualizer-insert-mode

Usage

Once installed, you can start using keyboard-visualizer right away. Below are the key commands and features:

Keybinding	Command	Description
`M-x keyboard-visualizer-show-command`	Visualize a specific command’s keybinding.
`C-c b`	Open the main menu for interactive commands.
`C-c b e`	Toggle ergonomic representation.
`C-c b j`	Fuzzy search for commands by description/query.
`C-c b n`	Show a random interactive command’s keybinding.
`C-c b s`	Save the current keyboard layout to a file.
`C-c b b`	Toggle “insert mode” to visualize commands automatically.

Visualize a Command

To visualize a specific command:

M-x keyboard-visualizer-show-command RET some-command RET

Show ergomic issues with key chords

Will highlight the keys that could cause hand fatigue over a period of time.

C-c b e

Search Commands by Query

Use fuzzy searching to look up commands:

C-c b j

For example, type “undo” and choose the corresponding Emacs command.

Enable Insert Mode

Toggle insert mode to see visualizations for your recently executed commands:

C-c b b

Save Layouts

You can save the current layout to a file and revisit it later:

C-c b s

Configuration

You can customize keyboard-visualizer to suit your preferences.

Define a Custom Keyboard Layout

You can define a new keyboard layout using keyboard-visualizer-layout:

(setq keyboard-visualizer-layout
  '(("ESC" "F1" "F2" ...)
    ("`" "1" "2" ...)
    ...))

Natural Language Query Mappings

Add or modify fuzzy search mappings with keyboard-visualizer-query-command-map:

(add-to-list 'keyboard-visualizer-query-command-map
             '("my custom command" . my-custom-command))

Faces and Appearance

Customize the appearance of normal and highlighted keys:

(set-face-attribute 'keyboard-visualizer-key-face nil :box '(:line-width 1))
(set-face-attribute 'keyboard-visualizer-highlight-face nil :box '(:line-width 2 :color "red"))

Roadmap

Add transient like menu to activate different functionality

Show random functions and their keybindings for learning

Fuzzy search on simple command description for Emacs transition

Save keybindings that are discovered through random learning

Warning when keys in visualized command are not ergonomic

Key visualization to accomodate ergonomic keybinding setup

Issues

Contribution

We welcome contributions! Here’s how you can get started:

1. Fork the repository and create a new branch for your changes.
2. Ensure your code adheres to Emacs Lisp conventions.
3. Add tests or documentation for new features.
4. Submit a pull request with a detailed description.

Acknowledgments

Special thanks to the Emacs community for inspiration and support.

Feedback

Have questions, suggestions, or issues? Feel free to open a GitHub issue or reach out to us through the repository.

GitHub Repository: keyboard-visualizer