guide-key.el

Overview

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 describe-key and describe-bindings.

Installation

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.

If you don’t have package.el, please download m2ym/popwin-el and kai2nenobu/guide-key directly, and then put them in your load-path.

Basic usage

Just add your favorite prefix keys to guide-key/guide-key-sequence as below.

(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”.

If guide-key/guide-key-sequence is 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 rectangle family, register family and bookmark 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 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 guide-key/idle-delay:

(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.

Advanced Usage

Check key sequence recursively

It is annoying to add many prefixes to guide-key/guide-key-sequence. 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 “C-x”.

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-guide-key-sequence, guide-key/add-local-highlight-command-regexp and the hook of that mode.

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 sequences without 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 @”.

Work with key-chord

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 @"))

If 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; this-command-keys and this-command-keys-vector.

Other functions and variables

Here are some functions and variables which control guide-key.

• (guide-key-mode ARG): guide-key-mode is implemented as a minor mode. Executing “M-x guide-key-mode” toggles whether guide-key is enabled or not. Because guide-key-mode is a global minor mode, guide-key-mode is 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 right, bottom, left, top. The default value is right.
• 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.

Known issues

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.

TODOs

• [ ] 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

ChangeLog

Version 1.2.5

• Enable setting guide-key/guide-key-sequence to t so 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)

Version 1.2.4

• Change the format of tag name to suit MELPA Stable rule (ver1.x.y -> v1.x.y)
• 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)

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)

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)

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

• Make guide-key-mode global minor mode.

Version 0.1.0

• Initial version.