mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-16 09:50:25 +00:00
Code Issues Releases Activity

Improve documentation of set-window-start

Browse Source 
* doc/lispref/windows.texi (Window Start and End):
* src/window.c (Fset_window_start): Document that reliable
setting of a window start position requires to adjust point to
be visible.  (Bug#34038)
This commit is contained in:
Eli Zaretskii 2019-04-06 11:22:13 +03:00
parent 92ce2dd48b
commit a30a6c3019
2 changed files with 21 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/lispref/windows.texi
View File

@ -4625,13 +4625,14 @@ This function sets the display-start position of @var{window} to
@var{position} in @var{window}'s buffer. It returns @var{position}.
The display routines insist that the position of point be visible when a
buffer is displayed. Normally, they change the display-start position
(that is, scroll the window) whenever necessary to make point visible.
However, if you specify the start position with this function using
@code{nil} for @var{noforce}, it means you want display to start at
@var{position} even if that would put the location of point off the
screen. If this does place point off screen, the display routines move
point to the left margin on the middle line in the window.
buffer is displayed. Normally, they select the display-start position
according to their internal logic (and scroll the window if necessary)
to make point visible. However, if you specify the start position
with this function using @code{nil} for @var{noforce}, it means you
want display to start at @var{position} even if that would put the
location of point off the screen. If this does place point off
screen, the display routines attempt to move point to the left margin
on the middle line in the window.
For example, if point @w{is 1} and you set the start of the window
@w{to 37}, the start of the next line, point will be above the top
@ -4678,6 +4679,13 @@ it is still 1 when redisplay occurs. Here is an example:
@end group
@end example
If the attempt to make point visible (i.e., in a fully-visible screen
line) fails, the display routines will disregard the requested
window-start position and compute a new one anyway. Thus, for
reliable results Lisp programs that call this function should always
move point to be inside the window whose display starts at
@var{position}.
If @var{noforce} is non-@code{nil}, and @var{position} would place point
off screen at the next redisplay, then redisplay computes a new window-start
position that works well with point, and thus @var{position} is not used.

7
src/window.c
View File

@ -1704,7 +1704,12 @@ DEFUN ("set-window-start", Fset_window_start, Sset_window_start, 2, 3, 0,
doc: /* Make display in WINDOW start at position POS in WINDOW's buffer.
WINDOW must be a live window and defaults to the selected one. Return
POS. Optional third arg NOFORCE non-nil inhibits next redisplay from
overriding motion of point in order to display at this exact start. */)
overriding motion of point in order to display at this exact start.
For reliable setting of WINDOW start position, make sure point is
at a position that will be visible when that start is in effect,
otherwise there's a chance POS will be disregarded, e.g., if point
winds up in a partially-visible line. */)
(Lisp_Object window, Lisp_Object pos, Lisp_Object noforce)
{
register struct window *w = decode_live_window (window);