From 01827de4518c8da974821da0439f2ad4984d49da Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Tue, 30 Dec 2014 10:56:43 +0100 Subject: [PATCH] Update documentation of Temporary Displays. * display.texi (Temporary Displays): Amend description of `with-temp-buffer-window'. Add descriptions for `with-current-buffer-window', `with-displayed-buffer-window' and `temp-buffer-resize-mode', `temp-buffer-max-height' and `temp-buffer-max-width'. * frame.c (frame_inhibit_implied_resize): Escape left paren in doc-string. --- doc/lispref/ChangeLog | 8 +++++ doc/lispref/display.texi | 64 +++++++++++++++++++++++++++++++++------- src/frame.c | 2 +- 3 files changed, 63 insertions(+), 11 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index ad9af13488e..c9f576af5e6 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,11 @@ +2014-12-30 Martin Rudalics + + * display.texi (Temporary Displays): Amend description of + `with-temp-buffer-window'. Add descriptions for + `with-current-buffer-window', `with-displayed-buffer-window' and + `temp-buffer-resize-mode', `temp-buffer-max-height' and + `temp-buffer-max-width'. + 2014-12-27 Glenn Morris * control.texi (Pattern matching case statement): diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index e26d6491850..14a98f32ffb 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1194,12 +1194,6 @@ it prints into the buffer named @var{buffer-or-name} and displays that buffer in some window. Unlike @code{with-output-to-temp-buffer}, however, it does not automatically switch that buffer to Help mode. -Like @code{with-output-to-temp-buffer} it neither makes the buffer -specified by @var{buffer-or-name} current when executing @var{body}. -@findex with-current-buffer-window -The otherwise identical macro @code{with-current-buffer-window} can be -used to execute @var{body} with that buffer current. - 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 @@ -1207,14 +1201,14 @@ 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. +passes the @var{action} argument to @code{display-buffer} +(@pxref{Choosing Window}) in order to display the buffer. The value of the last form in @var{body} 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{body}. The final return value is then whatever -@var{quit-function} returns. +@var{body}. The final return value is then whatever @var{quit-function} +returns. @vindex temp-buffer-window-setup-hook @vindex temp-buffer-window-show-hook @@ -1223,6 +1217,56 @@ and @code{temp-buffer-window-show-hook} in place of the analogous hooks run by @code{with-output-to-temp-buffer}. @end defmac +The two constructs described next are mostly identical to +@code{with-temp-buffer-window} but differ from it as specified: + +@defmac with-current-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-temp-buffer-window} but unlike that makes +the buffer specified by @var{buffer-or-name} current for running +@var{body}. +@end defmac + +@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-current-buffer-window} but unlike that +displays the buffer specified by @var{buffer-or-name} @emph{before} +running @var{body}. +@end defmac + +A window showing a temporary buffer can be fit to the size of that +buffer using the following mode: + +@defopt temp-buffer-resize-mode +When this minor mode is enabled, windows showing a temporary buffer are +automatically resized to fit their buffer's contents. + +A window is resized if and only if it has been specially created for the +buffer. In particular, windows that have shown another buffer before +are not resized. By default, this mode uses @code{fit-window-to-buffer} +(@pxref{Resizing Windows}) for resizing. You can specify a different +function by customizing the options @code{temp-buffer-max-height} and +@code{temp-buffer-max-width} below. +@end defopt + +@defopt temp-buffer-max-height +This option specifies the maximum height (in lines) of a window +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the height +for such a buffer. It gets one argument, the buffer, and should return +a positive integer. At the time the function is called, the window to +be resized is selected. +@end defopt + +@defopt temp-buffer-max-width +This option specifies the maximum width of a window (in columns) +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the width for +such a buffer. It gets one argument, the buffer, and should return a +positive integer. At the time the function is called, the window to be +resized is selected. +@end defopt + +The following function uses the current buffer for temporal display: + @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/src/frame.c b/src/frame.c index 2ad1c1b52b7..82a85bc48e6 100644 --- a/src/frame.c +++ b/src/frame.c @@ -5057,7 +5057,7 @@ keep it unchanged if this option is either `t' or a list containing `vertical-scroll-bars'. The default value is '(tool-bar-lines) on Lucid, Motif and Windows -(which means that adding/removing a tool bar does not change the frame +\(which means that adding/removing a tool bar does not change the frame height), nil on all other window systems including GTK+ (which means that changing any of the parameters listed above may change the size of the frame), and `t' otherwise (which means the frame size never changes -- 2.39.2