Function: with-temp-buffer-window

with-temp-buffer-window is a macro defined in window.el.gz.

Signature

(with-temp-buffer-window BUFFER-OR-NAME ACTION QUIT-FUNCTION &rest BODY)

Documentation

Bind standard-output to BUFFER-OR-NAME, eval BODY, show the buffer.

BUFFER-OR-NAME must specify either a live buffer, or the name of a buffer (if it does not exist, this macro creates it).

Make the buffer specified by BUFFER-OR-NAME empty before running BODY and bind standard-output to that buffer, so that output generated with prin1 and similar functions in BODY goes into that buffer. Do not make that buffer current for running the forms in BODY. Use with-current-buffer-window instead if you need to run BODY with that buffer current.

At the end of BODY, mark the specified buffer unmodified and read-only, and display it in a window (but do not select it). The display happens by calling display-buffer passing it the ACTION argument. If temp-buffer-resize-mode(var)/temp-buffer-resize-mode(fun) is enabled, the corresponding window may be resized automatically.

Return the value returned by BODY, unless QUIT-FUNCTION specifies a function. In that case, run that function with two arguments - the window showing the specified buffer and the value returned by BODY - and return the value returned by that function.

If the buffer is displayed on a new frame, the window manager may decide to select that frame. In that case, it's usually a good strategy if QUIT-FUNCTION selects the window showing the buffer before reading any value from the minibuffer; for example, when asking a yes-or-no-p question.

This runs the hook temp-buffer-window-setup-hook before BODY, with the specified buffer temporarily current. It runs the hook temp-buffer-window-show-hook after displaying the buffer, with that buffer temporarily current, and the window that was used to display it temporarily selected.

This construct is similar to with-output-to-temp-buffer but, neither runs temp-buffer-setup-hook which usually puts the buffer in Help mode, nor temp-buffer-show-function (the ACTION argument replaces this).

View in manual

Probably introduced at or before Emacs version 24.3.

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defmacro with-temp-buffer-window (buffer-or-name action quit-function &rest body)
  "Bind `standard-output' to BUFFER-OR-NAME, eval BODY, show the buffer.
BUFFER-OR-NAME must specify either a live buffer, or the name of
a buffer (if it does not exist, this macro creates it).

Make the buffer specified by BUFFER-OR-NAME empty before running
BODY and bind `standard-output' to that buffer, so that output
generated with `prin1' and similar functions in BODY goes into
that buffer.  Do not make that buffer current for running the
forms in BODY.  Use `with-current-buffer-window' instead if you
need to run BODY with that buffer current.

At the end of BODY, mark the specified buffer unmodified and
read-only, and display it in a window (but do not select it).
The display happens by calling `display-buffer' passing it the
ACTION argument.  If `temp-buffer-resize-mode' is enabled, the
corresponding window may be resized automatically.

Return the value returned by BODY, unless QUIT-FUNCTION specifies
a function.  In that case, run that function with two arguments -
the window showing the specified buffer and the value returned by
BODY - and return the value returned by that function.

If the buffer is displayed on a new frame, the window manager may
decide to select that frame.  In that case, it's usually a good
strategy if QUIT-FUNCTION selects the window showing the buffer
before reading any value from the minibuffer; for example, when
asking a `yes-or-no-p' question.

This runs the hook `temp-buffer-window-setup-hook' before BODY,
with the specified buffer temporarily current.  It runs the hook
`temp-buffer-window-show-hook' after displaying the buffer, with
that buffer temporarily current, and the window that was used to
display it temporarily selected.

This construct is similar to `with-output-to-temp-buffer' but,
neither runs `temp-buffer-setup-hook' which usually puts the
buffer in Help mode, nor `temp-buffer-show-function' (the ACTION
argument replaces this)."
  (declare (debug t) (indent 3))
  (let ((buffer (make-symbol "buffer"))
	(window (make-symbol "window"))
	(value (make-symbol "value")))
    (macroexp-let2* nil ((vbuffer-or-name buffer-or-name)
			 (vaction action)
			 (vquit-function quit-function))
      `(let* ((,buffer (temp-buffer-window-setup ,vbuffer-or-name))
	      (standard-output ,buffer)
	      ,window ,value)
	 (setq ,value (progn ,@body))
	 (with-current-buffer ,buffer
	   (setq ,window (temp-buffer-window-show ,buffer ,vaction)))

	 (if (functionp ,vquit-function)
	     (funcall ,vquit-function ,window ,value)
	   ,value)))))