diff options
| -rw-r--r-- | doc/emacs/mini.texi | 49 | ||||
| -rw-r--r-- | doc/lispref/text.texi | 25 | ||||
| -rw-r--r-- | etc/NEWS | 27 | ||||
| -rw-r--r-- | lisp/minibuffer.el | 25 |
4 files changed, 71 insertions, 55 deletions
diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index 24517262fa6..72a3cf24912 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -628,14 +628,19 @@ commands never display the completion list buffer; you must type shows the completion list buffer on the second attempt to complete. In other words, if there is nothing to complete, the first @key{TAB} echoes @samp{Next char not unique}; the second @key{TAB} shows the -completion list buffer. With the previous values and the default -@code{t} the completions are hidden when some unique completion is -executed. If @code{completion-auto-help} is set to @code{always}, the -completion commands are always shown after a completion attempt, or -updated if they are already visible. If the value is @code{visible}, -then completions are not hidden, but updated if they are already -visible while the current behavior stays the same as default if they -are not. +completion list buffer. If the value is @code{always}, the completion +list buffer is always shown when completion is attempted. + +The display of the completion list buffer after it is shown for the +first time is also controlled by @code{completion-auto-help}. If the +value is @code{t} or @code{lazy}, the window showing the completions +pops down when Emacs is able to complete (and may pop up again if +Emacs is again unable to complete after you type some more text); if +the value is @code{always}, the window pops down only when you exit +the completion. The value @code{visible} is a hybrid: it behaves like +@code{t} when it decides whether to pop up the window showing the +completion list buffer, and like @code{always} when it decides whether +to pop it down. @vindex completion-cycle-threshold If @code{completion-cycle-threshold} is non-@code{nil}, completion @@ -668,21 +673,25 @@ Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp Reference Manual}). @vindex completions-header-format -The variable @code{completions-header-format} is a formatted string to +The variable @code{completions-header-format} is a format spec string to control the informative line shown before the completions list of -candidates. It may contain a @code{%s} to show the total number of -completions. When it is @code{nil}, the message is totally suppressed. -Text properties may be added to change the appearance, some useful -ones are @code{face} or @code{cursor-intangible} (@pxref{Special -Properties,,Properties with Special Meanings, elisp, The Emacs Lisp -Reference Manual}). +candidates. If it contains a @samp{%s} construct, that get replaced +by the number of completions shown in the completion list buffer. To +suppress the display of the heading line, customize this variable to +@code{nil}. The string that is the value of this variable can have +text properties to change the visual appearance of the heading line; +some useful properties @code{face} or @code{cursor-intangible} +(@pxref{Special Properties,,Properties with Special Meanings, elisp, +The Emacs Lisp Reference Manual}). @vindex completions-highlight-face -When @code{completions-highlight-face} is a face name, then the -current completion candidate will be highlighted with that face. The -default value is @code{completions-highlight}. When the value is -@code{nil}, no highlighting is performed. This feature sets the text -property @code{cursor-face}. +When @code{completions-highlight-face} names a face, the current +completion candidate, the one that will be selected by typing +@kbd{@key}RET}} or clicking the mouse, will be highlighted using that +face. The default value of this variable is +@code{completions-highlight}; the value is @code{nil} disables this +highlighting. This feature uses the special text property +@code{cursor-face}. @node Minibuffer History @section Minibuffer History diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index edb75b453c8..f76512c5a0b 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3541,10 +3541,10 @@ special modes that implement their own highlighting. @item mouse-face @kindex mouse-face @r{(text property)} -This property is used instead of @code{face} when the mouse is on or -near the character. For this purpose, ``near'' means that all text -between the character and where the mouse is have the same -@code{mouse-face} property value. +This property is used instead of @code{face} when the mouse pointer +hovers over the text which has this property. When this happens, the +entire stretch of text that has the same @code{mouse-face} property +value, not just the character under the mouse, is highlighted. Emacs ignores all face attributes from the @code{mouse-face} property that alter the text size (e.g., @code{:height}, @code{:weight}, and @@ -3553,14 +3553,17 @@ unhighlighted text. @item cursor-face @kindex cursor-face @r{(text property)} -This property is similar to @code{mouse-face}, but the face is used if -the cursor (instead of mouse) is on or near the character. Near has -the same meaning that in @code{mouse-face} and the highlighting only -takes effect if the mode @code{cursor-face-highlight-mode} is enabled; -otherwise no highlighting is performed. When the variable +@findex cursor-face-highlight-mode +@vindex cursor-face-highlight-nonselected-window +This property is similar to @code{mouse-face}, but it is used when +point (not the mouse) is inside text that has this property. The +highlighting happens only if the mode +@code{cursor-face-highlight-mode} is enabled. When the variable @code{cursor-face-highlight-nonselected-window} is non-@code{nil}, the -text is highlighted even if the window is not selected that is similar -to @code{highlight-nonselected-windows} for the region. +text with this face is highlighted even if the window is not selected, +similarly to what @code{highlight-nonselected-windows} does for the +region (@pxref{Mark,, The Mark and the Region, emacs, The GNU Emacs +Manual}). @item fontified @kindex fontified @r{(text property)} @@ -579,28 +579,29 @@ alphabetical (the default), or a custom sort function. +++ *** New values for the 'completion-auto-help' user option. -There are two new values to control the way "*Completions*" behave after -a 'TAB' if completion is not unique. 'always' updates or shows -the "*Completions*" buffer after any attempt to complete. 'visual' is -like 'always', but only update the completions if they are already -visible. The default value 't' always hides the completion buffer after -some completion is made. +There are two new values to control the way the "*Completions*" buffer +behaves after pressing a 'TAB' if completion is not unique. The value +'always' updates or shows the "*Completions*" buffer after any attempt +to complete. The value 'visual' is like 'always', but only updates +the completions if they are already visible. The default value 't' +always hides the completion buffer after some completion is made. +++ *** New user option 'completions-max-height'. This option limits the height of the "*Completions*" buffer. +++ -*** New user option 'completions-header-format' -This is a string to control the message to show before completions. -It may contain a "%s" to show the total number of completions. If nil no -completions are shown. +*** New user option 'completions-header-format'. +This is a string to control the heading line to show in the +"*Completions*" buffer before the list of completions. +If it contains "%s", that is replaced with the number of completions. +If nil, the heading line is not shown. +++ *** New user option 'completions-highlight-face'. -When this user option is a face name, it highlights the current -candidate in the "*Completions*" buffer with that face. When the -value is nil, no highlighting is performed at all. +When this user option names a face, the current +candidate in the "*Completions*" buffer is highlighted with that face. +The nil value disables this highlighting. ** Isearch and Replace diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 00d4560865c..c4fb1c00391 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -894,20 +894,23 @@ If the current buffer is not a minibuffer, erase its entire contents." (defcustom completion-auto-help t "Non-nil means automatically provide help for invalid completion input. -If the value is t the *Completions* buffer is displayed whenever completion +If the value is t, the *Completions* buffer is displayed whenever completion is requested but cannot be done. If the value is `lazy', the *Completions* buffer is only displayed after the second failed attempt to complete. -If the value is 'always', the completion commands are always shown -after a completion attempt, or updated if they are already visible. -If the value is 'visible', then completions are not hidden, but updated -if they are already visible while the current behavior stays the same -as default if they are not." - :type '(choice (const :tag "Disabled" nil) - (const :tag "Enabled legacy" t) - (const :tag "After a second attempt" lazy) - (const :tag "Visible update" visible) - (const :tag "Always update" always))) +If the value is 'always', the *Completions* buffer is always shown +after a completion attempt, and the list of completions is updated if +already visible. +If the value is 'visible', the *Completions* buffer is displayed +whenever completion is requested but cannot be done for the first time, +but remains visible thereafter, and the list of completions in it is +updated for subsequent attempts to complete.." + :type '(choice (const :tag "Don't show" nil) + (const :tag "Show only when cannot complete" t) + (const :tag "Show after second failed completion attempt" lazy) + (const :tag + "Leave visible after first failed completion" visible) + (const :tag "Always visible" always))) (defvar completion-styles-alist '((emacs21 |