mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-30 04:10:54 -08:00
Code Issues Projects Releases Wiki Activity

Update docs for select-window and buffer-list-update-hook.

Browse source 
* 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'.
This commit is contained in:
Martin Rudalics 2014-03-07 16:11:12 +01:00
parent 84254bbdf0
commit 2c6053e838
8 changed files with 74 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

7
doc/lispref/ChangeLog
View file

@ -1,7 +1,14 @@
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>

11
doc/lispref/buffers.texi
View file

@ -25,7 +25,7 @@ not be displayed in any windows.
* 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.
@ -759,7 +759,7 @@ buffer is read-only. @xref{Using Interactive}, for another way to
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
@ -910,6 +910,13 @@ buffer returned by @code{last-buffer} (see above), in the selected
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

9
doc/lispref/elisp.texi
View file

@ -992,7 +992,7 @@ 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
@ -1344,12 +1344,13 @@ Emacs Display
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
@ -1384,10 +1385,10 @@ Faces
* 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.

2
doc/lispref/hooks.texi
View file

@ -98,7 +98,7 @@ Hook run after a frame's font changes.
@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

52
doc/lispref/windows.texi
View file

@ -1504,16 +1504,27 @@ windows.
@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
@ -1882,7 +1893,7 @@ window and make it the current buffer. It is often used interactively
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}
@ -1890,7 +1901,7 @@ 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
@ -1968,7 +1979,7 @@ possible (@pxref{Input Focus}). The return value is the buffer that
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}
@ -2524,9 +2535,9 @@ or killed, or has been already shown by a recent invocation of
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
@ -2537,7 +2548,7 @@ defaults to the selected one.
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}
@ -2584,7 +2595,7 @@ called when a buffer gets killed, deletes the window in case (1) and
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
@ -2623,7 +2634,7 @@ buffer is shown on a separate frame, you might want to call
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
@ -2705,11 +2716,12 @@ one window that should be either quit, or whose buffer should be buried.
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}

6
src/ChangeLog
View file

@ -1,3 +1,9 @@
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

4
src/buffer.c
View file

@ -6284,9 +6284,9 @@ The function `kill-all-local-variables' runs this before doing anything else. *
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");

15
src/window.c
View file

@ -559,7 +559,7 @@ select_window_1 (Lisp_Object window, bool inhibit_point_swap)
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.
@ -567,8 +567,17 @@ Optional second arg NORECORD non-nil means do not put this buffer at the
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);