masscollaborationlabs/emacs
2
0
Fork 0
mirror of https://github.com/masscollaborationlabs/emacs.git synced 2025-07-10 22:20:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

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
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}. @var{position} in @var{window}'s buffer. It returns @var{position}.
The display routines insist that the position of point be visible when a The display routines insist that the position of point be visible when a
buffer is displayed. Normally, they change the display-start position buffer is displayed. Normally, they select the display-start position
(that is, scroll the window) whenever necessary to make point visible. according to their internal logic (and scroll the window if necessary)
However, if you specify the start position with this function using to make point visible. However, if you specify the start position
@code{nil} for @var{noforce}, it means you want display to start at with this function using @code{nil} for @var{noforce}, it means you
@var{position} even if that would put the location of point off the want display to start at @var{position} even if that would put the
screen. If this does place point off screen, the display routines move location of point off the screen. If this does place point off
point to the left margin on the middle line in the window. 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 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 @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 group
@end example @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 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 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. 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. 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 WINDOW must be a live window and defaults to the selected one. Return
POS. Optional third arg NOFORCE non-nil inhibits next redisplay from 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) (Lisp_Object window, Lisp_Object pos, Lisp_Object noforce)
{ {
register struct window *w = decode_live_window (window); register struct window *w = decode_live_window (window);