justbur/emacs-which-key

Emacs package that displays available keybindings in popup

emacs-which-key's Issues

TODO: Switch to defcustom for key variables

Like which-key-popup-type

Key description is wrong if the keybinding is changed.

The keybinding description are mapped directly to keybindings so a changed keybinding will show the wrong description. This likely only affects people using Spacemacs or other distributions where keybindings and descriptions are predefined.

SPC SPC is mapped to hs-toggle-hide for me, but the description is ace word. I think that mapping descriptions to function names would solve this problem

Replacing description of a group changes its face

I changd the descriptions of C-x 4, C-x 5 and C-x C-k, which are all prefix keys. As a side effect, which-key now shows them with which-key-command-description-face, instead of which-key-group-description-face.

(which-key/add-key-based-replacements "C-x 4" "other window")
(which-key/add-key-based-replacements "C-x 5" "+other frame")
(add-to-list 'which-key-description-replacement-alist '("kmacro-keymap" . "kbd macros"))

What is which-key?

The introduction section in the README.org does not actually state whatch which-key is. If it told what it did, I could decide if I want to install it or not.

I realize that I can click on the link for guide-key-mode but why?

BUG: which-key window not wide enough

Using these settings:

(setq which-key-popup-type 'side-window
      which-key-side-window-location 'right
      which-key-side-window-max-width 90)

Results in a which-key window that isn't wide enough for the lines in the which-key buffer. The "empty" lines contain spaces, and each such line is actually the continuation of the previous line (Spacemacs makes it look like two different lines, but in the buffer it's a single line).

This is the actual content of the which-key buffer. Notice the cursor is at the bottom left corner of the text:

I will debug this later, but I suspect we may have a slight miscommunication about which-key/show-popup and which-key/popup-max-dimensions. As I understand it, the ACT-POPUP-DIM argument to show-popup specifies the width and the height of the popup window as follows:

• width: the length of each line in which-key buffer, or the length of the longest line in which-key buffer. Length is the same as "number of columns". show-popup should take care of calculating necessary width to accommodate for fringes, margins, scroll bars, etc.
• height: the number of lines in which-key buffer.

Assuming all lines are of the same length, ACT-POPUP-DIM should be equivalent to:

(with-current-buffer which-key-buffer-name
  (save-excursion
    (goto-char (point-max))
    (cons (line-number-at-pos) (current-column))))

Concerning popup-max-dimensions, as I understand it, the function should return the maximal height and width that show-popup can handle. So the following should always be true:

(and (<= (car argument-to-show-popup) (car popup-max-dimensions-return-value))
     (<= (cdr argument-to-show-popup) (car popup-max-dimensions-return-value)))

Please share what meaning you meant those parameters to have, so we can agree on a single meaning and fix this issue.

which-key-faces group

I think it might be time for

(defgroup which-key-faces nil
  "Faces used by which-key."
  :group 'which-key
  :group 'faces)

Timer error when using sudoedit/emacsclient combination

Hello and thank you for this wonderful package! I have my $EDITOR set as emacsclient and the following error pops up when attempting to sudoedit a file:

Error running timer``which-key--update': (wrong-type-argument keymapp nil)

Strangely enough the timer error doesn't appear when editing files not owned by root.
This is on GNU Emacs 24.5.1 (i686-pc-linux-gnu, X toolkit, Xaw scroll bars)

which-key echo-keystrokes question

I'm not 100% about this yet, but it looks as though which-key will sometimes set the value of echo-keystrokes to nil when the mode is activated.

Is this intentional?

TODO: smarter calculation of max dimensions

Currently, which-key/side-window-max-dimensions and which-key/frame-max-dimensions don't take into account the actual layout of the selected frame. When the available size in the frame is smaller than the user-defined max height and width, this could cause bugs.
This is probably more important for the side-window case than the frame case.

BUG: which-key hides too soon

which-key sometimes hides the buffer while I'm reading it (e.g. slow user)

TODO: Fill vertical space first when buffer is vertical

It's filling up horizontally first, which means the buffer is almost always at max width

Show x/y pages only if `n-pages`>1

I was looking into the code on how to not show 1/1 if there is only one page to show.

             (status-left (propertize (format "%s/%s" (1+ i) n-pages)
                                      'face 'font-lock-comment-face))
             (status-top (propertize (format "(%s of %s)" (1+ i) n-pages)
                                     'face 'font-lock-comment-face))

So my suggestion is to set status-left and status-top to "" when n-pages is 1.

BUG: which-key not showing

With vanilla emacs, which-key does not show at all. Works fine with spacemacs, though.

Steps to reproduce:

1. emacs -Q -l path/to/s.el -l path/to/which-key.el
2. M-x which-key-mode
3. C-x
   Expected result: which-key shown in the minibuffer
   Actual result: which-key isn't shown at all

Probably introduced by some recent change.
Tried emacs 24.3, 24.5 and 25, same behavior. On spacemacs I don't experience this bug - which-key works as expected.

SUGGESTION: use a specialized mode-line

The default mode-line isn't very helpful for which-key buffer, but we can change it. We change it by setting the variable mode-line-format in which-key/setup. That variable is buffer-local.

One option is to remove it entirely for which-key buffer:

(setq-local mode-line-format nil)

Using this should cause the side-window case to look the same as the minibuffer case, when which-key-side-window-position is set to bottom.

Another option is to use the mode-line to convey some useful information, such as which-key page number and the typed key sequence. For example, if the user typed "C-x" and which-key is showing the 1st page out of 3, the mode-line could look like this:

This has the advantage of saving space in which-key window, but won't affect the minibuffer case. For the minibuffer case, we could imitate the mode-line by inserting a fake mode-line into which-key buffer's text.

TODO: Switch to window-purpose?

I'm experimenting with dropping popwin and using the lower level display-buffer mechanism on the display-buffer branch

which-key-key-based-description-replacement-alist not working?

Hi,

I have the which-key-key-based-description-replacement-alist variable customized as below:

   (setq which-key-key-based-description-replacement-alist
          '(("C-x 8"   . "unicode")
            ("C-x a"   . "abbrev/expand")
            ("C-x r"   . "rect/reg")
            ("C-x w"   . "hi-lock-map")
            ("C-c /"   . "engine-mode-map")
            ("C-c C-v" . "org-babel")
            ("C-x 8 0" . "ZWS")))

But it is not working. I expected to see "8 → unicode" after pressing "C-x", but instead I see "8 → +prefix".

I have seen this feature to work fine; but it probably broke in the updates that happened in last 2-3 weeks.

I can see the same problem on both emacs 24.5 and the latest emacs build from git.

Unicode correction

@bmag I added which-key-unicode-correction as a variable. Setting it higher than 0 will "lie" about the available width and make the window seem smaller to the layout functions.

When you get a chance could you try your case where the characters were getting cutoff using this variable? Thanks!

Paging not working with minibuffer for evil-leader prefix

It works fine with other prefixes. If you are having this problem, the side-window popups work fine.

To replicate, try

(evil-leader/set-key "<next>" 'which-key-show-next-page)

The buffer flashes then disappears

Is there guide-key/highlight-command-regexp in which-key-mode?

I can use this:

(setq guide-key/highlight-command-regexp
  '(("^helm-" . warning)
        ("rectangle" . link))

link and warning can be color like "red".

to set all the command which contains the specific string the specific color.

Can I do this in which-key-mode?

TODO: require cl-lib directly

(require 'cl-lib)

should replace

(require 'cl-macs)
(require 'cl-extra)

See CL package manual, or more specifically: usage and organization.

Updated all function names in v0.2

After reading more about elisp conventions, I decided against using slashes for function names. I made the required changes, but might have broken some existing configs sorry!

[feature] display the prefix command

I thought it would be cool to have an option to be able to have the prefix command name printed in the minibuffer.

Say I type SPC s which corresponds to prefix command search/symbol which-key displays:

search/symbol 
B -> helm-buffers-smart...   L -> ..
F -> helm-files....          P -> ...

More compact layout

Check out the fill-columns branch for a different layout algorithm that allows for variable column widths and a more compact layout. It also fills vertically first, rather than horizontally. Here's an example (the previous implementation wouldn't have fit all three columns because of the one long function name in the last column).

which-key-side-window-location

I think there should be a 'auto setting in there, which chooses between two axes such as 'right and 'bottom depending on the most available space. Maybe with a list: '(right bottom).

I'm using 'right, but since I'm using a tiling window manager, the frame gets resized often automatically. In a two vertically-split emacs frames, 'bottom would have more space, whereas 'right just doesn't show anything due to the minimum size constraint.

TODO: fix docstrings

Descriptions with wrong faces

As you can see, some of the groups have the wrong face. For example, "rings" (r) and "symbol" (s) are groups, but are displayed like regular commands. They should be blue, not purple.

Full list of groups with wrong faces in the image above:

• C -> colors
• T -> themes
• c -> comments
• g -> version-control
• h -> highlight
• j -> split
• n -> numbers
• r -> rings
• s -> symbol

which-key doesn't list keys after paging

Whether or not we need to list one or more pages for a given prefix like C-x or C-c, once the which-key-show-next-page binding is pressed, which-key does not show the key lists for any key pressed after that.

Below example would demonstrate this issue:

• Open an org-mode buffer. This is because I want to show this issue when C-c needs more than 1 page.
• In that buffer, when you hit C-c, you see the first page.
• Hitting the key set for paging shows the second page perfectly fine.
• As I sort the keys by key order, the C-v key bound to org-babel commands shows up on the second page.
• Now if I hit C-v, which-key does not show the commands bound to C-c C-v map.

If I repeat the above steps except doing the paging, C-c C-v keys are displayed fine by which-key.

[my which-key setup]

Submit to MELPA?

I want to put off working on the paging stuff for the moment, because I'm not sure exactly the best way to do it yet and I want to see what problems people have with the current code.

I'd like to get more people to use this to find the problems and such, so I was thinking of MELPA. But before I do that, I'm trying to think about what issues need to be resolved first. So my list is something like

Do now

• Fix docstrings and add them where needed (#24)
• Use new layout functions for a few days to find bugs
• Merge status-key branch and decide if it should be the default
• Fix any pressing issues with the window size calculations
• Address any MELPA requirements
• elisp conventions

Do later

• Work on paging/scaling functionality for next release

@bmag and @syl20bnr if you think there's something else please let me know. Thanks

TODO: alist for major-mode specific bindings

From: syl20bnr/spacemacs#2109

@syl20bnr I'm not sure what you meant by this feature. Could you explain more when you get a chance?

Use (or include an option for) unicode characters as abbreviation for special characters

Personally, I find the inverted face with abbreviated special keys (tab, return, delete, and space) a little unintuitive. Would it be possible to use unicode symbols instead. For example:

• U+21B9 ↹ (leftwards arrow to bar over rightwards arrow to bar) for tab
• U+23CE ⏎ (return symbol) for return
• U+21E4 ⇤ (leftwards arrow to bar) for delete
• U+2423 ␣ (open box) for space

I am unsure about escape as the corresponding unicode symbol seems not very widespread (U+238B ⎋ broken circle with northwest arrow).

It seems that this should already be possible with key-replacement but I am not sure how it interferes with special key handling.

What do you think?

autoload missing for which-key-setup-side-window-right-bottom

I believe there's an autoload missing for which-key-setup-side-window-right-bottom

emacs-which-key/which-key.el

Line 418 in 156bd61

(defun which-key-setup-side-window-right-bottom ()

Also maybe an option to have which-key appear on the left side could be added.

Is there a way to never show/select an empty *which-key* buffer?

At times, on emacs startup, I am faced with just a blank which-key buffer even when I have set the which-key-popup-type to 'minibuffer. My understanding was that that buffer get created only when you choose the other options like 'side-window.

Can we make that buffer non-selectable so that user couldn't switch to it interactively?

Also that buffer should not show up by itself because it could be confusing at first as to what happened because all we see is a blank which-key buffer without a mode-line.

The first time this happened, I just kept waiting for emacs to look as usual when it starts up, but actually emacs had finished loading and I realized I was waiting on the blank which-key buffer :)

Show keybinding for paging

I was thrilled to see the note (1 of 2) at the bottom that suggest that there is more, however, it took some time to find out how to turn to the next page. Extending this label to e.g. (1 of 2) press <F5> would help new users find their way around immediately.

TODO: Come up with single character substitutes for SPC, TAB, RET, etc

It's annoying that C-SPC takes 5 characters. I don't think I want to change the way the column alignment works, so this makes the key column 5 columns wide anytime this key is bound.

It should be easily recognizable as each of the characters. I looked through some seemingly common unicode characters and found one for space but not the other two.

Was thinking about maybe using S, T, and R, but make them bold and have a different face. We can always provide a translation table. I've already replaced <C-right> for example.

Frame popup problems

It pops up as a smallish window, flickers, and disappears almost immediates. This is using emacs25 on win8. Need to check with emasc24 on linux. I don't have the ability to try osx.

TODO: hide buffer right before command execution

which-key should hide itself after the user chose a command to execute, and before emacs executes that command. This is important for commands that depend or use the current window layout.
For example, magit-status tries to restore the window layout when the user quits the status screen. Currently, that could cause which-key buffer to be shown as well.
I hope there is some suitable hook, maybe look at how guide-key manages it.

Discussion: Sorting

Opening this issue in case other suggestions want to be made for how to sort results (see #42)

Implicit prefix map bindings are not shown

I have these bindings in my emacs setup:

;; Unicode
(require 'iso-transl)
;; Add custom bindings to "C-x 8" map
(dolist (binding '(;; >
                   (">"       . nil) ; First unbind ">" from the map
                   (">="      . [?≥]) ; greater than or equal to
                   (">>"      . [?≫]) ; much greater than
                   (">\""     . [?»]) ; right-pointing double angle quotation mark
                   (">'"      . [?›]) ; single right-pointing angle quotation mark
                   (">h"      . [?☛]) ; black right pointing index
                   ;; <
                   ("<"       . nil) ; First unbind "<" from the map
                   ("<="      . [?≤]) ; less than or equal to
                   ("<<"      . [?≪]) ; much less than
                   ("<\""     . [?«]) ; left-pointing double angle quotation mark
                   ("<'"      . [?‹]) ; single left-pointing angle quotation mark
                   ("<h"      . [?☚]) ; black left pointing index
                   ;; arrows
                   ("<right>" . [?→]) ; rightwards arrow
                   ("<left>"  . [?←]) ; leftwards arrow
                   ("<up>"    . [?↑]) ; upwards arrow
                   ("<down>"  . [?↓]) ; downwards arrow
                   ;; misc
                   ("r"       . [?▯]) ; white vertical rectangle
                   ("R"       . [?▮]) ; black vertical rectangle
                   ("*r"      . [?₹]) ; indian rupee sign
                   ("1/3"     . [?⅓]) ; fraction one third
                   ("0"       . [?​]) ; zero width space
                   ))
  (define-key iso-transl-ctl-x-8-map (kbd (car binding)) (cdr binding)))

When I hit C-x 8, it shows the bindings correctly.

But after that when I hit > it does not show the nested bindings (because > is sort of bound to an implicit prefix map and not an explicit one?).

Zoomed view:

Here are the nested bindings for >:

                   (">"       . nil) ; First unbind ">" from the map
                   (">="      . [?≥]) ; greater than or equal to
                   (">>"      . [?≫]) ; much greater than
                   (">\""     . [?»]) ; right-pointing double angle quotation mark
                   (">'"      . [?›]) ; single right-pointing angle quotation mark
                   (">h"      . [?☛]) ; black right pointing index

I can ignore the misalignment.. it's because I have C-x 8 0 bound to ZERO WIDTH SPACE.

My which-key setup

TODO: Test performance vs guide-key

Need to find someone with guide-key performance issues, like syl20bnr/spacemacs#1263, to test the changes made in which-key for improvement.

which-key should be less aggressive in its polling behavior based on its existing implementation, but it doesn't seem possible to completely remove some of the issues. Ideally, it would be possible to hook into the function that uses echo-keystrokes to modify that echo (instead of running idle timers), but I don't see how to easily do that right now.

Local/global keymaps

I've been trying which-key since it has been in melpa (a few days ;)), mostly for fun to discover which key is mapped to what (as opposed to: from function to keybinding).

One thing that I noticed is that it would make sense to indicate whether the binding is in a local map vs global map, maybe just by using a customizable face which is the same by default.

Not showing after SPC u <num> SPC

As title. It's not strictly an expected behavior given the current state of which-key, but I think it's nice to have the consistency.

Check it out

@syl20bnr I decided to neglect my work today and start on this. I put together a minimal working rewrite of guide-key. It's very basic, but it doesn't use a polling function anymore (just run-with-idle-timer) and it includes some variables for replacement lists. I hard-coded some stuff to just to get started.

I haven't figured out window-purpose yet, so I'm still using popwin, but I think you'll see that the code is pretty simple all things considered.

I'd like your feedback on this (and guidance if possible), since I've never written an emacs package before.

Discussion: Fit more keys (Paging and/or Text Scaling)

Opening this issue to continue the discussion in #14

Print the echo-keystrokes modified message just once?

Hi,

I tried out which-key today and so far it looks great right out of box.

A minor pet-peeve.. I have this minor mode enabled globally and I use desktop-mode.

So each time I restart emacs, as this minor mode gets enabled in all the buffers, I see these in my Messages buffer:

Which-key-mode enabled (note echo-keystrokes changed from 1 to 0.25) [2 times]
Which-key-mode enabled (note echo-keystrokes changed from 1 to 0.25) [8 times]
Buffer has been modified; could not load undo-tree history
Which-key-mode enabled (note echo-keystrokes changed from 1 to 0.25)
Buffer has been modified; could not load undo-tree history
Which-key-mode enabled (note echo-keystrokes changed from 1 to 0.25) [4 times]
Buffer has been modified; could not load undo-tree history
Which-key-mode enabled (note echo-keystrokes changed from 1 to 0.25) [5 times]
Buffer has been modified; could not load undo-tree history
Which-key-mode enabled (note echo-keystrokes changed from 1 to 0.25) [8 times]
org-mode fontification error
Which-key-mode enabled (note echo-keystrokes changed from 1 to 0.25)
Wrote /home/kmodi/.emacs.d/emacs_25_0.desktop.lock
Desktop: 28 buffers restored, 1 failed to restore.
Quit

Can this this prevented from printing out for each buffer?

New Features?

@bmag Is there any feature or change you are thinking about adding? I'm just curious, because I don't have a lot more in mind.

I'm really happy with the minibuffer option, which has been great for me. I want to play with the alists some more and see what makes sense for defaults. I also want to figure out the best way to show more keybindings (I'm thinking of C-x mainly), maybe with #8 and playing with text scaling or paging or something like that. Once this stabilizes, I'll write up some documentation and try to put it on MELPA.

Also, how's the performance for you? Any slowdown on your machine? guide-key was causing problems for people with constant wake-ups, and that was part of the motivation for the rewrite.

BUG: weird behavior with ace-jump-mode and avy

When invoking command ace-jump-mode from package ace-jump-mode, or command avy-goto-char from package avy, I experience weird behavior for the side-window case and the frame case.

side-window case: invoking ace-jump-mode (or avy-goto-char) causes which-key buffer to be shown, but not updated (shows previous content). It doesn't prevent ace-jump-mode from working.

frame case: invoking ace-jump-mode (or avy-goto-char) causes an error message to appear in the minibuffer:

Error running timer `which-key/update': (wrong-type-argument number-or-marker-p nil)

It doesn't prevent ace-jump-mode from working.

No problems with the minibuffer case.

Force sort the bindings

I have noticed that the bindings are not always listed in sorted order. The same prefix map seems to get shuffled around when displayed (either in the same or across different emacs sessions).

For instance, C-c shows me this (you can click on the image for the zoomed view):

Note that the lower case s, t, w appear at the very end. Also bindings for P and W are not along with other upper case bindings.

Discussion: Handling echo-keystrokes

which-key tries to use the echo area (aka the minibuffer) to display useful information, including in the default configuration. If echo-keystrokes is not set appropriately, the keystroke echo can overwrite this information. which-key attempts to control this by turning echo-keystrokes off by default, but echo-keystrokes can easily be reset by the user, as is done in spacemacs.

I'm not sure what the right policy should be here, and I don't like the current way that this works (setting up once and hoping nothing else changes which is wrong in the spacemacs case at least).

I'm also not sure how important echo-keystrokes is to people, as in whether I should defer to that setting or ignore it and turn it off whenever I can. In some sense, which-key is a more informative substitute.

@syl20bnr what do you think is the correct behavior for the spacemacs case? Currently, you set echo-keystrokes to 0.02, and this conflicts with one of the which-key settings when paging is used.

BUG: Error running timer `which-key/update': (range-error "ceiling" 1.0e+INF)

With these settings:

(setq which-key-popup-type 'side-window
      which-key-side-window-location 'right
      which-key-side-window-max-width 20) ; or other small value

The which-key buffer isn't displayed, and I get an error message in the minibuffer:

Error running timer `which-key/update': (range-error "ceiling" 1.0e+INF)

This also happens when setting window location to left, but doesn't happen when using top or bottom and a small max height.

which-key vs. guide-key screen shots

I've done some screen shots to show the difference between which-key and guide-key, so you can use them if you want.

3 horizontally-split windows, which-key, (which-key/setup-side-window-right):

Compare with guide-key, (setq guide-key/popup-window-position 'right):

guide-key shows less shortcuts, and the windows are not split evenly.

2 vertically-split windows, which-key, (which-key/setup-side-window-bottom):

Compare with guide-key, (setq guide-key/popup-window-position 'bottom):

guide-key shows less shortcuts, and the windows are not split evenly. You can see that which-key doesn't fully show "x" and "z" on the far right, but it's still much better than guide-key.