"%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
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
+++
** 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'.
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"
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))
(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)))
projects / emacs.git / commitdiff