This section describes the standard functions for displaying messages in the echo area.
This function displays a message in the echo area.
format-string is a format string, and arguments are the
objects for its format specifications, like in the format-message
function (see Formatting Strings). The resulting formatted string
is displayed in the echo area; if it contains face
text
properties, it is displayed with the specified faces (see Faces).
The string is also added to the *Messages* buffer, but without
text properties (see Logging Messages in *Messages*).
Typically grave accent and apostrophe in the format translate to
matching curved quotes, e.g., "Missing `%s'"
might result in
"Missing ‘foo’"
. See Text Quoting Style, for how to influence
or inhibit this translation.
In batch mode, the message is printed to the standard error stream, followed by a newline.
When inhibit-message
is non-nil
, no message will be displayed
in the echo area, it will only be logged to ‘*Messages*’.
If format-string is nil
or the empty string,
message
clears the echo area; if the echo area has been
expanded automatically, this brings it back to its normal size. If
the minibuffer is active, this brings the minibuffer contents back
onto the screen immediately.
(message "Reverting `%s'..." (buffer-name)) -| Reverting ‘subr.el’... ⇒ "Reverting ‘subr.el’..."
---------- Echo Area ---------- Reverting ‘subr.el’... ---------- Echo Area ----------
To automatically display a message in the echo area or in a pop-buffer,
depending on its size, use display-message-or-buffer
(see below).
Warning: If you want to use your own string as a message
verbatim, don’t just write (message string)
. If
string contains ‘%’, ‘`’, or ‘'’ it may be
reformatted, with undesirable results. Instead, use (message
"%s" string)
.
The following facilities allow users and Lisp programs to control how echo-area messages are displayed.
If this variable is non-nil
, it should be a function of one
argument, the text of a message to display in the echo area. That
function will be called by message
and related functions. If
the function returns nil
, the message is displayed in the echo
area as usual. If the function returns a string, that string is
displayed in the echo area instead of the original message. If
the function returns any other non-nil
value, that means the
message was already handled, so message
will not display
anything in the echo area.
The default value calls set-minibuffer-message
, described
below.
If this variable is non-nil
, it should be a function of no
arguments; message
and related functions call it when their
argument message is 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
clear the message displayed by its counterpart function specified by
set-message-function
, but doesn’t have to. If the function
wants the echo area to remain uncleared, it should return the symbol
dont-clear-message
; any other value will result in the echo
area being cleared.
The default value is the function that clears the message displayed in an active minibuffer.
The value of this user option is a list of functions to be called for
handling display of echo-area messages. Each function is called with
one argument, the text of the message to display. If the function
returns a string, that string replaces the original message, and the
next function in the list is called with the new message text. If the
function returns nil
, the next function in the list is called
with the same text; if the last function in the list returns
nil
, the message text is displayed in the echo area. If the
function returns a non-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.
This function displays 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 minibuffer-message
text property
(see Properties with Special Meanings) 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
set-message-functions
.
If an echo-area message matches any regexp in the list that is
the value of the user option inhibit-message-regexps
, this
function suppresses the display of that message and returns a
non-nil
value that is not a string. Thus, if this function is
in the list set-message-functions
, the rest of the functions in
the list will not be called when message matches the regexps in
inhibit-message-regexps
. To ensure a matching message
will never be displayed, make this function be the first element of
the list in set-message-functions
.
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 multi-message-max
recent messages can be accumulated. The accumulated messages are
discarded when more than multi-message-timeout
seconds have
elapsed since the time the first message was emitted.
When this variable is non-nil
, message
and related functions
will not display any messages in the Echo Area. Echo-area messages
are still logged in the *Messages* buffer, though.
This construct displays a message in the echo area temporarily, during the execution of body. It displays message, executes body, then returns the value of the last body form while restoring the previous echo area contents.
This function displays a message like message
, but may display it
in a dialog box instead of the echo area. If this function is called in
a command that was invoked using the mouse—more precisely, if
last-nonmenu-event
(see Information from the Command Loop) is either
nil
or a list—then it uses a dialog box or pop-up menu to
display the message. Otherwise, it uses the echo area. (This is the
same criterion that y-or-n-p
uses to make a similar decision; see
Yes-or-No Queries.)
You can force use of the mouse or of the echo area by binding
last-nonmenu-event
to a suitable value around the call.
This function displays a message like message
, but uses a dialog
box (or a pop-up menu) whenever that is possible. If it is impossible
to use a dialog box or pop-up menu, because the terminal does not
support them, then message-box
uses the echo area, like
message
.
This function displays the message message, which may be either a
string or a buffer. If it is shorter than the maximum height of the
echo area, as defined by max-mini-window-height
, it is displayed
in the echo area, using message
. Otherwise,
display-buffer
is used to show it in a pop-up buffer.
Returns either the string shown in the echo area, or when a pop-up buffer is used, the window used to display it.
If message is a string, then the optional argument buffer-name is the name of the buffer used to display it when a pop-up buffer is used, defaulting to *Message*. In the case where message is a string and displayed in the echo area, it is not specified whether the contents are inserted into the buffer anyway.
The optional arguments action and frame are as for
display-buffer
, and only used if a buffer is displayed.
This function returns the message currently being displayed in the
echo area, or nil
if there is none.