The Echo Area
=============
The "echo area" is used for displaying messages made with the
`message' primitive, and for echoing keystrokes. It is not the same as
the minibuffer, despite the fact that the minibuffer appears (when
active) in the same place on the screen as the echo area. The `GNU
Emacs Manual' specifies the rules for resolving conflicts between the
echo area and the minibuffer for use of that screen space (Note:The
Minibuffer.). Error messages appear in the echo
area; see Note:Errors.
You can write output in the echo area by using the Lisp printing
functions with `t' as the stream (Note:Output Functions), or as
follows:
- Function: message string &rest arguments
This function displays a message in the echo area. The argument
STRING is similar to a C language `printf' control string. See
`format' in Note:String Conversion, for the details on the
conversion specifications. `message' returns the constructed
string.
In batch mode, `message' prints the message text on the standard
error stream, followed by a newline.
If STRING, or strings among the ARGUMENTS, have `face' text
properties, these affect the way the message is displayed.
If STRING is `nil', `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.
Normally, displaying a long message resizes the echo area to
display the entire message. But if the variable
`message-truncate-lines' is non-`nil', the echo area does not
resize, and the message is truncated to fit it, as in Emacs 20 and
before.
(message "Minibuffer depth is %d."
(minibuffer-depth))
-| Minibuffer depth is 0.
=> "Minibuffer depth is 0."
---------- Echo Area ----------
Minibuffer depth is 0.
---------- 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'.
- Macro: with-temp-message message &rest body
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.
- Function: message-or-box string &rest arguments
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' (Note:Command Loop Info) 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 Note: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.
- Function: message-box string &rest arguments
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'.
- Function: display-message-or-buffer message &optional buffer-name
not-this-window frame
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 NOT-THIS-WINDOW and FRAME are as for
`display-buffer', and only used if a buffer is displayed.
- Function: current-message
This function returns the message currently being displayed in the
echo area, or `nil' if there is none.
- Variable: cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area. If it is non-`nil', then the cursor
appears at the end of the message. Otherwise, the cursor appears
at point--not in the echo area at all.
The value is normally `nil'; Lisp programs bind it to `t' for
brief periods of time.
- Variable: echo-area-clear-hook
This normal hook is run whenever the echo area is cleared--either
by `(message nil)' or for any other reason.
Almost all the messages displayed in the echo area are also recorded
in the `*Messages*' buffer.
- User Option: message-log-max
This variable specifies how many lines to keep in the `*Messages*'
buffer. The value `t' means there is no limit on how many lines to
keep. The value `nil' disables message logging entirely. Here's
how to display a message and prevent it from being logged:
(let (message-log-max)
(message ...))
- Variable: echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be an integer or floating point
number, which specifies the number of seconds to wait before
echoing. If the user types a prefix key (such as `C-x') and then
delays this many seconds before continuing, the prefix key is
echoed in the echo area. (Once echoing begins in a key sequence,
all subsequent characters in the same key sequence are echoed
immediately.)
If the value is zero, then command input is not echoed.