28.10 The Window Start Position

Each window contains a marker used to keep track of a buffer position that specifies where in the buffer display should start. This position is called the display-start position of the window (or just the start). The character after this position is the one that appears at the upper left corner of the window. It is usually, but not inevitably, at the beginning of a text line.

Function: window-start &optional window

This function returns the display-start position of window window. If window is nil, the selected window is used. For example,

(window-start) => 7058

When you create a window, or display a different buffer in it, the display-start position is set to a display-start position recently used for the same buffer, or 1 if the buffer doesn't have any.

Redisplay updates the window-start position (if you have not specified it explicitly since the previous redisplay)---for example, to make sure point appears on the screen. Nothing except redisplay automatically changes the window-start position; if you move point, do not expect the window-start position to change in response until after the next redisplay.

For a realistic example of using window-start, see the description of count-lines in 30.2.4 Motion by Text Lines.

Function: window-end &optional window update

This function returns the position of the end of the display in window window. If window is nil, the selected window is used.

Simply changing the buffer text or moving point does not update the value that window-end returns. The value is updated only when Emacs redisplays and redisplay completes without being preempted.

If the last redisplay of window was preempted, and did not finish, Emacs does not know the position of the end of display in that window. In that case, this function returns nil.

If update is non-nil, window-end always returns an up-to-date value for where the window ends, based on the current window-start value. If the saved value is valid, window-end returns that; otherwise it computes the correct value by scanning the buffer text.

Even if update is non-nil, window-end does not attempt to scroll the display if point has moved off the screen, the way real redisplay would do. It does not alter the window-start value. In effect, it reports where the displayed text will end if scrolling is not required.

Function: set-window-start window position &optional noforce

This function sets the display-start position of window to position in window's buffer. It returns 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 nil for noforce, it means you want display to start at 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.

For example, if point is 1 and you set the start of the window to 2, then point would be "above" the top of the window. The display routines will automatically move point if it is still 1 when redisplay occurs. Here is an example:

;; Here is what `foo' looks like before executing ;; the set-window-start expression. ---------- Buffer: foo ---------- -!-This is the contents of buffer foo. 2 3 4 5 6 ---------- Buffer: foo ---------- (set-window-start (selected-window) (1+ (window-start))) => 2 ;; Here is what `foo' looks like after executing ;; the set-window-start expression. ---------- Buffer: foo ---------- his is the contents of buffer foo. 2 3 -!-4 5 6 ---------- Buffer: foo ----------

If noforce is non-nil, and 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 position is not used.

Function: pos-visible-in-window-p &optional position window partially

This function returns t if position is within the range of text currently visible on the screen in window. It returns nil if position is scrolled vertically or horizontally out of view. Locations that are partially obscured are not considered visible unless partially is non-nil. The argument position defaults to the current position of point in window; window, to the selected window.

Here is an example:

(or (pos-visible-in-window-p (point) (selected-window)) (recenter 0))