guide-key.el displays the available key bindings automatically and dynamically. guide-key aims to be an alternative of one-key.el.
Here are some features of this library.
- guide-key automatically pops up the keys following your favorite prefixes. Moreover, even if you change key bindings, guide-key follows the change dynamically.
- guide-key can highlight particular commands. This makes it easy to find a command you are looking for, and to learn its key binding.
- guide-key doesn’t overwrite existing commands and key bindings, so there
is no interference with
I added guide-key to MELPA. You can install guide-key with package.el:
Because guide-key depends on popwin.el, popwin.el is also installed.
Just add your favorite prefix keys to
(require 'guide-key) (setq guide-key/guide-key-sequence '("C-x r" "C-x 4")) (guide-key-mode 1) ; Enable guide-key-mode
When you press these prefix keys, key bindings are automatically popped up after a short delay (1 second by default). This is a screenshot when you press “C-x r”.
t, any prefixes will pop up bindings.
guide-key can highlight commands which match a specified regular expression.
Key bindings following “C-x r” are
register family and
bookmark family. If you want to highlight only
commands, put this setting in your init.el.
(setq guide-key/highlight-command-regexp "rectangle")
This feature makes it easy to find commands and learn their key bindings. If you want to highlight all families, you can specify multiple regular expressions and faces as below.
(setq guide-key/highlight-command-regexp '("rectangle" ("register" . font-lock-type-face) ("bookmark" . "hot pink")))
If an element of
guide-key/highlight-command-regexp is a cons cell, its car
means a regular expression to highlight, and its cdr means a face or a color
name put on command names.
Moreover, prefix commands are automatically highlighted.
Depending on your level of emacs experience, you may want a shorter or
longer delay between pressing a key and the appearance of the guide
buffer. This can be controlled by setting
(setq guide-key/idle-delay 0.1)
The guide buffer is displayed only when you pause between keystrokes for longer than this delay, so it will keep out of your way when you are typing key sequences that you already know well.
I’ve confirmed that guide-key works well in these environments.
- Emacs 24.4, Ubuntu 14.04 or Windows 8.1 64bit
- Emacs 24.2, Ubuntu 12.04 or Windows 7 64bit
- Emacs 23.3, Ubuntu 12.04 or Windows 7 64bit
- Emacs 22.3, Windows 7 64bit
- Emacs 24.3.1, OS X 10.9
If popwin works, I think guide-key will work as well. You can use guide-key with Emacs working in terminal.
Check key sequence recursively
It is annoying to add many prefixes to
guide-key/recursive-key-sequence-flag releases you from this problem. If
guide-key/recursive-key-sequence-flag is non-nil, guide-key checks an input
key sequence recursively. That is, if “C-x 8 ^” is an input key sequence,
guide-key checks whether
guide-key/guide-key-sequence includes “C-x 8” and
For example, if you configure as below,
(setq guide-key/guide-key-sequence '("C-x")) (setq guide-key/recursive-key-sequence-flag t)
the guide buffer is popped up when you input “C-x r”, “C-x 8” and any other prefixes following “C-x”.
Add settings in a particular mode
You can add extra settings in a particular mode. Please use
guide-key/add-local-highlight-command-regexp and the hook of
This code is an example for org-mode.
(defun guide-key/my-hook-function-for-org-mode () (guide-key/add-local-guide-key-sequence "C-c") (guide-key/add-local-guide-key-sequence "C-c C-x") (guide-key/add-local-highlight-command-regexp "org-")) (add-hook 'org-mode-hook 'guide-key/my-hook-function-for-org-mode)
If you execute
org-set-property by pressing “C-c C-x p” in org-mode buffer,
Emacs behaves as below.
In respect of
guide-key/guide-key-sequence, you can add mode specific key
guide-key/add-local-guide-key-sequence. For example,
configure as below.
(setq guide-key/guide-key-sequence '("C-x r" "C-x 4" (org-mode "C-c C-x") (outline-minor-mode "C-c @")))
In this case, if the current major mode is
org-mode, guide key bindings
following “C-c C-x”. If
outline-minor-mode is enabled, guide key bindings
following “C-c @”.
guide-key can work with key-chord.el. If you want to guide key bindings
following key chord, you need to execute
guide-key/key-chord-hack-on. Then, add your favorite key chord to
guide-key/guide-key-sequence as below.
(key-chord-define global-map "@4" 'ctl-x-4-prefix) (guide-key/key-chord-hack-on) (setq guide-key/guide-key-sequence '("<key-chord> @ 4" "<key-chord> 4 @"))
guide-key/recursive-key-sequence-flag is non-nil, more simple.
(guide-key/key-chord-hack-on) (setq guide-key/recursive-key-sequence-flag t) (setq guide-key/guide-key-sequence '("<key-chord>"))
In this case, key bindings are popped up when you type any of key chords.
This hack may be dangerous because it advices primitive functions;
Other functions and variables
Here are some functions and variables which control guide-key.
guide-key-modeis implemented as a minor mode. Executing “M-x
guide-key-mode” toggles whether guide-key is enabled or not. Because
guide-key-modeis a global minor mode,
guide-key-modeis enabled in all buffers or disabled in all buffers.
guide-key/popup-window-position: This variable controls where a guide-key buffer is popped up. A value of this variable is one of
top. The default value is
guide-key/polling-time: This variable controls a polling time. The default value is 0.1 (in seconds).
guide-key/idle-delay: This variable controls the delay between starting a key sequence and popping up the guide buffer. The default value is 1.0 (in seconds), which means that guide-key will keep out of your way unless you hesitate in the middle of a key sequence . Set this to 0.0 to revert to the old default behavior.
guide-key/text-scale-amount: This variable controls the size of text in guide buffer. The default value is 0 (it means default size in Emacs). If you want to enlarge text, set positive number. Otherwise, set negative number.
Here are some issues and drawbacks.
- Because guide-key tries to pop up all key bindings, a size of popup window tends to be big. If the popup window is bigger than the current frame, guide-key cannot pop up normally. I recommend you not to add a prefix which has many key bindings like “C-x”.
- A popup window sometimes closes immediately. It tends to happen right after a window controlled by popwin.el closes. In that case, please retry after you type “C-g” a couple of times.
- one-key can display a short description instead of its command name. This is an advantage to creating template manually. In contrast, because guide-key extracts key bindings dynamically, guide-key can display nothing except a command name.
- [ ] confine a length of command name
- [ ] confine the number of items to guide
- [ ] a feature to exclude or include guide by command name
- [X] enrichment of guide buffer
- [ ] select more user-friendly colors
- [X] automatically guide all following keys
- [X] pop up guide buffer at top or bottom
- [X] prefix argument processing
- [X] define global minor mode
- Enable setting
tso that any key sequence will pop up bindings (#22)
- Enable to guide key sequences with universal argument (#6)
- Add a feature to specify a direct color name (#25)
- Change the format of tag name to suit MELPA Stable rule (
- Add some tests and work with Travis CI and Coveralls
- Fix a regression bug about a local highlight face (#16)
- Add a feature to specify multiple highlight faces according to each regular expression (#14)
- Modify a link of one-key to more explanatory page
- Allow key sequences with regexp special characters. (Thanks to @mrc)
- Allow popup function to be called directly. (Thanks to @mlf176f2)
- Add a Japanese README.
- Add a documentation about key-chord hack.
- Support for mode specific key sequences in
guide-key/guide-key-sequence. (Thanks to @Fuco1)
- Add a feature to scale the text size in the guide buffer.
- Add a feature to popup the guide buffer with delay. (Thanks to @deprecated)
- Fix up README. (Thanks to @haxney)
- Suppress an annoying message, “No following key”.
- Add a functionality to check an input key sequence recursively. This
enables to avoid adding many prefixes to
guide-key/guide-key-sequence. (Thanks @kui)
- Change to save and restore a last configuration of popwin
- First release version
- Adjust names of functions and variables
- Add some documentations
- Enable to guide key-chord bindings.
guide-key-modeglobal minor mode.
- Initial version.