From 7fe37cfcce719480da3bafd2e7f1346c2f44b22e Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Fri, 16 Nov 2012 21:29:58 -0500 Subject: [PATCH] * display.texi (Temporary Displays): Document with-temp-buffer-window. * etc/NEWS: Related edit. --- doc/lispref/ChangeLog | 2 ++ doc/lispref/display.texi | 34 +++++++++++++++++++++++++++++++++- etc/NEWS | 4 +++- 3 files changed, 38 insertions(+), 2 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index b7baac9c2f..6726c6d2ad 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,7 @@ 2012-11-17 Glenn Morris + * display.texi (Temporary Displays): Document with-temp-buffer-window. + * frames.texi (Size and Position): Add fit-frame-to-buffer command. * windows.texi (Resizing Windows): Add fit-frame-to-buffer option. (Window Sizes): Add vindex for window-min-height, window-min-width. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 9fedd162da..475a9550f9 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1078,7 +1078,8 @@ editing. Many help commands use this feature. This function executes @var{forms} while arranging to insert any output they print into the buffer named @var{buffer-name}, which is first created if necessary, and put into Help mode. Finally, the buffer is -displayed in some window, but not selected. +displayed in some window, but not selected. (See the similar +form @code{with-temp-buffer-window} below.) If the @var{forms} do not change the major mode in the output buffer, so that it is still Help mode at the end of their execution, then @@ -1152,6 +1153,37 @@ displaying the temporary buffer. When the hook runs, the temporary buffer is current, and the window it was displayed in is selected. @end defvar +@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{} +This macro is similar to @code{with-output-to-temp-buffer}. +Like that construct, it executes @var{forms} while arranging to insert +any output they print into the buffer named @var{buffer-or-name}. +Finally, the buffer is displayed in some window, but not selected. +Unlike @code{with-output-to-temp-buffer}, this does not switch to Help +mode. + +The argument @var{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 +@code{with-temp-buffer-window} exits. + +This macro does not call @code{temp-buffer-show-function}. Rather, it +passes the @var{action} argument to @code{display-buffer} in order to +display the buffer. + +The value of the last form in @var{forms} is returned, unless the +argument @var{quit-function} is specified. In that case, +it is called with two arguments: the window showing the buffer +and the result of @var{forms}. The final return value is then +whatever @var{quit-function} returns. + +@vindex temp-buffer-window-setup-hook +@vindex temp-buffer-window-show-hook +This macro uses the normal hooks @code{temp-buffer-window-setup-hook} +and @code{temp-buffer-window-show-hook} in place of the analogous hooks +run by @code{with-output-to-temp-buffer}. +@end defmac + @defun momentary-string-display string position &optional char message This function momentarily displays @var{string} in the current buffer at @var{position}. It has no effect on the undo list or on the buffer's diff --git a/etc/NEWS b/etc/NEWS index a951677bd1..d040ba7ddf 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -846,7 +846,9 @@ now accept a third argument to avoid choosing the selected window. +++ *** Additional values recognized for option `window-combination-limit'. -*** New macro `with-temp-buffer-window'. ++++ +*** New macro `with-temp-buffer-window', similar to +`with-output-to-temp-buffer'. --- *** `temp-buffer-resize-mode' no longer resizes windows that have been -- 2.20.1