Icicles - Completions Display

Previous: Icicles - Ido and IswitchBIciclesIciclesIndexNext: Icicles - Icompletion

Display of Buffer *Completions*

Icicles enhances the ‘*Completions*’ display in several ways. The following features are available whenever buffer ‘*Completions*’ is displayed.

Cycling Candidates

In buffer ‘*Completions*’, you can use the arrow keys (‘down’, ‘up’, ‘right’, ‘left’) to navigate among the candidate completions. The current candidate (under the cursor) is highlighted.

Current Candidate

When you cycle completion candidates in the minibuffer:

*Completions* Mode Line

The mode line of buffer ‘*Completions*’ shows information about the current completion state, in order from the left:

Here’s a screenshot showing:


Switch to *Completions* and Back to Minibuffer

You can use ‘C-insert’ to move back and forth between the minibuffer and ‘*Completions*’. In each direction, the current candidate is tracked in the destination buffer. For example, if the candidate in the minibuffer is ‘foobar’, after you hit ‘C-insert’ the cursor is on ‘foobar’ in ‘*Completions*’. In the other direction, if the cursor is on ‘foobar’ in ‘*Completions*’, after you hit ‘C-insert’ the current input in the minibuffer is ‘foobar’.

*Completions* Display as Apropos Icompletion

‘*Completions*’ can also serve as apropos icompletion help – see Icicles - Icompletion.

Choose Multiple Candidates

You can choose multiple candidates during completion, by clicking them with ‘mouse-2’ while holding the Control key pressed. See Icicles - Multi-Commands. You can choose a set of candidates in additional ways, and then act on all of them – see Icicles - Candidate Sets).

*Completions* Window Resized to Fit

Icicles dynamically resizes the ‘*Completions*’ window vertically, to fit the current set of completion candidates. The window is not resized, however, if buffer ‘*Completions*’ appears in its own frame. (It is also not resized in Emacs releases prior to 21.) You can control this automatic resizing generally or on a per-command basis:

For example, you can use the following code to set the maximum ‘*Completions*’ height for command ‘foo’ to 100 and turn off per-command control of the height for command ‘bar’. If you use such code, evaluate it after you load Icicles.

    (put 'foo 'icicle-Completions-window-max-height 100)
    (put 'bar 'icicle-Completions-window-max-height nil)

Smaller Text in *Completions*

Starting with Emacs 23, if you also use DoReMi library doremi-frm.el, then you can use ‘C-x -’ in the minibuffer to zoom the ‘*Completions*’ buffer text, shrinking or enlarging it incrementally using ‘-’ or `=’, respectively (`=’ is typically on the same keyboard key as `+’, but it needs no Shift).

Also starting with Emacs 23 (whether or not you use doremi-frm.el), you can specify an initial text-scale amount for the ‘*Completions*’ text, by customizing option `icicle-Completions-text-scale-decrease’. This controls the default appearance. (The option has no effect for terminal Emacs. It is used only for graphic display (GUI Emacs).

You typically use these features to make the ‘*Completions*’ text a bit smaller and thus save screen real estate – show more candidates in less space. However, Emacs 23 text-scaling does not by itself let you recuperate the saved window space – it shrinks the text, but it does not shrink the window accordingly. For that, you also need library face-remap+.el and its option ‘text-scale-resize-window’, which lets you resize the window or not, horizontally, vertically, or in both directions.

(For example, you might set ‘split-width-threshold’ to a small number, so ‘*Completions*’ appears on the side rather than above or below other windows, and in that case you might want to resize it only horizontally.)

If you use library oneonone.el with a standalone ‘*Completions*’ frame, then see option ‘1on1-completions-frame-zoom-font-difference’.

`*Completions*' Frame Uses Same Font as Invoking Window

If you use a dedicated frame for buffer ‘*Completions*’ then Icicles gives it the same font as the window that was selected when ‘*Completions*’ was displayed. This means, for instance, that if that original window has a font tailored to a specific locale or Unicode character set then ‘*Completions*’ will use that same font.

Change *Completions* Spacing and Columns On the Fly

Icicles varies the number of columns used to display completion candidates, for a better fit. You can tweak this with options `icicle-candidate-width-factor’ and `icicle-inter-candidates-min-spaces’.

If you use DoReMi (library doremi.el), then you can modify these options incrementally during completion, seeing the effect as they change. Use ‘C-x w’ or `C-x |’ from the minibuffer, then use the arrow keys or the mouse wheel to increment and decrement the current value. WYSIWYG.

Why is this important enough to merit changing it dynamically, instead of just customizing the options once and for all? Because different sets of candidates have different candidate lengths and distributions of those lengths. Play with it a bit and you will see. One size does not fit all in an ideal way.

(You can use option `icicle-Completions-max-columns’ to prevent Icicles from automatically calculating the number of columns to display, but I do not recommend this.)

Hide Common-Match Portion of Candidates

You can use `C-x .’ (‘icicle-toggle-hiding-common-match’) in the minibuffer at any time during completion to toggle hiding of the matched portions of the candidates in ‘*Completions*’. This portion is replaced by ellipsis, `...’. (In Emacs 20, it is replaced by nothing.)

This can be useful when you do not care about the text that matches or when that text is particularly long. For example, if you use ‘icicle-find-file-absolute’ (‘C-u C-x C-f’) and the completion candidates are absolute file names that share a common directory, it can be convenient to hide the directory portion that is common to all candidates.

Show Thumbnails for Image Files

Starting with Emacs 22, if option `icicle-image-files-in-Completions’ is non-‘nil’ (it is ‘t’ by default) then thumbnail images are shown in ‘*Completions*’ for candidates that are either (relative or absolute) names of image files or names of image-file bookmarks (see Bookmark+). If the option value is ‘image-only’, then only the thumbnail images are shown. If it is otherwise non-‘nil’ then the file names are also shown. You can cycle the option value using ‘C-x t’ in the minibuffer at any time during completion.

Show Thumnail Image Tooltips on Mouseover

Starting with Emacs 22, if option `icicle-image-preview-in-tooltip’ is non-‘nil’ and ‘tooltip-mode’ is on, then passing the mouse over an image-file candidate in ‘*Completions*’ can pop up a tooltip showing a preview of the image. The possible values are ‘nil’ (do not show a tooltip preview), ‘full’ (show a full-size tooltip preview), and a positive integer (show a thumbnail tooltip preview of that size).

However, thumbnail tooltip previews are not shown if thumbnails are already shown in ‘*Completions*’, that is, if option `icicle-image-files-in-Completions’ is non-‘nil’ and ‘icicle-image-preview-in-tooltip’ is not ‘full’.

Scroll *Completions*

You can scroll ‘*Completions*’ down using ‘C-v’, and up using ‘M-v’. You can use ‘C-u’ at any time to reverse the scroll directions. In Emacs 22 or later, you can also use the mouse wheel to scroll ‘*Completions*’.

Optional Vertical Layout

You can lay completion candidates out vertically, if you like, instead of horizontally (the default). To do that, customize option `icicle-completions-format’ to have the value ‘vertical’.

You can toggle the completions layout between horizontal and vertical at any time during completion, using `C-M-^’.

Starting with Emacs 23.2, this is also possible in vanilla Emacs, and the vanilla option for this is ‘completions-format’. The default value of ‘icicle-completions-format’ is the value of ‘completions-format’, so if you prefer you can simply use the vanilla Emacs option. Vertical layout works in Icicles for all Emacs versions, starting with Emacs 20.

Unlike the case for vanilla Emacs, in Icicles the arrow keys in buffer ‘*Completions*’ correctly reflect the candidate order (e.g. as currently sorted). This also means that candidate cycling acts properly for a vertical layout.

Note: For visual clarity, when multi-line candidates are used (and this includes multi-line multi-completions) the candidates are displayed in a single column. When this is the case, the completions format (horizontal or vertical) makes no difference – the effect is the same. (Icicles also inserts an empty line after each multi-line candidate, for readability.) See also Customization and General Tips.

Proxy Candidates

In some cases, Icicles adds one or more additional, proxy completion candidates. These are placeholders for real candidates. If you choose a proxy candidate, then the real candidate that it refers to is used. Typical proxy candidates include a reference to a name under the cursor, a reference to whatever you then click ‘mouse-2’ on, and a reference to a name that is the value of a variable.

The inclusion of proxy candidates is controlled by user option `icicle-add-proxy-candidates-flag’. You can toggle this inclusion at any time during completion, using `C-M-_’. For performance reasons, you must re-invoke some commands after toggling the flag on, to make the proxy candidates available. Examples:

See Also: Variable Value as Input for information about using `C-M-{’ in the minibuffer to retrieve the value of any variable as minibuffer input.

Proxy Gotcha #1: Your minibuffer input is matched against proxy candidates, as usual. If ‘insert-default-directory’ is non-‘nil’ when you use ‘C-x d’ (‘icicle-dired’), then the default directory is inserted as part of your input. If you use ‘TAB’ for completion then you will first need to use ‘M-k’ to remove the inserted directory, as it will not match any of the proxy candidates.

Proxy Gotcha #2: If you enter text that matches a proxy candidate then the value of that proxy is taken as the real input – that’s the whole point of proxy candidates. But suppose, in Info, you want to (non-incrementally) search for the text ‘ftp-program’, which is the name of a variable? If you type ‘s ftp-program RET’ then the value of that variable (typically ‘ftp’) is taken as the text to search for, instead of the literal text ‘ftp-program’. To take care of this, use `C-M-_’ in the minibuffer to turn off including proxy candidates.

Contextual Popup Menu (`C-mouse-3')

Clicking ‘C-mouse-3’ on a candidate in ‘*Completions*’ pops up a contextual menu for acting on completion candidates. You can customize the menu using option `icicle-Completions-mouse-3-menu-entries’. By default, the menu has the following submenus:

The popup menu is contextual. In particular, the available items can change depending on whether you use a prefix argument (‘C-u C-mouse-3’) and whether you have selected candidates using the region (e.g. mouse drag). The menu also provides a good reminder of key bindings available during completion.

Screenshots of the popup menu and its submenus are here: Completion menu.

There are lots more Icicles features that enhance the display and behavior of ‘*Completions*’ in some way. Read on…

Here is a screenshot of buffer ‘*Completions*’ (shown in its own frame):


(Mode-line help is not shown in this screenshot, which is older than that help feature.)

See Also:

Previous: Icicles - Ido and IswitchBIciclesIciclesIndexNext: Icicles - Icompletion

DrewsElispLibraries referenced here: Lisp:icicles.el

CategoryCommands CategoryCompletion CategoryRegexp CategoryDocumentation CategoryHelp CategoryProgrammerUtils CategoryCode