mirror of
https://github.com/masscollaborationlabs/emacs.git
synced 2025-07-10 22:20:51 +00:00
Improve documentation of set-window-start
* 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:
parent
92ce2dd48b
commit
a30a6c3019
2 changed files with 21 additions and 8 deletions
|
@ -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.
|
||||||
|
|
|
@ -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);
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue