guide-key

guide-key copied to clipboard

This package is not maintained actively. [[https://github.com/justbur/emacs-which-key][which-key]] is a better altenative.

• guide-key.el [[https://travis-ci.org/kai2nenobu/guide-key][https://api.travis-ci.org/kai2nenobu/guide-key.png]] [[https://coveralls.io/r/kai2nenobu/guide-key][https://coveralls.io/repos/kai2nenobu/guide-key/badge.png?branch=master]] [[http://melpa.org/#/guide-key][http://melpa.org/packages/guide-key-badge.svg]] [[http://stable.melpa.org/#/guide-key][http://stable.melpa.org/packages/guide-key-badge.svg]] ** Overview guide-key.el displays the available key bindings automatically and dynamically. guide-key aims to be an alternative of [[http://www.emacswiki.org/emacs/OneKey][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 [[http://melpa.milkbox.net/][MELPA]]. You can install guide-key with package.el:

[[img/guide-key-package-install.png]]

Because guide-key depends on [[https://github.com/m2ym/popwin-el][popwin.el]], popwin.el is also installed.

If you don't have package.el, please download [[https://github.com/m2ym/popwin-el][m2ym/popwin-el]] and [[https://github.com/kai2nenobu/guide-key][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. #+BEGIN_SRC emacs-lisp (require 'guide-key) (setq guide-key/guide-key-sequence '("C-x r" "C-x 4")) (guide-key-mode 1) ; Enable guide-key-mode #+END_SRC 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".

[[img/guide-key-example.png]]

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. #+BEGIN_SRC emacs-lisp (setq guide-key/highlight-command-regexp "rectangle") #+END_SRC

[[img/guide-key-example2.png]]

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.

#+BEGIN_SRC emacs-lisp (setq guide-key/highlight-command-regexp '("rectangle" ("register" . font-lock-type-face) ("bookmark" . "hot pink"))) #+END_SRC

[[img/guide-key-multiple-highlight.png]]

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=: #+BEGIN_SRC emacs-lisp (setq guide-key/idle-delay 0.1) #+END_SRC 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, #+BEGIN_SRC emacs-lisp (setq guide-key/guide-key-sequence '("C-x")) (setq guide-key/recursive-key-sequence-flag t) #+END_SRC 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. #+BEGIN_SRC emacs-lisp (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) #+END_SRC If you execute =org-set-property= by pressing "C-c C-x p" in org-mode buffer, Emacs behaves as below.

[[img/guide-key-example-org-anime.gif]]

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. #+BEGIN_SRC emacs-lisp (setq guide-key/guide-key-sequence '("C-x r" "C-x 4" (org-mode "C-c C-x") (outline-minor-mode "C-c @"))) #+END_SRC 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 [[http://www.emacswiki.org/emacs/KeyChord][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. #+BEGIN_SRC emacs-lisp (key-chord-define global-map "@4" 'ctl-x-4-prefix)

(guide-key/key-chord-hack-on) (setq guide-key/guide-key-sequence '(" @ 4" " 4 @")) #+END_SRC

If =guide-key/recursive-key-sequence-flag= is non-nil, more simple. #+BEGIN_SRC emacs-lisp (guide-key/key-chord-hack-on) (setq guide-key/recursive-key-sequence-flag t) (setq guide-key/guide-key-sequence '("")) #+END_SRC 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 ([[https://github.com/kai2nenobu/guide-key/pull/22][#22]])
• Enable to guide key sequences with universal argument ([[https://github.com/kai2nenobu/guide-key/issues/6][#6]])
• Add a feature to specify a direct color name ([[https://github.com/kai2nenobu/guide-key/issues/25][#25]]) *** Version 1.2.4
• Change the format of tag name to suit [[http://stable.melpa.org/#/][MELPA Stable]] rule (=ver1.x.y= -> =v1.x.y=)
• Add some tests and work with [[https://travis-ci.org/kai2nenobu/guide-key][Travis CI]] and [[https://coveralls.io/r/kai2nenobu/guide-key][Coveralls]]
• Fix a regression bug about a local highlight face ([[https://github.com/kai2nenobu/guide-key/pull/16][#16]])
• Add a feature to specify multiple highlight faces according to each regular expression ([[https://github.com/kai2nenobu/guide-key/issues/14][#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.