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”.
guide-key can highlight commands which match a specified regular expression. Key bindings following “C-x r” are rectangle family and register family. If you want to highlight only rectangle family 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 both rectangle family and register family, set an adequate regular expression like this.
(setq guide-key/highlight-command-regexp "rectangle\\|register")
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.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.
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”.
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;
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
- Version 1.2.3
- 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)
- Version 1.2.2
- Add a Japanese README.
- Add a documentation about key-chord hack.
- Version 1.2.1
- Support for mode specific key sequences in
guide-key/guide-key-sequence. (Thanks to @Fuco1)
- Support for mode specific key sequences in
- Version 1.2.0
- 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)
- Version 1.1.1
- Suppress an annoying message, “No following key”.
- Version 1.1.0
- 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)
- Add a functionality to check an input key sequence recursively. This enables to avoid adding many prefixes to
- Version 1.0.1
- Change to save and restore a last configuration of popwin
- Version 1.0.0
- First release version
- Adjust names of functions and variables
- Add some documentations
- Version 0.1.2
- Enable to guide key-chord bindings.
- Version 0.1.1
guide-key-modeglobal minor mode.
- Version 0.1.0
- Initial version.