From d83dc65b3f42fae9b2085b9a1ca986c401d49f8d Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Sun, 9 Oct 2011 14:26:29 +0200 Subject: [PATCH] Describe frame-auto-hide-function and related issues. * buffers.texi (The Buffer List): Describe how bury-buffer deals with the selected window. * windows.texi (Buffers and Windows): Reformulate text on how replace-buffer-in-windows deals with a window. (Quitting Windows): Describe how quit-window deals with a standalone frame. Describe new option frame-auto-hide-function. --- doc/lispref/ChangeLog | 9 ++++++ doc/lispref/buffers.texi | 33 +++++++++++--------- doc/lispref/windows.texi | 67 ++++++++++++++++++++++++++++------------ etc/NEWS | 5 +++ 4 files changed, 81 insertions(+), 33 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index adc15cfc373..f822b4bebdf 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,12 @@ +2011-10-09 Martin Rudalics + + * buffers.texi (The Buffer List): Describe how bury-buffer deals + with the selected window. + * windows.texi (Buffers and Windows): Reformulate text on how + replace-buffer-in-windows deals with a window. + (Quitting Windows): Describe how quit-window deals with a + standalone frame. Describe new option frame-auto-hide-function. + 2011-10-08 Glenn Morris * symbols.texi (Other Plists): Markup fix. (Bug#9702) diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index ce1a8b0fb4e..816d0f9faa8 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -884,23 +884,28 @@ This buffer therefore becomes the least desirable candidate for @code{other-buffer} to return. The argument can be either a buffer itself or the name of one. -@code{bury-buffer} operates on each frame's @code{buffer-list} parameter -as well as the fundamental buffer list; therefore, the buffer that you -bury will come last in the value of @code{(buffer-list @var{frame})} and -in the value of @code{(buffer-list)}. - -If @var{buffer-or-name} is @code{nil} or omitted, this means to bury -the current buffer. In addition, if the buffer is displayed in the -selected window, this switches to some other buffer (obtained using -@code{other-buffer}) in the selected window. @xref{Switching -Buffers}. But if the selected window is dedicated to its buffer, it -deletes that window if there are other windows left on its frame. -Otherwise, if the selected window is the only window on its frame, it -iconifies that frame. If @var{buffer-or-name} is displayed in some +This functions operates on each frame's @code{buffer-list} parameter as +well as the fundamental buffer list; therefore, the buffer that you bury +will come last in the value of @code{(buffer-list @var{frame})} and in +the value of @code{(buffer-list)}. In addition, it also puts the buffer +at the end of the list of buffer of the selected window (@pxref{Window +History}) provided it is shown in that window. + +If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the +current buffer. In addition, if the current buffer is displayed in the +selected window, this makes sure that the window is either deleted or +another buffer is shown in it. More precisely, if the window is +dedicated (@pxref{Dedicated Windows}) and there are other windows on its +frame, the window is deleted. If the window is both dedicated and the +only window on its frame's terminal, the function specified by +@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal +with the window. If the window is not dedicated to its buffer, it calls +@code{switch-to-prev-buffer} (@pxref{Window History}) to show another +buffer in that window. If @var{buffer-or-name} is displayed in some other window, it remains displayed there. To replace a buffer in all the windows that display it, use -@code{replace-buffer-in-windows}. @xref{Buffers and Windows}. +@code{replace-buffer-in-windows}, @xref{Buffers and Windows}. @end deffn @deffn Command unbury-buffer diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index bffea19210c..41ccbaafd49 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -2076,16 +2076,17 @@ This command replaces @var{buffer-or-name} with some other buffer, in all windows displaying it. For each such window, it choose another buffer using @code{switch-to-prev-buffer} (@pxref{Window History}). -@var{buffer-or-name} may be a buffer, or the name of an existing -buffer; it defaults to the current buffer. +The argument @var{buffer-or-name} may be a buffer, or the name of an +existing buffer; it defaults to the current buffer. If a window displaying @var{buffer-or-name} is dedicated -(@pxref{Dedicated Windows}), has never displayed any other buffers and -is not the only window on its frame, that window is deleted. If that -window is the only window on its frame and there are other frames on the -frame's terminal, that frame is deleted too; otherwise, the buffer -provided by the function @code{switch-to-prev-buffer} (@pxref{Window -History}) is displayed instead. +(@pxref{Dedicated Windows}) and is not the only window on its frame, +that window is deleted. If that window is the only window on its frame +and there are other frames on the frame's terminal, that frame is dealt +with by the function spcecified by @code{frame-auto-hide-function} +(@pxref{Quitting Windows}). Otherwise, the buffer provided by the +function @code{switch-to-prev-buffer} (@pxref{Window History}) is +displayed in the window instead. @end deffn @@ -2784,14 +2785,14 @@ non-@code{nil} value. @section Quitting Windows When you want to get rid of a window used for displaying a buffer you -can use the function @code{delete-window} (@pxref{Deleting Windows}) to -remove that window from its frame. If the buffer has been shown on a -separate frame, you might want to call @code{delete-frame} -(@pxref{Deleting Frames}) instead. If, on the other hand, a window has -been reused for displaying the buffer, you might prefer showing the -buffer previously shown in that window by calling the function -@code{switch-to-prev-buffer} (@pxref{Window History}). Finally, you -might want to either bury (@pxref{The Buffer List}) or kill +can call @code{delete-window} or @code{delete-windows-on} +(@pxref{Deleting Windows}) to remove that window from its frame. If the +buffer is shown on a separate frame, you might want to call +@code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other +hand, a window has been reused for displaying the buffer, you might +prefer showing the buffer previously shown in that window by calling the +function @code{switch-to-prev-buffer} (@pxref{Window History}). +Finally, you might want to either bury (@pxref{The Buffer List}) or kill (@pxref{Killing Buffers}) the window's buffer. The following function uses information on how the window for @@ -2807,9 +2808,12 @@ instead of burying it. Quitting @var{window} means to proceed as follows: If @var{window} was created specially for displaying its current buffer, delete @var{window} provided its frame contains at least one other live window. If -@var{window} is the only window on its frame and other frames still -exist, delete the frame together with @var{window}. If, however, there -are no other frames left, display some other buffer in @var{window}. +@var{window} is the only window on its frame and there are other frames +on the frame's terminal, the value of @var{kill} determines how to +proceed with the window. If @var{kill} is @code{nil}, the fate of the +frame is determined by calling @code{frame-auto-hide-function} (see +below) with that frame as sole argument. If @var{kill} is +non-@code{nil}, the frame is deleted unconditionally. If @var{window} was reused for displaying its buffer, this command tries to display the buffer previously shown in it. It also tries to restore @@ -2831,6 +2835,31 @@ stored in @var{window}'s @code{quit-restore} window parameter (@pxref{Window Parameters}) and resets that parameter to @code{nil} after it's done. +The following option specifies how to deal with a frame containing just +one window that shall be either quit or whose buffer shall be buried. + +@defopt frame-auto-hide-function +The function specified by this option is called to automatically hide +frames. This function is called with one argument - a frame. + +The function specified here is called by @code{bury-buffer} (@pxref{The +Buffer List}) when the selected window is dedicated and shows the buffer +that shall be buried. It is also called by @code{quit-window} (see +above) when the frame of the window that shall be quit has been +specially created for displaying that window's buffer and the buffer +shall be buried. + +The default is to call @code{iconify-frame} (@pxref{Visibility of +Frames}). Alternatively, you may either specify @code{delete-frame} +(@pxref{Deleting Frames}) to remove the frame from its display, +@code{ignore} to leave the frame unchanged, or any other function that +can take a frame as its sole argument. + +Note that the function specified by this option is called if and only if +there's at least one other frame on the terminal of the frame it's +supposed to handle and that frame contains only one live window. +@end defopt + @node Window Point @section Windows and Point diff --git a/etc/NEWS b/etc/NEWS index 99cb7b5ab48..7cda5ec09ff 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1106,6 +1106,11 @@ See the docstring of `display-buffer' for details. The behavior of `quit-window' has been changed in order to restore the state before the last buffer display operation in that window. ++++ +*** The new option `frame-auto-hide-function' lets you choose between +iconfying or deleting a frame when burying a buffer shown in a dedicated +frame or quitting a window showing a buffer in a frame of its own. + ** Completion *** New variable completion-extra-properties used to specify extra properties -- 2.39.2