From: Glenn Morris Date: Sat, 17 Nov 2012 02:29:58 +0000 (-0500) Subject: * display.texi (Temporary Displays): Document with-temp-buffer-window. X-Git-Tag: emacs-24.2.90~59 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=7fe37cfcce719480da3bafd2e7f1346c2f44b22e;p=emacs.git * display.texi (Temporary Displays): Document with-temp-buffer-window. * etc/NEWS: Related edit. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index b7baac9c2fe..6726c6d2ad0 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 9fedd162da6..475a9550f99 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 a951677bd1d..d040ba7ddf8 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