From: Eli Zaretskii Date: Sat, 1 Apr 2023 09:49:18 +0000 (+0300) Subject: Document enhancements in handling of echo-area messages X-Git-Tag: emacs-29.0.90~46 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d1d39a0f09c272a8bdea54ecd13f560bbd8264eb;p=emacs.git Document enhancements in handling of echo-area messages * etc/NEWS: * doc/lispref/display.texi (Displaying Messages): * lisp/minibuffer.el (inhibit-message-regexps) (set-message-functions, inhibit-message, set-multi-message): Improve the documentation of functions dealing with display of echo-area messages. --- diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 550d711c73a..85fac4b30a6 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -310,29 +310,29 @@ reformatted, with undesirable results. Instead, use @code{(message "%s" @var{string})}. @end defun +The following facilities allow users and Lisp programs to control how +echo-area messages are displayed. + @defvar set-message-function If this variable is non-@code{nil}, it should be a function of one -argument, the text of a message to display in the echo area. This +argument, the text of a message to display in the echo area. That function will be called by @code{message} and related functions. If the function returns @code{nil}, the message is displayed in the echo -area as usual. If this function returns a string, that string is -displayed in the echo area instead of the original one. If this -function returns other non-@code{nil} values, that means the message -was already handled, so @code{message} will not display anything in -the echo area. See also @code{clear-message-function} that can be -used to clear the message displayed by this function. - -The default value is the function that displays the message at the end -of the minibuffer when the minibuffer is active. However, if the text -shown in the active minibuffer has the @code{minibuffer-message} text -property (@pxref{Special Properties}) on some character, the message -will be displayed before the first character having that property. +area as usual. If the function returns a string, that string is +displayed in the echo area @emph{instead} of the original message. If +the function returns any other non-@code{nil} value, that means the +message was already handled, so @code{message} will not display +anything in the echo area. + +The default value calls @code{set-minibuffer-message}, described +below. @end defvar @defvar clear-message-function -If this variable is non-@code{nil}, @code{message} and related -functions call it with no arguments when their argument message is -@code{nil} or the empty string. +If this variable is non-@code{nil}, it should be a function of no +arguments; @code{message} and related functions call it when their +argument message is @code{nil} or the empty string, to clear the echo +area. Usually this function is called when the next input event arrives after displaying an echo-area message. The function is expected to @@ -358,11 +358,51 @@ with the same text; if the last function in the list returns function returns a non-@code{nil} value that is not a string, the message is considered to be handled, and no further functions in the list are called. + +The three useful functions to be put in the list that is the value of +this option are described below. @end defopt +@defun set-minibuffer-message message +This function displays @var{message} in the echo-area when the +minibuffer is not active, and at the end of the minibuffer when the +minibuffer is active. However, if the text shown in the active +minibuffer has the @code{minibuffer-message} text property +(@pxref{Special Properties}) on some character, the message will be +displayed before the first character having that property. + +This function is by default the only member of the list in +@code{set-message-functions}. +@end defun + +@vindex inhibit-message-regexps +@defun inhibit-message message +If an echo-area @var{message} matches any regexp in the list that is +the value of the user option @code{inhibit-message-regexps}, this +function suppresses the display of that message and returns a +non-@code{nil} value that is not a string. Thus, if this function is +in the list @code{set-message-functions}, the rest of the functions in +the list will not be called when @var{message} matches the regexps in +@code{inhibit-message-regexps}. To ensure a matching @var{message} +will never be displayed, make this function be the first element of +the list in @code{set-message-functions}. +@end defun + +@vindex multi-message-max +@vindex multi-message-timeout +@defun set-multi-message message +This function accumulates several echo-area messages emitted one after +another, and returns them as a single string in which individual +messages are separated by newlines. Up to @code{multi-message-max} +recent messages can be accumulated. The accumulated messages are +discarded when more than @code{multi-message-timeout} seconds have +elapsed since the time the first message was emitted. +@end defun + @defvar inhibit-message When this variable is non-@code{nil}, @code{message} and related functions -will not use the Echo Area to display messages. +will not display any messages in the Echo Area. Echo-area messages +are still logged in the @file{*Messages*} buffer, though. @end defvar @defmac with-temp-message message &rest body diff --git a/etc/NEWS b/etc/NEWS index d7a6cf7986d..e43a82b1426 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -795,13 +795,14 @@ part of the buffer. +++ ** New user option 'set-message-functions'. -It allows selecting more functions for 'set-message-function' -in addition to the default function that handles messages -in the active minibuffer. The most useful are 'inhibit-message' -that allows specifying a list of messages to inhibit via -'inhibit-message-regexps', and 'set-multi-message' that -accumulates recent messages and displays them stacked -in the echo area. +It allows more flexible control of how echo-area message are displayed +by adding functions to this list. The default value is a list of one +element: 'set-minibuffer-message', which displays echo-area messages +at the end of the minibuffer text when the minibuffer is active. +Other useful functions include 'inhibit-message', which allows +specifying, via 'inhibit-message-regexps', the list of messages whose +display shall be inhibited; and 'set-multi-message' that accumulates +recent messages and displays them stacked together. --- ** New user option 'find-library-include-other-files'. diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 21d4607e7cf..be91987d635 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -862,7 +862,18 @@ If a function returns a string, the returned string is given to the next function in the list, and if the last function returns a string, it's displayed in the echo area. If a function returns any other non-nil value, no more functions are -called from the list, and no message will be displayed in the echo area." +called from the list, and no message will be displayed in the echo area. + +Useful functions to add to this list are: + + `inhibit-message' -- if this function is the first in the list, + messages that match the value of + `inhibit-message-regexps' will be suppressed. + `set-multi-message' -- accumulate multiple messages and display them + together as a single message. + `set-minibuffer-message' -- if the minibuffer is active, display the + message at the end of the minibuffer text + (this is the default)." :type '(choice (const :tag "No special message handling" nil) (repeat (choice (function-item :tag "Inhibit some messages" @@ -884,13 +895,18 @@ called from the list, and no message will be displayed in the echo area." message) (defcustom inhibit-message-regexps nil - "List of regexps that inhibit messages by the function `inhibit-message'." + "List of regexps that inhibit messages by the function `inhibit-message'. +When the list in `set-message-functions' has `inhibit-message' as its +first element, echo-area messages which match the value of this variable +will not be displayed." :type '(repeat regexp) :version "29.1") (defun inhibit-message (message) "Don't display MESSAGE when it matches the regexp `inhibit-message-regexps'. -This function is intended to be added to `set-message-functions'." +This function is intended to be added to `set-message-functions'. +To suppress display of echo-area messages that match `inhibit-message-regexps', +make this function be the first element of `set-message-functions'." (or (and (consp inhibit-message-regexps) (string-match-p (mapconcat #'identity inhibit-message-regexps "\\|") message)) @@ -912,6 +928,10 @@ This function is intended to be added to `set-message-functions'." (defun set-multi-message (message) "Return recent messages as one string to display in the echo area. +Individual messages will be separated by a newline. +Up to `multi-message-max' messages can be accumulated, and the +accumulated messages are discarded when `multi-message-timeout' +seconds have elapsed since the first message. Note that this feature works best only when `resize-mini-windows' is at its default value `grow-only'." (let ((last-message (car multi-message-list)))