GNU Info

(elisp)Window Start

---

Next: Textual Scrolling Prev: Window Point Up: Windows

---

Enter node , (file) or (file)node

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 Note: 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))