File: completion-preview.el.html

This library provides the Completion Preview mode. This minor mode displays a completion suggestion for the symbol at point in an overlay after point. Check out the customization group completion-preview for user options that you may want to tweak.

To enable Completion Preview mode, use completion-preview-mode(var)/completion-preview-mode(fun). To accept the completion suggestion, press TAB. If you want to ignore a completion suggestion, just go on editing or moving around the buffer. Completion Preview mode continues to update the suggestion as you type according to the text around point.

Completion Preview mode uses completion-at-point-functions to find relevant completion suggestions, similarly to completion-at-point. You can use completion-at-point with your favorite in-buffer completion interface together with Completion Preview mode, just invoke completion-at-point as usual when you want to see all currently available completions. Another reason to invoke completion-at-point is when you want non-prefix completion, since Completion Preview mode only shows one prefix completion.

The commands completion-preview-next-candidate and completion-preview-prev-candidate allow you to cycle the completion candidate that the preview suggests. These commands don't have a default keybinding, but you can bind them, for example, to M-n and M-p in completion-preview-active-mode-map to have them handy whenever the preview is visible.

When the completion candidate that the preview is showing shares a common prefix with all other candidates, Completion Preview mode underlines that common prefix. If you want to insert the common prefix but with a different suffix than the one the preview is showing, use the command completion-preview-complete. This command inserts just the common prefix and lets you go on typing as usual. If you invoke completion-preview-complete when there is no common prefix (so nothing is underlined in the preview), it displays a list of all matching completion candidates.

You can also insert only the first word of the completion candidate with the command completion-preview-insert-word. With a numeric prefix argument, it inserts that many words instead of just the one. This command is not bound by default, but you may want to bind it to M-f (or remap forward-word) in completion-preview-active-mode-map since it's very much like a forward-word that also moves "into" the completion preview. To define your own command that inserts part of a completion candidate by moving "into" the completion preview, use the function completion-preview-partial-insert. For example, you can define a command that completes exactly one symbol as follows:

  (defun my-completion-preview-insert-symbol ()
    (interactive)
    (completion-preview-partial-insert #'forward-symbol 1))

Similarly to completion-preview-insert-word, the command completion-preview-insert-sexp lets you complete by one or more balanced expressions. The definition of this command is very similar to the simple example above, expect it uses forward-sexp rather than forward-symbol. This command can be useful when you're using Completion Preview mode with long, complex completion candidates, such as entire shell commands from the shell history.

If you set the user option completion-preview-exact-match-only to non-nil, Completion Preview mode only suggests a completion candidate when its the only possible completion for the (partial) symbol at point. The user option completion-preview-commands says which commands should trigger the completion preview. The user option completion-preview-minimum-symbol-length specifies a minimum number of consecutive characters with word or symbol syntax that should appear around point for Emacs to suggest a completion. By default, this option is set to 3, so Emacs suggests a completion if you type "foo", but typing just "fo" doesn't show the preview. If you want the preview to appear also after non-symbol characters, such as punctuation, set completion-preview-minimum-symbol-length to nil. If you do so, you may want to customize the user option completion-preview-idle-delay to have the preview appear only when you pause typing for a short duration rather than after every key. Try setting it to 0.2 seconds and see how that works for you.

By default, Completion Preview mode automatically adapts the background color of the preview overlay to match the background color of the buffer text it's completing. If you prefer a distinct background color for the preview, disable this feature by customizing completion-preview-adapt-background-color to nil.

Sometimes you may want to use Completion Preview mode alongside other Emacs features that place an overlay after point, in a way that could
"compete" with the preview overlay. In such cases, you should give
the completion preview overlay a higher priority, so it properly appears immediately after point, before other overlays. To do that, set the variable completion-preview-overlay-priority. You can set it buffer-locally if you only use competing overlays in some buffers. In particular, an important use case for this variable is enabling Completion Preview mode for M-: and other minibuffers that support completion-at-point. In the minibuffer, some message are displayed using an overlay that may, by default, conflict with the completion preview overlay. Use completion-preview-overlay-priority to resolve this conflict by giving the completion preview overlay a higher priority:

  (add-hook 'eval-expression-minibuffer-setup-hook (lambda () (setq-local completion-preview-overlay-priority 1200) (completion-preview-mode)))

Defined variables (22)

Defined functions (29)

Defined faces (4)