: [[image:iciclesimage]]

|| *Previous:*  [[Icicles - Ido and IswitchB]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Icompletion]] ||

----

== Display of Buffer *Completions* ==

'''Icicles''' enhances the `*Completions*'
display in several ways.  The following features are available whenever [[buffer]]
`*Completions*' is displayed.






[:CyclingCandidates]
=== 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.





[:CurrentCandidate]
=== Current Candidate ===

When you cycle completion candidates in the [[minibuffer]]:
* The current candidate is highlighted in `*Completions*'.
* Help on the current candidate (typically the first line of a [[doc string]]) is displayed in the [[mode line]], provided [[user option]] '''`<tt>[[Icicles - Customization and General Tips#icicle-help-in-mode-line-delay|icicle-help-in-mode-line-delay]]</tt>'''' is greater than zero.






[:NumberOfCandidatesIndicator]
[:CompletionsModeLine]

=== *Completions* Mode Line ===

The [[mode line]] of buffer `*Completions*' shows information about
the current completion state, in order from the left:

* The minor-mode lighter for Icicles, `Icy'.  This includes one
or more of these suffixes when appropriate:

** '''`##+##''''   for a [[multi-command]]
** '''`##||##''''  when candidates are [[multi-completion]]s
** '''`##...##'''' if the set of candidates in `*Completions' is truncated

* The total number of completion candidates -- e.g. `##567 candidates##'.
If the set of candidates in `*Completions*' is currently truncated (because of
option '''`<tt>[[Icicles - Customization and General Tips#icicle-max-candidates|icicle-max-candidates]]</tt>''''),
then the total number of candidates before truncation is also
shown -- e.g. `##149/567 shown##'.

* The current completion method: ##vanilla##, ##basic##, ##fuzzy##, ##swank (fuzzy symbol)##, ##apropos##, ##scatter##, ##SPC scatter##, ##Levenshtein##, ##Levenshtein strict##, or ##Jaro-Winkler##.  (However, this
indication is meaningless for a few Icicles multi-completion
commands, such as `icicle-buffer' and `icicle-file'.)  See [[Icicles - Completion Methods and Styles]] and [[user option]]s `<tt>[[Icicles - Customization and General Tips#icicle-TAB-completion-methods|icicle-TAB-completion-methods]]</tt>' and `<tt>[[Icicles - Customization and General Tips#icicle-S-TAB-completion-methods-alist|icicle-S-TAB-completion-methods-alist]]</tt>'.

[:SortOrder]
* The current sort order, and whether it is reversed.  See [[Icicles - Sorting Candidates]].

Here's a screenshot showing:

* Multi-completion (`##||##') with a multi-command (`##+##'): `##Icy##'''##+||##''''
* 18 candidates match the minibuffer content (not shown --`##i.*c##' in this case)
* Apropos completion
* Sorting by buffer size

[[image:Icicles-Completion-mode-line]]










[:SwitchingBetweenCompletionsAndMinibuffer]
=== 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'.






[:CompletionsDisplayAsAproposIcompletion]
=== *Completions* Display as Apropos Icompletion ===

`*Completions*' can also serve as apropos icompletion help -- see [[Icicles - Icompletion]].





[:ChooseMultipleCandidates]
=== 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]]).






[:AutoResizeOfCompletionsWindow]
=== *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:


[:icicle-Completions-window-max-height]
* User option '''`<tt>[[Icicles - Customization and General Tips#icicle-Completions-window-max-height|icicle-Completions-window-max-height]]</tt>'''' is the
maximum number of [[line]]s to show in the `*Completions*' window.

* You can override the behavior of option
`icicle-Completions-window-max-height' for any given command,
by setting ''property'' `icicle-Completions-window-max-height' on
the command [[symbol]] to a different maximum window height
value.  This property value is predefined for commands, such
as `icicle-buffer' and `icicle-file', for which you do not
need to see much of the current buffer contents during completion.  A large
value is used for these commands, so that nearly all of the
frame real estate is given to the `*Completions*' window.

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)








[:icicle-Completions-text-scale-decrease]
[:text-scale-resize-window']
[:1on1-completions-frame-zoom-font-difference]
[:TextSizeInCompletions]
=== Smaller Text in *Completions* ===

Starting with Emacs 23, if you also use '''DoReMi''' library <tt>[[doremi-frm.el]]</tt>, 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
'''`<tt>[[Icicles - Customization and General Tips#icicle-Completions-text-scale-decrease|icicle-Completions-text-scale-decrease]]</tt>''''.  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 <tt>[[face-remap+.el]]</tt> 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 <tt>[[oneonone.el]]</tt> with a standalone
`*Completions*' [[frame]], then see option
'''`1on1-completions-frame-zoom-font-difference''''.








[:SameFont]
=== `*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.









[:icicle-candidate-width-factor]
[:icicle-inter-candidates-min-spaces]
[:ChangeCompletionsSpacingOnTheFly]
=== 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 '''`<tt>[[Icicles - Customization and General Tips#icicle-candidate-width-factor|icicle-candidate-width-factor]]</tt>'''' and '''`<tt>[[Icicles - Customization and General Tips#icicle-inter-candidates-min-spaces|icicle-inter-candidates-min-spaces]]</tt>''''.

If you use '''DoReMi''' (library <tt>[[doremi.el]]</tt>), 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.

[:icicle-Completions-max-columns]
(You can use option '''`<tt>[[Icicles - Customization and General Tips#icicle-Completions-max-columns|icicle-Completions-max-columns]]</tt>'''' to prevent
'''Icicles''' from automatically calculating the number of columns to
display, but I do not recommend this.)









[:HideCommonMatchPortion]
=== 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.








[:ThumbnailImages]
=== Show Thumbnails for Image Files ===

Starting with Emacs 22, if option '''`<tt>[[Icicles - Customization and General Tips#icicle-image-files-in-Completions|icicle-image-files-in-Completions]]</tt>'''' 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.






[:ThumbnailImageTooltips]
=== Show Thumnail Image Tooltips on Mouseover ===

Starting with Emacs 22, if option
'''`<tt>[[Icicles - Customization and General Tips#icicle-image-preview-in-tooltip|icicle-image-preview-in-tooltip]]</tt>'''' 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 
`<tt>[[Icicles - Customization and General Tips#icicle-image-files-in-Completions|icicle-image-files-in-Completions]]</tt>' is non-`nil' and
`icicle-image-preview-in-tooltip' is not `full'.




[:ScrollCompletions]
=== 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*'.






[:VerticalLayout]
=== Optional Vertical Layout ===

You can lay completion candidates out vertically, if you like,
instead of horizontally (the default).  To do that, customize
option '''`<tt>[[Icicles - Customization and General Tips#icicle-completions-format|icicle-completions-format]]</tt>'''' 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-completion]]s) 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 [[Icicles - Customization and General Tips#icicle-completions-format|Customization and General Tips]].










[:ProxyCandidates]
=== 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 '''`<tt>[[Icicles - Customization and General Tips#icicle-add-proxy-candidates-flag|icicle-add-proxy-candidates-flag]]</tt>''''.  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:

* When you read a file name with completion, the proxy candidates include the following (reading a [[face]] name is similar):

** '''`##*mouse-2 file name*##'''' -- proxy for a file name that you click with `mouse-2'.  

** '''`##*point file name*##'''' -- proxy for the file name at [[point]] (if available).

** Single-quoted names of file-name variables -- proxy for the variable value.

* When a command reads input using `icicle-read-number' or
`icicle-read-string-completing', the proxy candidates are all
variables whose values are numbers or strings, respectively.
You can choose such a proxy candidate to use its value.  (All
candidates are proxy candidates for these functions.)

* When you use command `icicle-read-color-WYSIWYG', the proxy candidates include the following:

** '''`##*point foreground*##'''' -- proxy for the foreground color at the cursor position (point).

** '''`##*mouse-2 foreground*##'''' -- proxy for the foreground color where you then click `mouse-2'.

** '''`##*copied foreground*##'''' -- proxy for a previously copied foreground color, the value of variable `eyedrop-picked-foreground'.

** Background versions of the first three: `##*copied background*##' etc.

** Single-quoted names of color-valued variables -- proxy for the variable value.

'''See Also:''' [[Icicles - Candidate Sets#SaveRetrieveWithVariable|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.







[:CompletionPopupMenu]
=== 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 '''`<tt>[[Icicles - Customization and General Tips#icicle-Completions-mouse-3-menu-entries|icicle-Completions-mouse-3-menu-entries]]</tt>''''.  By default, the menu
has the following submenus:


* '''This Candidate''' -- Act on the candidate that you clicked to
pop up the menu.  Or act on all current candidates,
individually or collectively.

* '''Sorting''' -- Change the current candidate sort order.

* '''Save/Retrieve''' -- Save (mark) candidates or retrieve them,
including to/from a variable or a cache file.

* '''Sets''' -- Perform operations on sets of candidates, in
particular, the set of current candidates and the set of
saved candidates.

* '''Toggle/Cycle/Change''' -- Toggle, cycle, or otherwise change an
'''Icicles''' setting, altering the behavior on the fly.

* '''Miscellaneous''' -- Other candidate operations and general help.

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:
[[Icicles - Nutshell View#CompletionPopupMenu|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): 

: [[image:iciclesscreenshot]]

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

'''See Also:'''

* [[Icicles - Moving Between the Minibuffer and Other Buffers]] for information on the `pause' key, which is somewhat related to using `C-insert'.

* [[Icicles - Candidates with Text Properties]] and [[Icicles - Programming Multi-Completions]] for information about using text
properties in `*Completions*'.  These sections are for Emacs-Lisp
programmers.




----



|| *Previous:*  [[Icicles - Ido and IswitchB]] || '''[[Icicles]]''' || IciclesIndex || *Next:* [[Icicles - Icompletion]] ||



DrewsElispLibraries referenced here: Lisp:icicles.el


CategoryCommands 
CategoryCompletion
CategoryRegexp
CategoryDocumentation
CategoryHelp
CategoryProgrammerUtils
CategoryCode