SXEmacs Lisp Reference Manual: The Echo Area

52.3 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 SXEmacs Lisp Reference Manual specifies the rules for resolving conflicts between the echo area and the minibuffer for use of that screen space (see The Minibuffer in The SXEmacs Lisp Reference Manual). Error messages appear in the echo area; see Errors.

You can write output in the echo area by using the Lisp printing functions with t as the stream (see Output Functions), or as follows:

Function: message string &rest arguments

This function displays a one-line message in the echo area. The argument string is similar to a C language printf control string. See format in 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 is nil, message clears the echo area. If the minibuffer is active, this brings the minibuffer contents back onto the screen immediately.

(message "Minibuffer depth is %d."
         (minibuffer-depth))
 -| Minibuffer depth is 0.
⇒ "Minibuffer depth is 0."

---------- Echo Area ----------
Minibuffer depth is 0.
---------- Echo Area ----------

In addition to only displaying a message, SXEmacs allows you to label your messages, giving you fine-grained control of their display. Message label is a symbol denoting the message type. Some standard labels are:

message—default label used by the message function;
error—default label used for reporting errors;
progress—progress indicators like ‘Converting... 45%’ (not logged by default);
prompt—prompt-like messages like ‘Isearch: foo’ (not logged by default);
command—helper command messages like ‘Mark set’ (not logged by default);
no-log—messages that should never be logged

Several messages may be stacked in the echo area at once. Lisp programs may access these messages, or remove them as appropriate, via the message stack.

Function: display-message label message &optional frame stdout-p

This function displays message (a string) labeled as label, as described above.

The frame argument specifies the frame to whose minibuffer the message should be printed. This is currently unimplemented. The stdout-p argument is used internally.

(display-message 'command "Mark set")

Function: lmessage label string &rest arguments

This function displays a message string with label label. It is similar to message in that it accepts a printf-like strings and any number of arguments.

;; Display a command message.
(lmessage 'command "Comment column set to %d" comment-column)

;; Display a progress message.
(lmessage 'progress "Fontifying %s... (%d)" buffer percentage)

;; Display a message that should not be logged.
(lmessage 'no-log "Done")

Function: clear-message &optional label frame stdout-p no-restore

This function remove any message with the given label from the message-stack, erasing it from the echo area if it’s currently displayed there.

If a message remains at the head of the message-stack and no-restore is nil, it will be displayed. The string which remains in the echo area will be returned, or nil if the message-stack is now empty. If label is nil, the entire message-stack is cleared.

;; Show a message, wait for 2 seconds, and restore old minibuffer
;; contents.
(message "A message")
 -| A message
⇒ "A Message"
(lmessage 'my-label "Newsflash!  Newsflash!")
 -| Newsflash!  Newsflash!
⇒ "Newsflash!  Newsflash!"
(sit-for 2)
(clear-message 'my-label)
 -| A message
⇒ "A message"

Unless you need the return value or you need to specify a label, you should just use (message nil).

Function: current-message &optional frame: This function returns the current message in the echo area, or nil. The frame argument is currently unused.

Some of the messages displayed in the echo area are also recorded in the ‘ *Message-Log*’ buffer. Exactly which messages will be recorded can be tuned using the following variables.

User Option: log-message-max-size: This variable specifies the maximum size of the ‘ *Message-log*’ buffer.

Variable: log-message-ignore-labels: This variable specifies the labels whose messages will not be logged. It should be a list of symbols.

Variable: log-message-ignore-regexps

This variable specifies the regular expressions matching messages that will not be logged. It should be a list of regular expressions.

Normally, packages that generate messages that might need to be ignored should label them with progress, prompt, or no-log, so they can be filtered by log-message-ignore-labels.

Variable: echo-keystrokes

This variable determines how much time should elapse before command characters echo. Its value must be a 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. Any subsequent characters in the same command will be echoed as well.

If the value is zero, then command input is not echoed.

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.