| img | ||
| .gitignore | ||
| LICENSE.md | ||
| README.org | ||
| which-key.el | ||
which-key
Rewrite of guide-key-mode for emacs.
Table of Contents TOC@4
Install
Add which-key.el to your load-path and require. Something like
(add-to-list 'load-path "path/to/which-key.el")
(require 'which-key)
(which-key-mode)There are 3 choices of default configs for you to try (then customize to your liking). The main choice is where you want the which-key buffer to display. Screenshots of the default options are shown in the next sections.
In each case, we show as many key bindings as we can fit in the buffer within the constraints. The constraints are determined by several factors, including your emacs settings, the size of the current emacs frame, and the which-key settings (which are configurable but not well documented at the moment).
By default which-key makes substitutions for text all with the aim of saving
space. The most noticeable are the "special keys" like SPC, TAB, RET, etc. This
can be turned off, but the default is to truncate these keys to one character
and display them using :inverse-video (flips foreground and background
colors). You can see the effect in the screenshots.
There are other substitution abilities included, which are quite flexible (ability to use regexp for example). This makes which-key very customizable. This functionality is targeting spacemacs.
Minibuffer Option
Take over the minibuffer. Setup by default, but you can also use
(which-key/setup-minibuffer)
Note the maximum height of the minibuffer is controlled through the built-in
variable max-mini-window-height.
Side Window Right Option
Popup side window on right. For defaults use
(which-key/setup-side-window-right)
Side Window Bottom Option
Popup side window on bottom. For defaults use
(which-key/setup-side-window-bottom)
Status/Goals
Stability
- It's very much a work in progress, so expect weird things to happen from time to time. That being said, the default configuration works well for me.
Completed Goals
- Use idle timers to trigger window popup instead of guide-key's constant polling.
- Remove popwin as a "hard" dependency, prefering built-in display commands where possible.
- Add support for replacement lists to modify key descriptions on the fly.
Currently you can replace in the key or description field using regexp, and
using a key sequence (like
C-x 1) to fully replace the description (the latter can target major modes, too).
Incomplete and Planned
-
Come up with creative ways to fit more keys in buffer while still maintaining nice alignment and formatting. Such as
- Automatic text scaling
- Paging functionality
Special Features
Several Popup Types
There are three different popup types that which-key can use to display the
available keys. The variable which-key-popup-type decides which one is used.
minibuffer
(setq which-key-popup-type 'minibuffer)Show keys in the minibuffer.
side window
(setq which-key-popup-type 'side-window)Show keys in a side window. This popup type has further options:
;; location of which-key window. valid values: top, bottom, left, right
(setq which-key-side-window-location 'bottom)
;; max width of which-key window, when displayed at left or right.
;; valid values: number of columns (integer), or percentage out of current
;; frame's width (float larger than 0 and smaller than 1)
(setq which-key-side-window-max-width 0.33)
;; max height of which-key window, when displayed at top or bottom.
;; valid values: number of lines (integer), or percentage out of current
;; frame's height (float larger than 0 and smaller than 1)
(setq which-key-side-window-max-height 0.25)frame
(setq which-key-popup-type 'frame)Show keys in a popup frame. This popup won't work very well in a terminal, where only one frame can be shown at any given moment. This popup type has further options:
;; max width of which-key frame: number of columns (an integer)
(setq which-key-frame-max-width 60)
;; max height of which-key frame: number of lines (an integer)
(setq which-key-frame-max-height 20)Custom String Replacement
TODO…
Nice Display with Split Frame
Unlike guide-key, which-key looks good even if the frame is split into several windows.
