Temporary displays are used by Lisp programs to put output into a buffer and then present it to the user for perusal rather than for editing. Many help commands use this feature.
This function executes the forms in body while arranging to insert any output they print into the buffer named buffer-name, which is first created if necessary, and put into Help mode. (See the similar form
with-temp-buffer-windowbelow.) Finally, the buffer is displayed in some window, but that window is not selected.
If the forms in body do not change the major mode in the output buffer, so that it is still Help mode at the end of their execution, then
with-output-to-temp-buffermakes this buffer read-only at the end, and also scans it for function and variable names to make them into clickable cross-references. See Tips for Documentation Strings, in particular the item on hyperlinks in documentation strings, for more details.
The string buffer-name specifies the temporary buffer, which need not already exist. The argument must be a string, not a buffer. The buffer is erased initially (with no questions asked), and it is marked as unmodified after
standard-outputto the temporary buffer, then it evaluates the forms in body. Output using the Lisp output functions within body goes by default to that buffer (but screen display and messages in the echo area, although they are “output” in the general sense of the word, are not affected). See Output Functions.
Several hooks are available for customizing the behavior of this construct; they are listed below.
The value of the last form in body is returned.---------- Buffer: foo ---------- This is the contents of foo. ---------- Buffer: foo ---------- (with-output-to-temp-buffer "foo" (print 20) (print standard-output)) ⇒ #<buffer foo> ---------- Buffer: foo ---------- 20 #<buffer foo> ---------- Buffer: foo ----------
If this variable is non-
with-output-to-temp-buffercalls it as a function to do the job of displaying a help buffer. The function gets one argument, which is the buffer it should display.
It is a good idea for this function to run
with-output-to-temp-buffernormally would, inside of
save-selected-windowand with the chosen window and buffer selected.
This normal hook is run by
with-output-to-temp-bufferbefore evaluating body. When the hook runs, the temporary buffer is current. This hook is normally set up with a function to put the buffer in Help mode.
This normal hook is run by
with-output-to-temp-bufferafter displaying the temporary buffer. When the hook runs, the temporary buffer is current, and the window it was displayed in is selected.
This macro is similar to
with-output-to-temp-buffer. Like that construct, it executes body while arranging to insert any output it prints into the buffer named buffer-or-name and displays that buffer in some window. Unlike
with-output-to-temp-buffer, however, it does not automatically switch that buffer to Help mode.
with-output-to-temp-bufferit neither makes the buffer specified by buffer-or-name current when executing body. The otherwise identical macro
with-current-buffer-windowcan be used to execute body with that buffer current.
The argument buffer-or-name specifies the temporary buffer. It can be either a buffer, which must already exist, or a string, in which case a buffer of that name is created, if necessary. The buffer is marked as unmodified and read-only when
This macro does not call
temp-buffer-show-function. Rather, it passes the action argument to
display-bufferin order to display the buffer.
The value of the last form in body is returned, unless the argument quit-function is specified. In that case, it is called with two arguments: the window showing the buffer and the result of body. The final return value is then whatever quit-function returns.
This function momentarily displays string in the current buffer at position. It has no effect on the undo list or on the buffer's modification status.
The momentary display remains until the next input event. If the next input event is char,
momentary-string-displayignores it and returns. Otherwise, that event remains buffered for subsequent use as input. Thus, typing char will simply remove the string from the display, while typing (say) C-f will remove the string from the display and later (presumably) move point forward. The argument char is a space by default.
The return value of
momentary-string-displayis not meaningful.
If the string string does not contain control characters, you can do the same job in a more general way by creating (and then subsequently deleting) an overlay with a
before-stringproperty. See Overlay Properties.
If message is non-
nil, it is displayed in the echo area while string is displayed in the buffer. If it is
nil, a default message says to type char to continue.
In this example, point is initially located at the beginning of the second line:---------- Buffer: foo ---------- This is the contents of foo. -!-Second line. ---------- Buffer: foo ---------- (momentary-string-display "**** Important Message! ****" (point) ?\r "Type RET when done reading") ⇒ t ---------- Buffer: foo ---------- This is the contents of foo. **** Important Message! ****Second line. ---------- Buffer: foo ---------- ---------- Echo Area ---------- Type RET when done reading ---------- Echo Area ----------