diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index b66454f9304..24517262fa6 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -624,15 +624,15 @@ completion alternatives in the completion list. @vindex completion-auto-help If @code{completion-auto-help} is set to @code{nil}, the completion commands never display the completion list buffer; you must type -@kbd{?} to display the list. If the value is @code{lazy}, Emacs only +@kbd{?} to display the list. If the value is @code{lazy}, Emacs only 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} +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. @@ -659,29 +659,29 @@ changed by changing the @code{completions-format} user option. If and if @code{one-column}, just use a single column. @vindex completions-max-height - When @code{completions-max-height} is non-@code{nil} it limits the + When @code{completions-max-height} is non-@code{nil}, it limits the size of the completions window. It is specified in lines and include mode, header line and a bottom divider, if any. For a more complex -control of the Completion window display properties you can use +control of the Completion window display properties, you can use @code{display-buffer-alist} (@pxref{Buffer Display Action Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp Reference Manual}). -@vindex completion-header-format -The variable @code{completion-header-format} is a formatted string to +@vindex completions-header-format +The variable @code{completions-header-format} is a formatted string to control the informative line shown before the completions list of -candidates. It may contain a ``%s'' to show the total number of -completions. When it is @code{nil} the message is totally suppressed. +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}). @vindex completions-highlight-face -When @code{completions-highlight-face} is a face name; then the +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 highlight is performed. This feature sets the text +@code{nil}, no highlighting is performed. This feature sets the text property @code{cursor-face}. @node Minibuffer History diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 30036675e10..edb75b453c8 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3553,15 +3553,14 @@ 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 +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 than in @code{mouse-face} and the highlight only +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 highlight is performed. When the variable -@code{cursor-face-highlight-nonselected-window} is non-@code{nil} the -text is highlighted even if the window is not selected similar to -@code{highlight-nonselected-windows} for the region. The default -value is the same of @code{cursor-in-non-selected-windows}. +otherwise no highlighting is performed. 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. @item fontified @kindex fontified @r{(text property)} diff --git a/etc/NEWS b/etc/NEWS index bb92e463109..026a9d1f7f0 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -556,9 +556,9 @@ alphabetical (the default), or a custom sort function. +++ *** New values for the 'completion-auto-help' option. -There are two new values to control the way *Completions* behave after +There are two new values to control the way "*Completions*" behave after a if completion is not unique. 'always' updates or shows -the *Completions* buffer after any attempt to complete. 'visual' is +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. @@ -568,17 +568,16 @@ some completion is made. This option limits the height of the "*Completions*" buffer. +++ -*** New option 'completion-header-format' +*** New 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 +It may contain a "%s" to show the total number of completions. If nil no completions are shown. +++ *** New option 'completions-highlight-face'. -When this variable is a face name it highlights the current candidate -in the *Completions* buffer with that face. When the value is nil no -highlight is performed at all. - +When this variable 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. ** Isearch and Replace @@ -1262,11 +1261,11 @@ property. This allows setting a minimum display width for a region of text. +++ -** New 'cursor-face 'text' property. -This uses cursor-face instead of the default face when cursor is on or +** New 'cursor-face' text property. +This uses 'cursor-face' instead of the default face when cursor is on or near the character and 'cursor-face-highlight-mode' is enabled. The -variable 'highlight-nonselected-windows' is similar to -'highlight-nonselected-windows' but for this property. +variable 'cursor-face-highlight-nonselected-window' is similar to +'highlight-nonselected-windows', but for this property. +++ ** New event type 'touch-end'. diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 46e7bf2fb05..00d4560865c 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -899,8 +899,8 @@ 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 +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) @@ -1853,6 +1853,17 @@ Return nil if there is no valid completion, else t." This face is only used if the strings used for completions doesn't already specify a face.") +(defface completions-highlight + '((t :inherit highlight)) + "Default face for highlighting the current completion candidate." + :version "29.1") + +(defcustom completions-highlight-face 'completions-highlight + "A face name to highlight the current completion candidate. +If the value is nil, no highlighting is performed." + :type '(choice (const nil) face) + :version "29.1") + (defcustom completions-format 'horizontal "Define the appearance and sorting of completions. If the value is `vertical', display completions sorted vertically @@ -1872,15 +1883,15 @@ completions." :type 'boolean :version "28.1") -(defcustom completion-header-format +(defcustom completions-header-format (propertize "%s possible completions:\n" 'face 'shadow :help "Please select a completion") "Format of completions header. It may contain one %s to show the total count of completions. -When nil no header is shown." - :type '(choice (const :tag "No prefix" nil) - (string :tag "Prefix format string")) +When nil, no header is shown." + :type '(choice (const :tag "No header" nil) + (string :tag "Header format string")) :version "29.1") (defun completion--insert-strings (strings &optional group-fun) @@ -2145,25 +2156,13 @@ candidates." (with-current-buffer standard-output (goto-char (point-max)) - (when completion-header-format - (insert (format completion-header-format (length completions)))) + (when completions-header-format + (insert (format completions-header-format (length completions)))) (completion--insert-strings completions group-fun))) (run-hooks 'completion-setup-hook) nil) - -(defface completions-highlight - '((t :inherit highlight)) - "Default face for highlighting the current line in `completions-highlight-mode'." - :version "29.1") - -(defcustom completions-highlight-face 'completions-highlight - "A face name to highlight current completion candidate. -If the value is nil no highlight is performed." - :type '(choice (const nil) face) - :version "29.1") - (defvar completion-extra-properties nil "Property list of extra properties of the current completion job. These include: @@ -2232,12 +2231,12 @@ variables.") (completion--message message)))) (defcustom completions-max-height nil - "Maximum height for *Completions* buffer." + "Maximum height for *Completions* buffer window." :type '(choice (const nil) natnum) :version "29.1") (defun completions--fit-window-to-buffer (&optional win &rest _) - "Resize completions." + "Resize *Completions* buffer window." (if temp-buffer-resize-mode (let ((temp-buffer-max-height (or completions-max-height temp-buffer-max-height))) diff --git a/lisp/simple.el b/lisp/simple.el index 8eece3e81fb..21ea08c0f2c 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -6483,7 +6483,7 @@ separate contiguous regions for each line." (cdr (region-bounds))) (defun redisplay--unhighlight-overlay-function (rol) - "If ROL is an overlay, call ``delete-overlay''." + "If ROL is an overlay, call `delete-overlay'." (when (overlayp rol) (delete-overlay rol))) (defvar redisplay-unhighlight-region-function @@ -9399,7 +9399,7 @@ Called from `temp-buffer-show-hook'." (setq tab-width completion-tab-width)) ;; Maybe enable cursor completions-highlight. (when completions-highlight-face - ;; keep highlight even if not selected + ;; Keep highlighting even if not selected. (setq-local cursor-face-highlight-nonselected-window t) (cursor-face-highlight-mode 1)) ;; Maybe insert help string.