* buffer.c (Vbuffer_list_update_hook): Doc-string fix.
* window.c (Fselect_window): Explain NORECORD and
`buffer-list-update-hook' in doc-string.
* buffers.texi (The Buffer List): Rename node to Buffer List.
Describe `buffer-list-update-hook'.
* elisp.texi (Top): "The Buffer List" renamed to "Buffer List".
Add node for Window Dividers.
* hooks.texi (Standard Hooks): Add reference to
`buffer-list-update-hook'.
* windows.texi (Selecting Windows): Update description of
`select-window'.
2014-03-07 Martin Rudalics <rudalics@gmx.at>
+ * buffers.texi (The Buffer List): Rename node to Buffer List.
+ Describe `buffer-list-update-hook'.
+ * elisp.texi (Top): "The Buffer List" renamed to "Buffer List".
+ Add node for Window Dividers.
+ * hooks.texi (Standard Hooks): Add reference to
+ `buffer-list-update-hook'.
* windows.texi (Window Sizes): Describe `window-min-size'.
(Splitting Windows): Update description of `split-window'.
+ (Selecting Windows): Update description of `select-window'.
2014-03-06 Martin Rudalics <rudalics@gmx.at>
* Modification Time:: Determining whether the visited file was changed
"behind Emacs's back".
* Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
-* The Buffer List:: How to look at all the existing buffers.
+* Buffer List:: How to look at all the existing buffers.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
signal an error if the current buffer is read-only.
@end defun
-@node The Buffer List
+@node Buffer List
@section The Buffer List
@cindex buffer list
window.
@end deffn
+@defvar buffer-list-update-hook
+This is a normal hook run whenever the buffer list changes. Functions
+(implicitly) running this hook are @code{get-buffer-create}
+(@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}),
+@code{kill-buffer} (@pxref{Killing Buffers}), @code{bury-buffer} (see
+above) and @code{select-window} (@pxref{Selecting Windows}).
+@end defvar
@node Creating Buffers
@section Creating Buffers
"behind Emacs's back".
* Read Only Buffers:: Modifying text is not allowed in a
read-only buffer.
-* The Buffer List:: How to look at all the existing buffers.
+* Buffer List:: How to look at all the existing buffers.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some
for text characters: font, colors, etc.
* Fringes:: Controlling window fringes.
* Scroll Bars:: Controlling vertical scroll bars.
+* Window Dividers:: Separating windows visually.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Character Display:: How Emacs displays individual characters.
+* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
* Attribute Functions:: Functions to examine and set face attributes.
* Displaying Faces:: How Emacs combines the faces specified for
a character.
-* Face Remapping:: Remapping faces to alternative definitions.
+* Face Remapping:: Remapping faces to alternative definitions.
* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
-* Basic Faces:: Faces that are defined by default.
+* Basic Faces:: Faces that are defined by default.
* Font Selection:: Finding the best available font for a face.
* Font Lookup:: Looking up the names of available fonts
and information about them.
@item buffer-list-update-hook
@vindex buffer-list-update-hook
-Hook run when the buffer list changes.
+Hook run when the buffer list changes (@pxref{Buffer List}).
@item buffer-quit-function
@vindex buffer-quit-function
@defun select-window window &optional norecord
This function makes @var{window} the selected window and the window
selected within its frame (@pxref{Basic Windows}) and selects that
-frame. @var{window} must be a live window. This function also makes
-@var{window}'s buffer (@pxref{Buffers and Windows}) current and sets
-that buffer's value of @code{point} to the value of @code{window-point}
-(@pxref{Window Point}) in @var{window}. The return value is
-@var{window}.
+frame. It also makes @var{window}'s buffer (@pxref{Buffers and
+Windows}) current and sets that buffer's value of @code{point} to the
+value of @code{window-point} (@pxref{Window Point}) in @var{window}.
+@var{window} must be a live window. The return value is @var{window}.
By default, this function also moves @var{window}'s buffer to the front
-of the buffer list (@pxref{The Buffer List}), and makes @var{window} the
+of the buffer list (@pxref{Buffer List}), and makes @var{window} the
most recently selected window. However, if the optional argument
@var{norecord} is non-@code{nil}, these additional actions are omitted.
+
+This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
+unless @var{norecord} is non-@code{nil}. Note that applications and
+internal routines often temporarily select a window in order to simplify
+coding. As a rule, such selections (including those made by the macros
+@code{save-selected-window} and @code{with-selected-window} below) are
+not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
+Selections that ``really count'' are those causing a visible change in
+the next redisplay of @var{window}'s frame and should be always
+recorded. This also means that to run a function each time a window
+gets selected, putting it on @code{buffer-list-update-hook} should be
+the right choice.
@end defun
@cindex most recently selected windows
return value is the buffer switched to.
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
-returned by @code{other-buffer} (@pxref{The Buffer List}). If
+returned by @code{other-buffer} (@pxref{Buffer List}). If
@var{buffer-or-name} is a string that is not the name of any existing
buffer, this function creates a new buffer with that name; the new
buffer's major mode is determined by the variable @code{major-mode}
Normally, the specified buffer is put at the front of the buffer
list---both the global buffer list and the selected frame's buffer
-list (@pxref{The Buffer List}). However, this is not done if the
+list (@pxref{Buffer List}). However, this is not done if the
optional argument @var{norecord} is non-@code{nil}.
Sometimes, @code{switch-to-buffer} may be unable to display the buffer
was switched to.
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
-returned by @code{other-buffer} (@pxref{The Buffer List}). If
+returned by @code{other-buffer} (@pxref{Buffer List}). If
@var{buffer-or-name} is a string that is not the name of any existing
buffer, this function creates a new buffer with that name; the new
buffer's major mode is determined by the variable @code{major-mode}
If repeated invocations of this command have already shown all buffers
previously shown in @var{window}, further invocations will show buffers
-from the buffer list of the frame @var{window} appears on (@pxref{The
-Buffer List}), trying to skip buffers that are already shown in another
-window on that frame.
+from the buffer list of the frame @var{window} appears on (@pxref{Buffer
+List}), trying to skip buffers that are already shown in another window
+on that frame.
@end deffn
@deffn Command switch-to-next-buffer &optional window
If there is no recent invocation of @code{switch-to-prev-buffer} that
can be undone, this function tries to show a buffer from the buffer list
-of the frame @var{window} appears on (@pxref{The Buffer List}).
+of the frame @var{window} appears on (@pxref{Buffer List}).
@end deffn
By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
behaves like @code{delete-windows-on} otherwise.
@c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
- When @code{bury-buffer} (@pxref{The Buffer List}) operates on the
+ When @code{bury-buffer} (@pxref{Buffer List}) operates on the
selected window (which shows the buffer that shall be buried), it
handles case (2) by calling @code{frame-auto-hide-function}
(@pxref{Quitting Windows}) to deal with the selected frame. 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
+Finally, you might want to either bury (@pxref{Buffer List}) or kill
(@pxref{Killing Buffers}) the window's buffer.
The following command uses information on how the window for
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
-to bury. It is also called by @code{quit-restore-window} (see above)
-when the frame of the window to quit has been specially created for
-displaying that window's buffer and the buffer is not killed.
+The function specified here is called by @code{bury-buffer}
+(@pxref{Buffer List}) when the selected window is dedicated and shows
+the buffer to bury. It is also called by @code{quit-restore-window}
+(see above) when the frame of the window to quit has been specially
+created for displaying that window's buffer and the buffer is not
+killed.
The default is to call @code{iconify-frame} (@pxref{Visibility of
Frames}). Alternatively, you may specify either @code{delete-frame}
+2014-03-07 Martin Rudalics <rudalics@gmx.at>
+
+ * buffer.c (Vbuffer_list_update_hook): Doc-string fix.
+ * window.c (Fselect_window): Explain NORECORD and
+ `buffer-list-update-hook' in doc-string.
+
2014-03-06 Martin Rudalics <rudalics@gmx.at>
* window.c (Fother_window_for_scrolling): Check that
DEFVAR_LISP ("buffer-list-update-hook", Vbuffer_list_update_hook,
doc: /* Hook run when the buffer list changes.
-Functions running this hook are `get-buffer-create',
+Functions running this hook are, `get-buffer-create',
`make-indirect-buffer', `rename-buffer', `kill-buffer',
-and `bury-buffer-internal'. */);
+`bury-buffer-internal' and `select-window'. */);
Vbuffer_list_update_hook = Qnil;
DEFSYM (Qbuffer_list_update_hook, "buffer-list-update-hook");
DEFUN ("select-window", Fselect_window, Sselect_window, 1, 2, 0,
doc: /* Select WINDOW which must be a live window.
Also make WINDOW's frame the selected frame and WINDOW that frame's
-selected window. In addition, make WINDOW's buffer current and set that
+selected window. In addition, make WINDOW's buffer current and set its
buffer's value of `point' to the value of WINDOW's `window-point'.
Return WINDOW.
front of the buffer list and do not make this window the most recently
selected one.
-Note that the main editor command loop sets the current buffer to the
-buffer of the selected window before each command. */)
+Run `buffer-list-update-hook' unless NORECORD is non-nil. Note that
+applications and internal routines often select a window temporarily for
+various purposes; mostly, to simplify coding. As a rule, such
+selections should be not recorded and therefore will not pollute
+`buffer-list-update-hook'. Selections that "really count" are those
+causing a visible change in the next redisplay of WINDOW's frame and
+should be always recorded. So if you think of running a function each
+time a window gets selected put it on `buffer-list-update-hook'.
+
+Also note that the main editor command loop sets the current buffer to
+the buffer of the selected window before each command. */)
(register Lisp_Object window, Lisp_Object norecord)
{
return select_window (window, norecord, 0);
projects / emacs.git / commitdiff