Restore updated copyright info that was inadvertently removed.
[emacs.git] / lispref / windows.texi
blob01d7d3bfb4bf83db57ddb6342d8ee2d1eb79494e
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c   Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/windows
7 @node Windows, Frames, Buffers, Top
8 @chapter Windows
10   This chapter describes most of the functions and variables related to
11 Emacs windows.  See @ref{Display}, for information on how text is
12 displayed in windows.
14 @menu
15 * Basic Windows::           Basic information on using windows.
16 * Splitting Windows::       Splitting one window into two windows.
17 * Deleting Windows::        Deleting a window gives its space to other windows.
18 * Selecting Windows::       The selected window is the one that you edit in.
19 * Cyclic Window Ordering::  Moving around the existing windows.
20 * Buffers and Windows::     Each window displays the contents of a buffer.
21 * Displaying Buffers::      Higher-level functions for displaying a buffer
22                               and choosing a window for it.
23 * Choosing Window::         How to choose a window for displaying a buffer.
24 * Window Point::            Each window has its own location of point.
25 * Window Start::            The display-start position controls which text
26                               is on-screen in the window.
27 * Textual Scrolling::       Moving text up and down through the window.
28 * Vertical Scrolling::      Moving the contents up and down on the window.
29 * Horizontal Scrolling::    Moving the contents sideways on the window.
30 * Size of Window::          Accessing the size of a window.
31 * Resizing Windows::        Changing the size of a window.
32 * Coordinates and Windows:: Converting coordinates to windows.
33 * Window Configurations::   Saving and restoring the state of the screen.
34 * Window Hooks::            Hooks for scrolling, window size changes,
35                               redisplay going past a certain point,
36                               or window configuration changes.
37 @end menu
39 @node Basic Windows
40 @section Basic Concepts of Emacs Windows
41 @cindex window
42 @cindex selected window
44   A @dfn{window} in Emacs is the physical area of the screen in which a
45 buffer is displayed.  The term is also used to refer to a Lisp object that
46 represents that screen area in Emacs Lisp.  It should be
47 clear from the context which is meant.
49   Emacs groups windows into frames.  A frame represents an area of
50 screen available for Emacs to use.  Each frame always contains at least
51 one window, but you can subdivide it vertically or horizontally into
52 multiple nonoverlapping Emacs windows.
54   In each frame, at any time, one and only one window is designated as
55 @dfn{selected within the frame}.  The frame's cursor appears in that
56 window.  At any time, one frame is the selected frame; and the window
57 selected within that frame is @dfn{the selected window}.  The selected
58 window's buffer is usually the current buffer (except when
59 @code{set-buffer} has been used).  @xref{Current Buffer}.
61   For practical purposes, a window exists only while it is displayed in
62 a frame.  Once removed from the frame, the window is effectively deleted
63 and should not be used, @emph{even though there may still be references
64 to it} from other Lisp objects.  Restoring a saved window configuration
65 is the only way for a window no longer on the screen to come back to
66 life.  (@xref{Deleting Windows}.)
68   Each window has the following attributes:
70 @itemize @bullet
71 @item
72 containing frame
74 @item
75 window height
77 @item
78 window width
80 @item
81 window edges with respect to the screen or frame
83 @item
84 the buffer it displays
86 @item
87 position within the buffer at the upper left of the window
89 @item
90 amount of horizontal scrolling, in columns
92 @item
93 point
95 @item
96 the mark
98 @item
99 how recently the window was selected
101 @item
102 fringe settings
104 @item
105 display margins
107 @item
108 scroll-bar settings
109 @end itemize
111 @cindex multiple windows
112   Users create multiple windows so they can look at several buffers at
113 once.  Lisp libraries use multiple windows for a variety of reasons, but
114 most often to display related information.  In Rmail, for example, you
115 can move through a summary buffer in one window while the other window
116 shows messages one at a time as they are reached.
118   The meaning of ``window'' in Emacs is similar to what it means in the
119 context of general-purpose window systems such as X, but not identical.
120 The X Window System places X windows on the screen; Emacs uses one or
121 more X windows as frames, and subdivides them into
122 Emacs windows.  When you use Emacs on a character-only terminal, Emacs
123 treats the whole terminal screen as one frame.
125 @cindex terminal screen
126 @cindex screen of terminal
127 @cindex tiled windows
128   Most window systems support arbitrarily located overlapping windows.
129 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
130 together they fill the whole screen or frame.  Because of the way in
131 which Emacs creates new windows and resizes them, not all conceivable
132 tilings of windows on an Emacs frame are actually possible.
133 @xref{Splitting Windows}, and @ref{Size of Window}.
135   @xref{Display}, for information on how the contents of the
136 window's buffer are displayed in the window.
138 @defun windowp object
139 This function returns @code{t} if @var{object} is a window.
140 @end defun
142 @node Splitting Windows
143 @section Splitting Windows
144 @cindex splitting windows
145 @cindex window splitting
147   The functions described here are the primitives used to split a window
148 into two windows.  Two higher level functions sometimes split a window,
149 but not always: @code{pop-to-buffer} and @code{display-buffer}
150 (@pxref{Displaying Buffers}).
152   The functions described here do not accept a buffer as an argument.
153 The two ``halves'' of the split window initially display the same buffer
154 previously visible in the window that was split.
156 @deffn Command split-window &optional window size horizontal
157 This function splits @var{window} into two windows.  The original
158 window @var{window} remains the selected window, but occupies only
159 part of its former screen area.  The rest is occupied by a newly created
160 window which is returned as the value of this function.
161 This function returns the newly created window.
163 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
164 two side by side windows.  The original window @var{window} keeps the
165 leftmost @var{size} columns, and gives the rest of the columns to the
166 new window.  Otherwise, it splits into windows one above the other, and
167 @var{window} keeps the upper @var{size} lines and gives the rest of the
168 lines to the new window.  The original window is therefore the
169 left-hand or upper of the two, and the new window is the right-hand or
170 lower.
172 If @var{window} is omitted or @code{nil}, then the selected window is
173 split.  If @var{size} is omitted or @code{nil}, then @var{window} is
174 divided evenly into two parts.  (If there is an odd line, it is
175 allocated to the new window.)  When @code{split-window} is called
176 interactively, all its arguments are @code{nil}.
178 If splitting would result in making a window that is smaller than
179 @code{window-min-height} or @code{window-min-width}, the function
180 signals an error and does not split the window at all.
182 The following example starts with one window on a screen that is 50
183 lines high by 80 columns wide; then it splits the window.
185 @smallexample
186 @group
187 (setq w (selected-window))
188      @result{} #<window 8 on windows.texi>
189 (window-edges)          ; @r{Edges in order:}
190      @result{} (0 0 80 50)     ;   @r{left--top--right--bottom}
191 @end group
193 @group
194 ;; @r{Returns window created}
195 (setq w2 (split-window w 15))
196      @result{} #<window 28 on windows.texi>
197 @end group
198 @group
199 (window-edges w2)
200      @result{} (0 15 80 50)    ; @r{Bottom window;}
201                         ;   @r{top is line 15}
202 @end group
203 @group
204 (window-edges w)
205      @result{} (0 0 80 15)     ; @r{Top window}
206 @end group
207 @end smallexample
209 The screen looks like this:
211 @smallexample
212 @group
213          __________
214         |          |  line 0
215         |    w     |
216         |__________|
217         |          |  line 15
218         |    w2    |
219         |__________|
220                       line 50
221  column 0   column 80
222 @end group
223 @end smallexample
225 Next, split the top window horizontally:
227 @smallexample
228 @group
229 (setq w3 (split-window w 35 t))
230      @result{} #<window 32 on windows.texi>
231 @end group
232 @group
233 (window-edges w3)
234      @result{} (35 0 80 15)  ; @r{Left edge at column 35}
235 @end group
236 @group
237 (window-edges w)
238      @result{} (0 0 35 15)   ; @r{Right edge at column 35}
239 @end group
240 @group
241 (window-edges w2)
242      @result{} (0 15 80 50)  ; @r{Bottom window unchanged}
243 @end group
244 @end smallexample
246 @need 3000
247 Now the screen looks like this:
249 @smallexample
250 @group
251      column 35
252          __________
253         |   |      |  line 0
254         | w |  w3  |
255         |___|______|
256         |          |  line 15
257         |    w2    |
258         |__________|
259                       line 50
260  column 0   column 80
261 @end group
262 @end smallexample
264 Normally, Emacs indicates the border between two side-by-side windows
265 with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
266 characters.  The display table can specify alternative border
267 characters; see @ref{Display Tables}.
268 @end deffn
270 @deffn Command split-window-vertically &optional size
271 This function splits the selected window into two windows, one above the
272 other, leaving the upper of the two windows selected, with @var{size}
273 lines.  (If @var{size} is negative, then the lower of the two windows
274 gets @minus{} @var{size} lines and the upper window gets the rest, but
275 the upper window is still the one selected.)
276 @end deffn
278 @deffn Command split-window-horizontally &optional size
279 This function splits the selected window into two windows
280 side-by-side, leaving the selected window with @var{size} columns.
282 This function is basically an interface to @code{split-window}.
283 You could define a simplified version of the function like this:
285 @smallexample
286 @group
287 (defun split-window-horizontally (&optional arg)
288   "Split selected window into two windows, side by side..."
289   (interactive "P")
290 @end group
291 @group
292   (let ((size (and arg (prefix-numeric-value arg))))
293     (and size (< size 0)
294          (setq size (+ (window-width) size)))
295     (split-window nil size t)))
296 @end group
297 @end smallexample
298 @end deffn
300 @defun one-window-p &optional no-mini all-frames
301 This function returns non-@code{nil} if there is only one window.  The
302 argument @var{no-mini}, if non-@code{nil}, means don't count the
303 minibuffer even if it is active; otherwise, the minibuffer window is
304 counted when it is active.
306 The argument @var{all-frames} specifies which frames to consider.  Here
307 are the possible values and their meanings:
309 @table @asis
310 @item @code{nil}
311 Count the windows in the selected frame, plus the minibuffer used
312 by that frame even if it lies in some other frame.
314 @item @code{t}
315 Count all windows in all existing frames.
317 @item @code{visible}
318 Count all windows in all visible frames.
320 @item 0
321 Count all windows in all visible or iconified frames.
323 @item anything else
324 Count precisely the windows in the selected frame, and no others.
325 @end table
326 @end defun
328 @node Deleting Windows
329 @section Deleting Windows
330 @cindex deleting windows
332 A window remains visible on its frame unless you @dfn{delete} it by
333 calling certain functions that delete windows.  A deleted window cannot
334 appear on the screen, but continues to exist as a Lisp object until
335 there are no references to it.  There is no way to cancel the deletion
336 of a window aside from restoring a saved window configuration
337 (@pxref{Window Configurations}).  Restoring a window configuration also
338 deletes any windows that aren't part of that configuration.
340   When you delete a window, the space it took up is given to one
341 adjacent sibling.
343 @c Emacs 19 feature
344 @defun window-live-p window
345 This function returns @code{nil} if @var{window} is deleted, and
346 @code{t} otherwise.
348 @strong{Warning:} Erroneous information or fatal errors may result from
349 using a deleted window as if it were live.
350 @end defun
352 @deffn Command delete-window &optional window
353 This function removes @var{window} from display, and returns @code{nil}.
354 If @var{window} is omitted, then the selected window is deleted.  An
355 error is signaled if there is only one window when @code{delete-window}
356 is called.
357 @end deffn
359 @deffn Command delete-other-windows &optional window
360 This function makes @var{window} the only window on its frame, by
361 deleting the other windows in that frame.  If @var{window} is omitted or
362 @code{nil}, then the selected window is used by default.
364 The return value is @code{nil}.
365 @end deffn
367 @deffn Command delete-windows-on buffer &optional frame
368 This function deletes all windows showing @var{buffer}.  If there are
369 no windows showing @var{buffer}, it does nothing.
371 @code{delete-windows-on} operates frame by frame.  If a frame has
372 several windows showing different buffers, then those showing
373 @var{buffer} are removed, and the others expand to fill the space.  If
374 all windows in some frame are showing @var{buffer} (including the case
375 where there is only one window), then the frame reverts to having a
376 single window showing another buffer chosen with @code{other-buffer}.
377 @xref{The Buffer List}.
379 The argument @var{frame} controls which frames to operate on.  This
380 function does not use it in quite the same way as the other functions
381 which scan all windows; specifically, the values @code{t} and @code{nil}
382 have the opposite of their meanings in other functions.  Here are the
383 full details:
385 @itemize @bullet
386 @item
387 If it is @code{nil}, operate on all frames.
388 @item
389 If it is @code{t}, operate on the selected frame.
390 @item
391 If it is @code{visible}, operate on all visible frames.
392 @item
393 If it is 0, operate on all visible or iconified frames.
394 @item
395 If it is a frame, operate on that frame.
396 @end itemize
398 This function always returns @code{nil}.
399 @end deffn
401 @node Selecting Windows
402 @section Selecting Windows
403 @cindex selecting windows
405   When a window is selected, the buffer in the window becomes the current
406 buffer, and the cursor will appear in it.
408 @defun selected-window
409 This function returns the selected window.  This is the window in
410 which the cursor appears and to which many commands apply.
411 @end defun
413 @defun select-window window &optional norecord
414 This function makes @var{window} the selected window.  The cursor then
415 appears in @var{window} (on redisplay).  The buffer being displayed in
416 @var{window} is immediately designated the current buffer.
418 Normally @var{window}'s selected buffer is moved to the front of the
419 buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
420 order is unchanged.
422 The return value is @var{window}.
424 @example
425 @group
426 (setq w (next-window))
427 (select-window w)
428      @result{} #<window 65 on windows.texi>
429 @end group
430 @end example
431 @end defun
433 @defmac save-selected-window forms@dots{}
434 This macro records the selected window of each frame, executes
435 @var{forms} in sequence, then restores the earlier selected windows.
437 This macro does not save or restore anything about the sizes,
438 arrangement or contents of windows; therefore, if the @var{forms}
439 change them, the change persists.  If the previously selected window
440 of some frame is no longer live at the time of exit from this form,
441 that frame's selected window is left alone.
442 @end defmac
444 @defmac with-selected-window window forms@dots{}
445 This macro selects @var{window} (without changing the buffer list),
446 executes @var{forms} in sequence, then restores the previously
447 selected window (unless that window is no longer alive).  It is similar
448 to @code{save-selected-window} except that it explicitly selects
449 @var{window} and that it does not alter the buffer list sequence.
450 @end defmac
452 @cindex finding windows
453   The following functions choose one of the windows on the screen,
454 offering various criteria for the choice.
456 @defun get-lru-window &optional frame
457 This function returns the window least recently ``used'' (that is,
458 selected).  If any full-width windows are present, it only considers
459 these.  The selected window is always the most recently used window.
461 The selected window can be the least recently used window if it is the
462 only window.  A newly created window becomes the least recently used
463 window until it is selected.  A minibuffer window is never a candidate.
465 The argument @var{frame} controls which windows are considered.
467 @itemize @bullet
468 @item
469 If it is @code{nil}, consider windows on the selected frame.
470 @item
471 If it is @code{t}, consider windows on all frames.
472 @item
473 If it is @code{visible}, consider windows on all visible frames.
474 @item
475 If it is 0, consider windows on all visible or iconified frames.
476 @item
477 If it is a frame, consider windows on that frame.
478 @end itemize
479 @end defun
481 @defun get-largest-window &optional frame
482 This function returns the window with the largest area (height times
483 width).  If there are no side-by-side windows, then this is the window
484 with the most lines.  A minibuffer window is never a candidate.
486 If there are two windows of the same size, then the function returns
487 the window that is first in the cyclic ordering of windows (see
488 following section), starting from the selected window.
490 The argument @var{frame} controls which set of windows to
491 consider.  See @code{get-lru-window}, above.
492 @end defun
494 @cindex window that satisfies a predicate
495 @cindex conditional selection of windows
496 @defun get-window-with-predicate predicate &optional minibuf all-frames default
497 This function returns a window satisfying @var{predicate}.  It cycles
498 through all visible windows using @code{walk-windows} (@pxref{Cyclic
499 Window Ordering}), calling @var{predicate} on each one of them
500 with that window as its argument.  The function returns the first
501 window for which @var{predicate} returns a non-@code{nil} value; if
502 that never happens, it returns @var{default}.
504 The optional arguments @var{minibuf} and @var{all-frames} specify the
505 set of windows to include in the scan.  See the description of
506 @code{next-window} in @ref{Cyclic Window Ordering}, for details.
507 @end defun
509 @node Cyclic Window Ordering
510 @comment  node-name,  next,  previous,  up
511 @section Cyclic Ordering of Windows
512 @cindex cyclic ordering of windows
513 @cindex ordering of windows, cyclic
514 @cindex window ordering, cyclic
516   When you use the command @kbd{C-x o} (@code{other-window}) to select
517 the next window, it moves through all the windows on the screen in a
518 specific cyclic order.  For any given configuration of windows, this
519 order never varies.  It is called the @dfn{cyclic ordering of windows}.
521   This ordering generally goes from top to bottom, and from left to
522 right.  But it may go down first or go right first, depending on the
523 order in which the windows were split.
525   If the first split was vertical (into windows one above each other),
526 and then the subwindows were split horizontally, then the ordering is
527 left to right in the top of the frame, and then left to right in the
528 next lower part of the frame, and so on.  If the first split was
529 horizontal, the ordering is top to bottom in the left part, and so on.
530 In general, within each set of siblings at any level in the window tree,
531 the order is left to right, or top to bottom.
533 @defun next-window &optional window minibuf all-frames
534 @cindex minibuffer window
535 This function returns the window following @var{window} in the cyclic
536 ordering of windows.  This is the window that @kbd{C-x o} would select
537 if typed when @var{window} is selected.  If @var{window} is the only
538 window visible, then this function returns @var{window}.  If omitted,
539 @var{window} defaults to the selected window.
541 The value of the argument @var{minibuf} determines whether the
542 minibuffer is included in the window order.  Normally, when
543 @var{minibuf} is @code{nil}, the minibuffer is included if it is
544 currently active; this is the behavior of @kbd{C-x o}.  (The minibuffer
545 window is active while the minibuffer is in use.  @xref{Minibuffers}.)
547 If @var{minibuf} is @code{t}, then the cyclic ordering includes the
548 minibuffer window even if it is not active.
550 If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
551 window is not included even if it is active.
553 The argument @var{all-frames} specifies which frames to consider.  Here
554 are the possible values and their meanings:
556 @table @asis
557 @item @code{nil}
558 Consider all the windows in @var{window}'s frame, plus the minibuffer
559 used by that frame even if it lies in some other frame.
561 @item @code{t}
562 Consider all windows in all existing frames.
564 @item @code{visible}
565 Consider all windows in all visible frames.  (To get useful results, you
566 must ensure @var{window} is in a visible frame.)
568 @item 0
569 Consider all windows in all visible or iconified frames.
571 @item a frame
572 Consider all windows on that frame.
574 @item anything else
575 Consider precisely the windows in @var{window}'s frame, and no others.
576 @end table
578 This example assumes there are two windows, both displaying the
579 buffer @samp{windows.texi}:
581 @example
582 @group
583 (selected-window)
584      @result{} #<window 56 on windows.texi>
585 @end group
586 @group
587 (next-window (selected-window))
588      @result{} #<window 52 on windows.texi>
589 @end group
590 @group
591 (next-window (next-window (selected-window)))
592      @result{} #<window 56 on windows.texi>
593 @end group
594 @end example
595 @end defun
597 @defun previous-window &optional window minibuf all-frames
598 This function returns the window preceding @var{window} in the cyclic
599 ordering of windows.  The other arguments specify which windows to
600 include in the cycle, as in @code{next-window}.
601 @end defun
603 @deffn Command other-window count &optional all-frames
604 This function selects the @var{count}th following window in the cyclic
605 order.  If count is negative, then it moves back @minus{}@var{count}
606 windows in the cycle, rather than forward.  It returns @code{nil}.
608 The argument @var{all-frames} has the same meaning as in
609 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
610 is always effectively @code{nil}.
612 In an interactive call, @var{count} is the numeric prefix argument.
613 @end deffn
615 @c Emacs 19 feature
616 @defun walk-windows proc &optional minibuf all-frames
617 This function cycles through all windows, calling @code{proc}
618 once for each window with the window as its sole argument.
620 The optional arguments @var{minibuf} and @var{all-frames} specify the
621 set of windows to include in the scan.  See @code{next-window}, above,
622 for details.
623 @end defun
625 @defun window-list &optional frame minibuf window
626 This function returns a list of the windows on @var{frame}, starting
627 with @var{window}.  If @var{frame} is @code{nil} or omitted, the
628 selected frame is used instead; if @var{window} is @code{nil} or
629 omitted, the selected window is used instead.
631 The value of @var{minibuf} determines if the minibuffer window will be
632 included in the result list.  If @var{minibuf} is @code{t}, the
633 minibuffer window will be included, even if it isn't active.  If
634 @var{minibuf} is @code{nil} or omitted, the minibuffer window will
635 only be included in the list if it is active.  If @var{minibuf} is
636 neither @code{nil} nor @code{t}, the minibuffer window is not
637 included, whether or not it is active.
638 @end defun
640 @node Buffers and Windows
641 @section Buffers and Windows
642 @cindex examining windows
643 @cindex windows, controlling precisely
644 @cindex buffers, controlled in windows
646   This section describes low-level functions to examine windows or to
647 display buffers in windows in a precisely controlled fashion.
648 @iftex
649 See the following section for
650 @end iftex
651 @ifnottex
652 @xref{Displaying Buffers}, for
653 @end ifnottex
654 related functions that find a window to use and specify a buffer for it.
655 The functions described there are easier to use than these, but they
656 employ heuristics in choosing or creating a window; use these functions
657 when you need complete control.
659 @defun set-window-buffer window buffer-or-name &optional keep-margins
660 This function makes @var{window} display @var{buffer-or-name} as its
661 contents.  It returns @code{nil}.  This is the fundamental primitive
662 for changing which buffer is displayed in a window, and all ways
663 of doing that call this function.
665 @example
666 @group
667 (set-window-buffer (selected-window) "foo")
668      @result{} nil
669 @end group
670 @end example
672 Normally, displaying @var{buffer} in @var{window} resets the window's
673 display margins, fringe widths, scroll bar settings, and position
674 based on the local variables of @var{buffer}.  However, if
675 @var{keep-margins} is non-@code{nil}, the display margins and fringe
676 widths of @var{window} remain unchanged.  @xref{Fringes}.
677 @end defun
679 @defun window-buffer &optional window
680 This function returns the buffer that @var{window} is displaying.  If
681 @var{window} is omitted, this function returns the buffer for the
682 selected window.
684 @example
685 @group
686 (window-buffer)
687      @result{} #<buffer windows.texi>
688 @end group
689 @end example
690 @end defun
692 @defun get-buffer-window buffer-or-name &optional all-frames
693 This function returns a window currently displaying
694 @var{buffer-or-name}, or @code{nil} if there is none.  If there are
695 several such windows, then the function returns the first one in the
696 cyclic ordering of windows, starting from the selected window.
697 @xref{Cyclic Window Ordering}.
699 The argument @var{all-frames} controls which windows to consider.
701 @itemize @bullet
702 @item
703 If it is @code{nil}, consider windows on the selected frame.
704 @item
705 If it is @code{t}, consider windows on all frames.
706 @item
707 If it is @code{visible}, consider windows on all visible frames.
708 @item
709 If it is 0, consider windows on all visible or iconified frames.
710 @item
711 If it is a frame, consider windows on that frame.
712 @end itemize
713 @end defun
715 @defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
716 This function returns a list of all the windows currently displaying
717 @var{buffer-or-name}.
719 The two optional arguments work like the optional arguments of
720 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
721 like the single optional argument of @code{get-buffer-window}.  Perhaps
722 we should change @code{get-buffer-window} in the future to make it
723 compatible with the other functions.
724 @end defun
726 @defvar buffer-display-time
727 This variable records the time at which a buffer was last made visible
728 in a window.  It is always local in each buffer; each time
729 @code{set-window-buffer} is called, it sets this variable to
730 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
731 When a buffer is first created, @code{buffer-display-time} starts out
732 with the value @code{nil}.
733 @end defvar
735 @node Displaying Buffers
736 @section Displaying Buffers in Windows
737 @cindex switching to a buffer
738 @cindex displaying a buffer
740   In this section we describe convenient functions that choose a window
741 automatically and use it to display a specified buffer.  These functions
742 can also split an existing window in certain circumstances.  We also
743 describe variables that parameterize the heuristics used for choosing a
744 window.
745 @iftex
746 See the preceding section for
747 @end iftex
748 @ifnottex
749 @xref{Buffers and Windows}, for
750 @end ifnottex
751 low-level functions that give you more precise control.  All of these
752 functions work by calling @code{set-window-buffer}.
754   Do not use the functions in this section in order to make a buffer
755 current so that a Lisp program can access or modify it; they are too
756 drastic for that purpose, since they change the display of buffers in
757 windows, which would be gratuitous and surprise the user.  Instead, use
758 @code{set-buffer} and @code{save-current-buffer} (@pxref{Current
759 Buffer}), which designate buffers as current for programmed access
760 without affecting the display of buffers in windows.
762 @deffn Command switch-to-buffer buffer-or-name &optional norecord
763 This function makes @var{buffer-or-name} the current buffer, and also
764 displays the buffer in the selected window.  This means that a human can
765 see the buffer and subsequent keyboard commands will apply to it.
766 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
767 the current buffer but does not display it in the selected window.
768 @xref{Current Buffer}.
770 If @var{buffer-or-name} does not identify an existing buffer, then a new
771 buffer by that name is created.  The major mode for the new buffer is
772 set according to the variable @code{default-major-mode}.  @xref{Auto
773 Major Mode}.
775 Normally the specified buffer is put at the front of the buffer list
776 (both the selected frame's buffer list and the frame-independent buffer
777 list).  This affects the operation of @code{other-buffer}.  However, if
778 @var{norecord} is non-@code{nil}, this is not done.  @xref{The Buffer
779 List}.
781 The @code{switch-to-buffer} function is often used interactively, as
782 the binding of @kbd{C-x b}.  It is also used frequently in programs.  It
783 returns the buffer that it switched to.
784 @end deffn
786 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
787 This function makes @var{buffer-or-name} the current buffer and
788 displays it in a window not currently selected.  It then selects that
789 window.  The handling of the buffer is the same as in
790 @code{switch-to-buffer}.
792 The currently selected window is absolutely never used to do the job.
793 If it is the only window, then it is split to make a distinct window for
794 this purpose.  If the selected window is already displaying the buffer,
795 then it continues to do so, but another window is nonetheless found to
796 display it in as well.
798 This function updates the buffer list just like @code{switch-to-buffer}
799 unless @var{norecord} is non-@code{nil}.
800 @end deffn
802 @defun pop-to-buffer buffer-or-name &optional other-window norecord
803 This function makes @var{buffer-or-name} the current buffer and
804 switches to it in some window, preferably not the window previously
805 selected.  The ``popped-to'' window becomes the selected window within
806 its frame.  The return value is the buffer that was switched to.
807 If @var{buffer-or-name} is @code{nil}, that means to choose some
808 other buffer, but you don't specify which.
810 If the variable @code{pop-up-frames} is non-@code{nil},
811 @code{pop-to-buffer} looks for a window in any visible frame already
812 displaying the buffer; if there is one, it returns that window and makes
813 it be selected within its frame.  If there is none, it creates a new
814 frame and displays the buffer in it.
816 If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
817 operates entirely within the selected frame.  (If the selected frame has
818 just a minibuffer, @code{pop-to-buffer} operates within the most
819 recently selected frame that was not just a minibuffer.)
821 If the variable @code{pop-up-windows} is non-@code{nil}, windows may
822 be split to create a new window that is different from the original
823 window.  For details, see @ref{Choosing Window}.
825 If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
826 creates another window even if @var{buffer-or-name} is already visible
827 in the selected window.  Thus @var{buffer-or-name} could end up
828 displayed in two windows.  On the other hand, if @var{buffer-or-name} is
829 already displayed in the selected window and @var{other-window} is
830 @code{nil}, then the selected window is considered sufficient display
831 for @var{buffer-or-name}, so that nothing needs to be done.
833 All the variables that affect @code{display-buffer} affect
834 @code{pop-to-buffer} as well.  @xref{Choosing Window}.
836 If @var{buffer-or-name} is a string that does not name an existing
837 buffer, a buffer by that name is created.  The major mode for the new
838 buffer is set according to the variable @code{default-major-mode}.
839 @xref{Auto Major Mode}.
841 This function updates the buffer list just like @code{switch-to-buffer}
842 unless @var{norecord} is non-@code{nil}.
843 @end defun
845 @deffn Command replace-buffer-in-windows buffer
846 This function replaces @var{buffer} with some other buffer in all
847 windows displaying it.  The other buffer used is chosen with
848 @code{other-buffer}.  In the usual applications of this function, you
849 don't care which other buffer is used; you just want to make sure that
850 @var{buffer} is no longer displayed.
852 This function returns @code{nil}.
853 @end deffn
855 @node Choosing Window
856 @section Choosing a Window for Display
858   This section describes the basic facility that chooses a window to
859 display a buffer in---@code{display-buffer}.  All the higher-level
860 functions and commands use this subroutine.  Here we describe how to use
861 @code{display-buffer} and how to customize it.
863 @deffn Command display-buffer buffer-or-name &optional not-this-window frame
864 This command makes @var{buffer-or-name} appear in some window, like
865 @code{pop-to-buffer}, but it does not select that window and does not
866 make the buffer current.  The identity of the selected window is
867 unaltered by this function.
869 If @var{not-this-window} is non-@code{nil}, it means to display the
870 specified buffer in a window other than the selected one, even if it is
871 already on display in the selected window.  This can cause the buffer to
872 appear in two windows at once.  Otherwise, if @var{buffer-or-name} is
873 already being displayed in any window, that is good enough, so this
874 function does nothing.
876 @code{display-buffer} returns the window chosen to display
877 @var{buffer-or-name}.
879 If the argument @var{frame} is non-@code{nil}, it specifies which frames
880 to check when deciding whether the buffer is already displayed.  If the
881 buffer is already displayed in some window on one of these frames,
882 @code{display-buffer} simply returns that window.  Here are the possible
883 values of @var{frame}:
885 @itemize @bullet
886 @item
887 If it is @code{nil}, consider windows on the selected frame.
888 @item
889 If it is @code{t}, consider windows on all frames.
890 @item
891 If it is @code{visible}, consider windows on all visible frames.
892 @item
893 If it is 0, consider windows on all visible or iconified frames.
894 @item
895 If it is a frame, consider windows on that frame.
896 @end itemize
898 Precisely how @code{display-buffer} finds or creates a window depends on
899 the variables described below.
900 @end deffn
902 @defopt display-buffer-reuse-frames
903 If this variable is non-@code{nil}, @code{display-buffer} searches
904 existing frames for a window displaying the buffer.  If the buffer is
905 already displayed in a window in some frame, @code{display-buffer} makes
906 the frame visible and raises it, to use that window.  If the buffer is
907 not already displayed, or if @code{display-buffer-reuse-frames} is
908 @code{nil}, @code{display-buffer}'s behavior is determined by other
909 variables, described below.
910 @end defopt
912 @defopt pop-up-windows
913 This variable controls whether @code{display-buffer} makes new windows.
914 If it is non-@code{nil} and there is only one window, then that window
915 is split.  If it is @code{nil}, then @code{display-buffer} does not
916 split the single window, but uses it whole.
917 @end defopt
919 @defopt split-height-threshold
920 This variable determines when @code{display-buffer} may split a window,
921 if there are multiple windows.  @code{display-buffer} always splits the
922 largest window if it has at least this many lines.  If the largest
923 window is not this tall, it is split only if it is the sole window and
924 @code{pop-up-windows} is non-@code{nil}.
925 @end defopt
927 @defopt even-window-heights
928 This variable determines if @code{display-buffer} should even out window
929 heights if the buffer gets displayed in an existing window, above or
930 beneath another existing window.  If @code{even-window-heights} is
931 @code{t}, the default, window heights will be evened out.  If
932 @code{even-window-heights} is @code{nil}, the original window heights
933 will be left alone.
934 @end defopt
936 @c Emacs 19 feature
937 @defopt pop-up-frames
938 This variable controls whether @code{display-buffer} makes new frames.
939 If it is non-@code{nil}, @code{display-buffer} looks for an existing
940 window already displaying the desired buffer, on any visible frame.  If
941 it finds one, it returns that window.  Otherwise it makes a new frame.
942 The variables @code{pop-up-windows} and @code{split-height-threshold} do
943 not matter if @code{pop-up-frames} is non-@code{nil}.
945 If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
946 splits a window or reuses one.
948 @xref{Frames}, for more information.
949 @end defopt
951 @c Emacs 19 feature
952 @defopt pop-up-frame-function
953 This variable specifies how to make a new frame if @code{pop-up-frames}
954 is non-@code{nil}.
956 Its value should be a function of no arguments.  When
957 @code{display-buffer} makes a new frame, it does so by calling that
958 function, which should return a frame.  The default value of the
959 variable is a function that creates a frame using parameters from
960 @code{pop-up-frame-alist}.
961 @end defopt
963 @defopt pop-up-frame-alist
964 This variable holds an alist specifying frame parameters used when
965 @code{display-buffer} makes a new frame.  @xref{Frame Parameters}, for
966 more information about frame parameters.
967 @end defopt
969 @defopt special-display-buffer-names
970 A list of buffer names for buffers that should be displayed specially.
971 If the buffer's name is in this list, @code{display-buffer} handles the
972 buffer specially.
974 By default, special display means to give the buffer a dedicated frame.
976 If an element is a list, instead of a string, then the @sc{car} of the
977 list is the buffer name, and the rest of the list says how to create
978 the frame.  There are two possibilities for the rest of the list (its
979 @sc{cdr}).  It can be an alist, specifying frame parameters, or it can
980 contain a function and arguments to give to it.  (The function's first
981 argument is always the buffer to be displayed; the arguments from the
982 list come after that.)
984 For example:
986 @example
987 (("myfile" (minibuffer) (menu-bar-lines . 0)))
988 @end example
990 @noindent
991 specifies to display a buffer named @samp{myfile} in a dedicated frame
992 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
994 The list of frame parameters can also use the phony frame parameters
995 @code{same-frame} and @code{same-window}.  If the specified frame
996 parameters include @code{(same-window . @var{value})} and @var{value}
997 is non-@code{nil}, that means to display the buffer in the current
998 selected window.  Otherwise, if they include @code{(same-frame .
999 @var{value})} and @var{value} is non-@code{nil}, that means to display
1000 the buffer in a new window in the currently selected frame.
1001 @end defopt
1003 @defopt special-display-regexps
1004 A list of regular expressions that specify buffers that should be
1005 displayed specially.  If the buffer's name matches any of the regular
1006 expressions in this list, @code{display-buffer} handles the buffer
1007 specially.
1009 By default, special display means to give the buffer a dedicated frame.
1011 If an element is a list, instead of a string, then the @sc{car} of the
1012 list is the regular expression, and the rest of the list says how to
1013 create the frame.  See above, under @code{special-display-buffer-names}.
1014 @end defopt
1016 @defun special-display-p buffer-name
1017 This function returns non-@code{nil} if displaying a buffer
1018 named @var{buffer-name} with @code{display-buffer} would
1019 create a special frame.  The value is @code{t} if it would
1020 use the default frame paramaters, or else the specified list
1021 of frame parameters.
1022 @end defun
1024 @defvar special-display-function
1025 This variable holds the function to call to display a buffer specially.
1026 It receives the buffer as an argument, and should return the window in
1027 which it is displayed.
1029 The default value of this variable is
1030 @code{special-display-popup-frame}.
1031 @end defvar
1033 @defun special-display-popup-frame buffer &rest args
1034 This function makes @var{buffer} visible in a frame of its own.  If
1035 @var{buffer} is already displayed in a window in some frame, it makes
1036 the frame visible and raises it, to use that window.  Otherwise, it
1037 creates a frame that will be dedicated to @var{buffer}.
1039 If @var{args} is an alist, it specifies frame parameters for the new
1040 frame.
1042 If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
1043 @var{args})} is called as a function to actually create and set up the
1044 frame; it is called with @var{buffer} as first argument, and @code{(cdr
1045 @var{args})} as additional arguments.
1047 This function always uses an existing window displaying @var{buffer},
1048 whether or not it is in a frame of its own; but if you set up the above
1049 variables in your init file, before @var{buffer} was created, then
1050 presumably the window was previously made by this function.
1051 @end defun
1053 @defopt special-display-frame-alist
1054 This variable holds frame parameters for
1055 @code{special-display-popup-frame} to use when it creates a frame.
1056 @end defopt
1058 @defopt same-window-buffer-names
1059 A list of buffer names for buffers that should be displayed in the
1060 selected window.  If the buffer's name is in this list,
1061 @code{display-buffer} handles the buffer by switching to it in the
1062 selected window.
1063 @end defopt
1065 @defopt same-window-regexps
1066 A list of regular expressions that specify buffers that should be
1067 displayed in the selected window.  If the buffer's name matches any of
1068 the regular expressions in this list, @code{display-buffer} handles the
1069 buffer by switching to it in the selected window.
1070 @end defopt
1072 @defun same-window-p buffer-name
1073 This function returns @code{t} if displaying a buffer
1074 named @var{buffer-name} with @code{display-buffer} would
1075 put it in the selected window.
1076 @end defun
1078 @c Emacs 19 feature
1079 @defvar display-buffer-function
1080 This variable is the most flexible way to customize the behavior of
1081 @code{display-buffer}.  If it is non-@code{nil}, it should be a function
1082 that @code{display-buffer} calls to do the work.  The function should
1083 accept two arguments, the same two arguments that @code{display-buffer}
1084 received.  It should choose or create a window, display the specified
1085 buffer, and then return the window.
1087 This hook takes precedence over all the other options and hooks
1088 described above.
1089 @end defvar
1091 @c Emacs 19 feature
1092 @cindex dedicated window
1093 A window can be marked as ``dedicated'' to its buffer.  Then
1094 @code{display-buffer} will not try to use that window to display any
1095 other buffer.
1097 @defun window-dedicated-p window
1098 This function returns non-@code{nil} if @var{window} is marked as
1099 dedicated; otherwise @code{nil}.
1100 @end defun
1102 @defun set-window-dedicated-p window flag
1103 This function marks @var{window} as dedicated if @var{flag} is
1104 non-@code{nil}, and nondedicated otherwise.
1105 @end defun
1107 @node Window Point
1108 @section Windows and Point
1109 @cindex window position
1110 @cindex window point
1111 @cindex position in window
1112 @cindex point in window
1114   Each window has its own value of point, independent of the value of
1115 point in other windows displaying the same buffer.  This makes it useful
1116 to have multiple windows showing one buffer.
1118 @itemize @bullet
1119 @item
1120 The window point is established when a window is first created; it is
1121 initialized from the buffer's point, or from the window point of another
1122 window opened on the buffer if such a window exists.
1124 @item
1125 Selecting a window sets the value of point in its buffer from the
1126 window's value of point.  Conversely, deselecting a window sets the
1127 window's value of point from that of the buffer.  Thus, when you switch
1128 between windows that display a given buffer, the point value for the
1129 selected window is in effect in the buffer, while the point values for
1130 the other windows are stored in those windows.
1132 @item
1133 As long as the selected window displays the current buffer, the window's
1134 point and the buffer's point always move together; they remain equal.
1136 @item
1137 @xref{Positions}, for more details on buffer positions.
1138 @end itemize
1140   As far as the user is concerned, point is where the cursor is, and
1141 when the user switches to another buffer, the cursor jumps to the
1142 position of point in that buffer.
1144 @defun window-point &optional window
1145 This function returns the current position of point in @var{window}.
1146 For a nonselected window, this is the value point would have (in that
1147 window's buffer) if that window were selected.  If @var{window} is
1148 @code{nil}, the selected window is used.
1150 When @var{window} is the selected window and its buffer is also the
1151 current buffer, the value returned is the same as point in that buffer.
1153 Strictly speaking, it would be more correct to return the
1154 ``top-level'' value of point, outside of any @code{save-excursion}
1155 forms.  But that value is hard to find.
1156 @end defun
1158 @defun set-window-point window position
1159 This function positions point in @var{window} at position
1160 @var{position} in @var{window}'s buffer.
1161 @end defun
1163 @node Window Start
1164 @section The Window Start Position
1166   Each window contains a marker used to keep track of a buffer position
1167 that specifies where in the buffer display should start.  This position
1168 is called the @dfn{display-start} position of the window (or just the
1169 @dfn{start}).  The character after this position is the one that appears
1170 at the upper left corner of the window.  It is usually, but not
1171 inevitably, at the beginning of a text line.
1173 @defun window-start &optional window
1174 @cindex window top line
1175 This function returns the display-start position of window
1176 @var{window}.  If @var{window} is @code{nil}, the selected window is
1177 used.  For example,
1179 @example
1180 @group
1181 (window-start)
1182      @result{} 7058
1183 @end group
1184 @end example
1186 When you create a window, or display a different buffer in it, the
1187 display-start position is set to a display-start position recently used
1188 for the same buffer, or 1 if the buffer doesn't have any.
1190 Redisplay updates the window-start position (if you have not specified
1191 it explicitly since the previous redisplay)---for example, to make sure
1192 point appears on the screen.  Nothing except redisplay automatically
1193 changes the window-start position; if you move point, do not expect the
1194 window-start position to change in response until after the next
1195 redisplay.
1197 For a realistic example of using @code{window-start}, see the
1198 description of @code{count-lines} in @ref{Text Lines}.
1199 @end defun
1201 @defun window-end &optional window update
1202 This function returns the position of the end of the display in window
1203 @var{window}.  If @var{window} is @code{nil}, the selected window is
1204 used.
1206 Simply changing the buffer text or moving point does not update the
1207 value that @code{window-end} returns.  The value is updated only when
1208 Emacs redisplays and redisplay completes without being preempted.
1210 If the last redisplay of @var{window} was preempted, and did not finish,
1211 Emacs does not know the position of the end of display in that window.
1212 In that case, this function returns @code{nil}.
1214 If @var{update} is non-@code{nil}, @code{window-end} always returns an
1215 up-to-date value for where the window ends, based on the current
1216 @code{window-start} value.  If the saved value is valid,
1217 @code{window-end} returns that; otherwise it computes the correct
1218 value by scanning the buffer text.
1220 Even if @var{update} is non-@code{nil}, @code{window-end} does not
1221 attempt to scroll the display if point has moved off the screen, the
1222 way real redisplay would do.  It does not alter the
1223 @code{window-start} value.  In effect, it reports where the displayed
1224 text will end if scrolling is not required.
1225 @end defun
1227 @defun set-window-start window position &optional noforce
1228 This function sets the display-start position of @var{window} to
1229 @var{position} in @var{window}'s buffer.  It returns @var{position}.
1231 The display routines insist that the position of point be visible when a
1232 buffer is displayed.  Normally, they change the display-start position
1233 (that is, scroll the window) whenever necessary to make point visible.
1234 However, if you specify the start position with this function using
1235 @code{nil} for @var{noforce}, it means you want display to start at
1236 @var{position} even if that would put the location of point off the
1237 screen.  If this does place point off screen, the display routines move
1238 point to the left margin on the middle line in the window.
1240 For example, if point @w{is 1} and you set the start of the window @w{to
1241 2}, then point would be ``above'' the top of the window.  The display
1242 routines will automatically move point if it is still 1 when redisplay
1243 occurs.  Here is an example:
1245 @example
1246 @group
1247 ;; @r{Here is what @samp{foo} looks like before executing}
1248 ;;   @r{the @code{set-window-start} expression.}
1249 @end group
1251 @group
1252 ---------- Buffer: foo ----------
1253 @point{}This is the contents of buffer foo.
1259 ---------- Buffer: foo ----------
1260 @end group
1262 @group
1263 (set-window-start
1264  (selected-window)
1265  (1+ (window-start)))
1266 @result{} 2
1267 @end group
1269 @group
1270 ;; @r{Here is what @samp{foo} looks like after executing}
1271 ;;   @r{the @code{set-window-start} expression.}
1272 ---------- Buffer: foo ----------
1273 his is the contents of buffer foo.
1276 @point{}4
1279 ---------- Buffer: foo ----------
1280 @end group
1281 @end example
1283 If @var{noforce} is non-@code{nil}, and @var{position} would place point
1284 off screen at the next redisplay, then redisplay computes a new window-start
1285 position that works well with point, and thus @var{position} is not used.
1286 @end defun
1288 @defun pos-visible-in-window-p &optional position window partially
1289 This function returns @code{t} if @var{position} is within the range of
1290 text currently visible on the screen in @var{window}.  It returns
1291 @code{nil} if @var{position} is scrolled vertically or horizontally out
1292 of view.  Locations that are partially obscured are not considered
1293 visible unless @var{partially} is non-@code{nil}.  The argument
1294 @var{position} defaults to the current position of point in
1295 @var{window}; @var{window}, to the selected window.
1297 Here is an example:
1299 @example
1300 @group
1301 (or (pos-visible-in-window-p
1302      (point) (selected-window))
1303     (recenter 0))
1304 @end group
1305 @end example
1306 @end defun
1308 @node Textual Scrolling
1309 @section Textual Scrolling
1310 @cindex textual scrolling
1311 @cindex scrolling textually
1313   @dfn{Textual scrolling} means moving the text up or down though a
1314 window.  It works by changing the value of the window's display-start
1315 location.  It may also change the value of @code{window-point} to keep
1316 point on the screen.
1318   Textual scrolling was formerly called ``vertical scrolling,'' but we
1319 changed its name to distinguish it from the new vertical fractional
1320 scrolling feature (@pxref{Vertical Scrolling}).
1322   In the commands @code{scroll-up} and @code{scroll-down}, the directions
1323 ``up'' and ``down'' refer to the motion of the text in the buffer at which
1324 you are looking through the window.  Imagine that the text is
1325 written on a long roll of paper and that the scrolling commands move the
1326 paper up and down.  Thus, if you are looking at text in the middle of a
1327 buffer and repeatedly call @code{scroll-down}, you will eventually see
1328 the beginning of the buffer.
1330   Some people have urged that the opposite convention be used: they
1331 imagine that the window moves over text that remains in place.  Then
1332 ``down'' commands would take you to the end of the buffer.  This view is
1333 more consistent with the actual relationship between windows and the
1334 text in the buffer, but it is less like what the user sees.  The
1335 position of a window on the terminal does not move, and short scrolling
1336 commands clearly move the text up or down on the screen.  We have chosen
1337 names that fit the user's point of view.
1339   The textual scrolling functions (aside from
1340 @code{scroll-other-window}) have unpredictable results if the current
1341 buffer is different from the buffer that is displayed in the selected
1342 window.  @xref{Current Buffer}.
1344 @deffn Command scroll-up &optional count
1345 This function scrolls the text in the selected window upward
1346 @var{count} lines.  If @var{count} is negative, scrolling is actually
1347 downward.
1349 If @var{count} is @code{nil} (or omitted), then the length of scroll
1350 is @code{next-screen-context-lines} lines less than the usable height of
1351 the window (not counting its mode line).
1353 @code{scroll-up} returns @code{nil}, unless it gets an error
1354 because it can't scroll any further.
1355 @end deffn
1357 @deffn Command scroll-down &optional count
1358 This function scrolls the text in the selected window downward
1359 @var{count} lines.  If @var{count} is negative, scrolling is actually
1360 upward.
1362 If @var{count} is omitted or @code{nil}, then the length of the scroll
1363 is @code{next-screen-context-lines} lines less than the usable height of
1364 the window (not counting its mode line).
1366 @code{scroll-down} returns @code{nil}, unless it gets an error because
1367 it can't scroll any further.
1368 @end deffn
1370 @deffn Command scroll-other-window &optional count
1371 This function scrolls the text in another window upward @var{count}
1372 lines.  Negative values of @var{count}, or @code{nil}, are handled
1373 as in @code{scroll-up}.
1375 You can specify which buffer to scroll by setting the variable
1376 @code{other-window-scroll-buffer} to a buffer.  If that buffer isn't
1377 already displayed, @code{scroll-other-window} displays it in some
1378 window.
1380 When the selected window is the minibuffer, the next window is normally
1381 the one at the top left corner.  You can specify a different window to
1382 scroll, when the minibuffer is selected, by setting the variable
1383 @code{minibuffer-scroll-window}.  This variable has no effect when any
1384 other window is selected.  @xref{Minibuffer Misc}.
1386 When the minibuffer is active, it is the next window if the selected
1387 window is the one at the bottom right corner.  In this case,
1388 @code{scroll-other-window} attempts to scroll the minibuffer.  If the
1389 minibuffer contains just one line, it has nowhere to scroll to, so the
1390 line reappears after the echo area momentarily displays the message
1391 ``Beginning of buffer''.
1392 @end deffn
1394 @c Emacs 19 feature
1395 @defvar other-window-scroll-buffer
1396 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
1397 which buffer to scroll.
1398 @end defvar
1400 @defopt scroll-margin
1401 This option specifies the size of the scroll margin---a minimum number
1402 of lines between point and the top or bottom of a window.  Whenever
1403 point gets within this many lines of the top or bottom of the window,
1404 redisplay scrolls the text automatically (if possible) to move point
1405 out of the margin, closer to the center of the window.
1406 @end defopt
1408 @defopt scroll-conservatively
1409 This variable controls how scrolling is done automatically when point
1410 moves off the screen (or into the scroll margin).  If the value is a
1411 positive integer @var{n}, then redisplay scrolls the text up to
1412 @var{n} lines in either direction, if that will bring point back into
1413 proper view.  This action is called @dfn{conservative scrolling}.
1414 Otherwise, scrolling happens in the usual way, under the control of
1415 other variables such as @code{scroll-up-aggressively} and
1416 @code{scroll-down-aggressively}.
1418 The default value is zero, which means that conservative scrolling
1419 never happens.
1420 @end defopt
1422 @defopt scroll-down-aggressively
1423 @tindex scroll-down-aggressively
1424 The value of this variable should be either @code{nil} or a fraction
1425 @var{f} between 0 and 1.  If it is a fraction, that specifies where on
1426 the screen to put point when scrolling down.  More precisely, when a
1427 window scrolls down because point is above the window start, the new
1428 start position is chosen to put point @var{f} part of the window
1429 height from the top.  The larger @var{f}, the more aggressive the
1430 scrolling.
1432 A value of @code{nil} is equivalent to .5, since its effect is to center
1433 point.  This variable automatically becomes buffer-local when set in any
1434 fashion.
1435 @end defopt
1437 @defopt scroll-up-aggressively
1438 @tindex scroll-up-aggressively
1439 Likewise, for scrolling up.  The value, @var{f}, specifies how far
1440 point should be placed from the bottom of the window; thus, as with
1441 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
1442 @end defopt
1444 @defopt scroll-step
1445 This variable is an older variant of @code{scroll-conservatively}.  The
1446 difference is that it if its value is @var{n}, that permits scrolling
1447 only by precisely @var{n} lines, not a smaller number.  This feature
1448 does not work with @code{scroll-margin}.  The default value is zero.
1449 @end defopt
1451 @defopt scroll-preserve-screen-position
1452 If this option is non-@code{nil}, the scroll functions move point so
1453 that the vertical position of the cursor is unchanged, when that is
1454 possible.
1455 @end defopt
1457 @defopt next-screen-context-lines
1458 The value of this variable is the number of lines of continuity to
1459 retain when scrolling by full screens.  For example, @code{scroll-up}
1460 with an argument of @code{nil} scrolls so that this many lines at the
1461 bottom of the window appear instead at the top.  The default value is
1462 @code{2}.
1463 @end defopt
1465 @deffn Command recenter &optional count
1466 @cindex centering point
1467 This function scrolls the text in the selected window so that point is
1468 displayed at a specified vertical position within the window.  It does
1469 not ``move point'' with respect to the text.
1471 If @var{count} is a nonnegative number, that puts the line containing
1472 point @var{count} lines down from the top of the window.  If
1473 @var{count} is a negative number, then it counts upward from the
1474 bottom of the window, so that @minus{}1 stands for the last usable
1475 line in the window.  If @var{count} is a non-@code{nil} list, then it
1476 stands for the line in the middle of the window.
1478 If @var{count} is @code{nil}, @code{recenter} puts the line containing
1479 point in the middle of the window, then clears and redisplays the entire
1480 selected frame.
1482 When @code{recenter} is called interactively, @var{count} is the raw
1483 prefix argument.  Thus, typing @kbd{C-u} as the prefix sets the
1484 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
1485 @var{count} to 4, which positions the current line four lines from the
1486 top.
1488 With an argument of zero, @code{recenter} positions the current line at
1489 the top of the window.  This action is so handy that some people make a
1490 separate key binding to do this.  For example,
1492 @example
1493 @group
1494 (defun line-to-top-of-window ()
1495   "Scroll current line to top of window.
1496 Replaces three keystroke sequence C-u 0 C-l."
1497   (interactive)
1498   (recenter 0))
1500 (global-set-key [kp-multiply] 'line-to-top-of-window)
1501 @end group
1502 @end example
1503 @end deffn
1505 @node Vertical Scrolling
1506 @section Vertical Fractional Scrolling
1507 @cindex Vertical Fractional Scrolling
1509   @dfn{Vertical fractional scrolling} means shifting the image in the
1510 window up or down by a specified multiple or fraction of a line.
1511 Starting in Emacs 21, each window has a @dfn{vertical scroll position},
1512 which is a number, never less than zero.  It specifies how far to raise
1513 the contents of the window.  Raising the window contents generally makes
1514 all or part of some lines disappear off the top, and all or part of some
1515 other lines appear at the bottom.  The usual value is zero.
1517   The vertical scroll position is measured in units of the normal line
1518 height, which is the height of the default font.  Thus, if the value is
1519 .5, that means the window contents are scrolled up half the normal line
1520 height.  If it is 3.3, that means the window contents are scrolled up
1521 somewhat over three times the normal line height.
1523   What fraction of a line the vertical scrolling covers, or how many
1524 lines, depends on what the lines contain.  A value of .5 could scroll a
1525 line whose height is very short off the screen, while a value of 3.3
1526 could scroll just part of the way through a tall line or an image.
1528 @defun window-vscroll &optional window
1529 This function returns the current vertical scroll position of
1530 @var{window}, If @var{window} is @code{nil}, the selected window is
1531 used.
1533 @example
1534 @group
1535 (window-vscroll)
1536      @result{} 0
1537 @end group
1538 @end example
1539 @end defun
1541 @defun set-window-vscroll window lines
1542 This function sets @var{window}'s vertical scroll position to
1543 @var{lines}.  The argument @var{lines} should be zero or positive; if
1544 not, it is taken as zero.
1546 If @var{window} is @code{nil}, the selected window is used.
1548 The actual vertical scroll position must always correspond
1549 to an integral number of pixels, so the value you specify
1550 is rounded accordingly.
1552 The return value is the result of this rounding.
1554 @example
1555 @group
1556 (set-window-vscroll (selected-window) 1.2)
1557      @result{} 1.13
1558 @end group
1559 @end example
1560 @end defun
1562 @node Horizontal Scrolling
1563 @section Horizontal Scrolling
1564 @cindex horizontal scrolling
1566   @dfn{Horizontal scrolling} means shifting the image in the window left
1567 or right by a specified multiple of the normal character width.  Each
1568 window has a @dfn{horizontal scroll position}, which is a number, never
1569 less than zero.  It specifies how far to shift the contents left.
1570 Shifting the window contents left generally makes all or part of some
1571 characters disappear off the left, and all or part of some other
1572 characters appear at the right.  The usual value is zero.
1574   The horizontal scroll position is measured in units of the normal
1575 character width, which is the width of space in the default font.  Thus,
1576 if the value is 5, that means the window contents are scrolled left by 5
1577 times the normal character width.  How many characters actually
1578 disappear off to the left depends on their width, and could vary from
1579 line to line.
1581   Because we read from side to side in the ``inner loop'', and from top
1582 to bottom in the ``outer loop'', the effect of horizontal scrolling is
1583 not like that of textual or vertical scrolling.  Textual scrolling
1584 involves selection of a portion of text to display, and vertical
1585 scrolling moves the window contents contiguously; but horizontal
1586 scrolling causes part of @emph{each line} to go off screen.
1588   Usually, no horizontal scrolling is in effect; then the leftmost
1589 column is at the left edge of the window.  In this state, scrolling to
1590 the right is meaningless, since there is no data to the left of the edge
1591 to be revealed by it; so this is not allowed.  Scrolling to the left is
1592 allowed; it scrolls the first columns of text off the edge of the window
1593 and can reveal additional columns on the right that were truncated
1594 before.  Once a window has a nonzero amount of leftward horizontal
1595 scrolling, you can scroll it back to the right, but only so far as to
1596 reduce the net horizontal scroll to zero.  There is no limit to how far
1597 left you can scroll, but eventually all the text will disappear off the
1598 left edge.
1600 @vindex auto-hscroll-mode
1601   If @code{auto-hscroll-mode} is set, redisplay automatically alters
1602 the horizontal scrolling of a window as necessary to ensure that point
1603 is always visible.  However, you can still set the horizontal
1604 scrolling value explicitly.  The value you specify serves as a lower
1605 bound for automatic scrolling, i.e. automatic scrolling will not
1606 scroll a window to a column less than the specified one.
1608 @deffn Command scroll-left &optional count
1609 This function scrolls the selected window @var{count} columns to the
1610 left (or to the right if @var{count} is negative).  The default
1611 for @var{count} is the window width, minus 2.
1613 The return value is the total amount of leftward horizontal scrolling in
1614 effect after the change---just like the value returned by
1615 @code{window-hscroll} (below).
1616 @end deffn
1618 @deffn Command scroll-right &optional count
1619 This function scrolls the selected window @var{count} columns to the
1620 right (or to the left if @var{count} is negative).  The default
1621 for @var{count} is the window width, minus 2.
1623 The return value is the total amount of leftward horizontal scrolling in
1624 effect after the change---just like the value returned by
1625 @code{window-hscroll} (below).
1627 Once you scroll a window as far right as it can go, back to its normal
1628 position where the total leftward scrolling is zero, attempts to scroll
1629 any farther right have no effect.
1630 @end deffn
1632 @defun window-hscroll &optional window
1633 This function returns the total leftward horizontal scrolling of
1634 @var{window}---the number of columns by which the text in @var{window}
1635 is scrolled left past the left margin.
1637 The value is never negative.  It is zero when no horizontal scrolling
1638 has been done in @var{window} (which is usually the case).
1640 If @var{window} is @code{nil}, the selected window is used.
1642 @example
1643 @group
1644 (window-hscroll)
1645      @result{} 0
1646 @end group
1647 @group
1648 (scroll-left 5)
1649      @result{} 5
1650 @end group
1651 @group
1652 (window-hscroll)
1653      @result{} 5
1654 @end group
1655 @end example
1656 @end defun
1658 @defun set-window-hscroll window columns
1659 This function sets horizontal scrolling of @var{window}.  The value of
1660 @var{columns} specifies the amount of scrolling, in terms of columns
1661 from the left margin.  The argument @var{columns} should be zero or
1662 positive; if not, it is taken as zero.  Fractional values of
1663 @var{columns} are not supported at present.
1665 Note that @code{set-window-hscroll} may appear not to work if you test
1666 it by evaluating a call with @kbd{M-:} in a simple way.  What happens
1667 is that the function sets the horizontal scroll value and returns, but
1668 then redisplay adjusts the horizontal scrolling to make point visible,
1669 and this overrides what the function did.  You can observe the
1670 function's effect if you call it while point is sufficiently far from
1671 the left margin that it will remain visible.
1673 The value returned is @var{columns}.
1675 @example
1676 @group
1677 (set-window-hscroll (selected-window) 10)
1678      @result{} 10
1679 @end group
1680 @end example
1681 @end defun
1683   Here is how you can determine whether a given position @var{position}
1684 is off the screen due to horizontal scrolling:
1686 @example
1687 @group
1688 (defun hscroll-on-screen (window position)
1689   (save-excursion
1690     (goto-char position)
1691     (and
1692      (>= (- (current-column) (window-hscroll window)) 0)
1693      (< (- (current-column) (window-hscroll window))
1694         (window-width window)))))
1695 @end group
1696 @end example
1698 @node Size of Window
1699 @section The Size of a Window
1700 @cindex window size
1701 @cindex size of window
1703   An Emacs window is rectangular, and its size information consists of
1704 the height (the number of lines) and the width (the number of character
1705 positions in each line).  The mode line is included in the height.  But
1706 the width does not count the scroll bar or the column of @samp{|}
1707 characters that separates side-by-side windows.
1709   The following three functions return size information about a window:
1711 @defun window-height &optional window
1712 This function returns the number of lines in @var{window}, including
1713 its mode line and header line, if any.  If @var{window} fills its
1714 entire frame except for the echo area, this is typically one less than
1715 the value of @code{frame-height} on that frame.
1717 If @var{window} is @code{nil}, the function uses the selected window.
1719 @example
1720 @group
1721 (window-height)
1722      @result{} 23
1723 @end group
1724 @group
1725 (split-window-vertically)
1726      @result{} #<window 4 on windows.texi>
1727 @end group
1728 @group
1729 (window-height)
1730      @result{} 11
1731 @end group
1732 @end example
1733 @end defun
1735 @tindex window-body-height
1736 @defun window-body-height &optional window
1737 Like @code{window-height} but the value does not include the
1738 mode line (if any) or the header line (if any).
1739 @end defun
1741 @defun window-width &optional window
1742 This function returns the number of columns in @var{window}.  If
1743 @var{window} fills its entire frame, this is the same as the value of
1744 @code{frame-width} on that frame.  The width does not include the
1745 window's scroll bar or the column of @samp{|} characters that separates
1746 side-by-side windows.
1748 If @var{window} is @code{nil}, the function uses the selected window.
1750 @example
1751 @group
1752 (window-width)
1753      @result{} 80
1754 @end group
1755 @end example
1756 @end defun
1758 @defun window-edges &optional window
1759 This function returns a list of the edge coordinates of @var{window}.
1760 If @var{window} is @code{nil}, the selected window is used.
1762 The order of the list is @code{(@var{left} @var{top} @var{right}
1763 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
1764 the frame.  The element @var{right} of the value is one more than the
1765 rightmost column used by @var{window}, and @var{bottom} is one more than
1766 the bottommost row used by @var{window} and its mode-line.
1768 If a window has a scroll bar, the right edge value includes the width of
1769 the scroll bar.  Otherwise, if the window has a neighbor on the right,
1770 its right edge value includes the width of the separator line between
1771 the window and that neighbor.  Since the width of the window does not
1772 include this separator, the width does not usually equal the difference
1773 between the right and left edges.
1774 @end defun
1776 @defun window-inside-edges window
1777 This is similar to @code{window-edges}, but the edge values
1778 it returns include only the text area of the window.  They
1779 do not include the header line, mode line, scroll bar or
1780 vertical separator, fringes, or display margins.
1781 @end defun
1783 Here are the results obtained on a typical 24-line terminal with just
1784 one window, with menu bar enabled:
1786 @example
1787 @group
1788 (window-edges (selected-window))
1789      @result{} (0 1 80 23)
1790 @end group
1791 @group
1792 (window-inside-edges (selected-window))
1793      @result{} (0 1 80 22)
1794 @end group
1795 @end example
1797 @noindent
1798 The bottom edge is at line 23 because the last line is the echo area.
1799 The bottom inside edge is at line 22, which is the window's mode line.
1801 If @var{window} is at the upper left corner of its frame, and there is
1802 no menu bar, then @var{bottom} returned by @code{window-edges} is the
1803 same as the value of @code{(window-height)}, @var{right} is almost the
1804 same as the value of @code{(window-width)}, and @var{top} and
1805 @var{left} are zero.  For example, the edges of the following window
1806 are @w{@samp{0 0 8 5}}.  Assuming that the frame has more than 8
1807 columns, the last column of the window (column 7) holds a border
1808 rather than text.  The last row (row 4) holds the mode line, shown
1809 here with @samp{xxxxxxxxx}.
1811 @example
1812 @group
1813            0
1814            _______
1815         0 |       |
1816           |       |
1817           |       |
1818           |       |
1819           xxxxxxxxx  4
1821                   7
1822 @end group
1823 @end example
1825 In the following example, let's suppose that the frame is 7
1826 columns wide.  Then the edges of the left window are @w{@samp{0 0 4 3}}
1827 and the edges of the right window are @w{@samp{4 0 7 3}}.
1828 The inside edges of the left window are @w{@samp{0 0 3 2}},
1829 and the inside edges of the right window are @w{@samp{4 0 7 2}},
1831 @example
1832 @group
1833            ___ ___
1834           |   |   |
1835           |   |   |
1836           xxxxxxxxx
1838            0  34  7
1839 @end group
1840 @end example
1842 @defun window-pixel-edges window
1843 This function is like @code{window-edges} except that, on a graphical
1844 display, the edge values are measured in pixels instead of in
1845 character lines and columns.
1846 @end defun
1848 @defun window-inside-pixel-edges window
1849 This function is like @code{window-inside-edges} except that, on a
1850 graphical display, the edge values are measured in pixels instead of
1851 in character lines and columns.
1852 @end defun
1854 @node Resizing Windows
1855 @section Changing the Size of a Window
1856 @cindex window resizing
1857 @cindex changing window size
1858 @cindex window size, changing
1860   The window size functions fall into two classes: high-level commands
1861 that change the size of windows and low-level functions that access
1862 window size.  Emacs does not permit overlapping windows or gaps between
1863 windows, so resizing one window affects other windows.
1865 @deffn Command enlarge-window size &optional horizontal
1866 This function makes the selected window @var{size} lines taller,
1867 stealing lines from neighboring windows.  It takes the lines from one
1868 window at a time until that window is used up, then takes from another.
1869 If a window from which lines are stolen shrinks below
1870 @code{window-min-height} lines, that window disappears.
1872 If @var{horizontal} is non-@code{nil}, this function makes
1873 @var{window} wider by @var{size} columns, stealing columns instead of
1874 lines.  If a window from which columns are stolen shrinks below
1875 @code{window-min-width} columns, that window disappears.
1877 If the requested size would exceed that of the window's frame, then the
1878 function makes the window occupy the entire height (or width) of the
1879 frame.
1881 If there are various other windows from which lines or columns can be
1882 stolen, and some of them specify fixed size (using
1883 @code{window-size-fixed}, see below), they are left untouched while
1884 other windows are ``robbed.''  If it would be necessary to alter the
1885 size of a fixed-size window, @code{enlarge-window} gets an error
1886 instead.
1888 If @var{size} is negative, this function shrinks the window by
1889 @minus{}@var{size} lines or columns.  If that makes the window smaller
1890 than the minimum size (@code{window-min-height} and
1891 @code{window-min-width}), @code{enlarge-window} deletes the window.
1893 @code{enlarge-window} returns @code{nil}.
1894 @end deffn
1896 @deffn Command enlarge-window-horizontally columns
1897 This function makes the selected window @var{columns} wider.
1898 It could be defined as follows:
1900 @example
1901 @group
1902 (defun enlarge-window-horizontally (columns)
1903   (enlarge-window columns t))
1904 @end group
1905 @end example
1906 @end deffn
1908 @deffn Command shrink-window size &optional horizontal
1909 This function is like @code{enlarge-window} but negates the argument
1910 @var{size}, making the selected window smaller by giving lines (or
1911 columns) to the other windows.  If the window shrinks below
1912 @code{window-min-height} or @code{window-min-width}, then it disappears.
1914 If @var{size} is negative, the window is enlarged by @minus{}@var{size}
1915 lines or columns.
1916 @end deffn
1918 @deffn Command shrink-window-horizontally columns
1919 This function makes the selected window @var{columns} narrower.
1920 It could be defined as follows:
1922 @example
1923 @group
1924 (defun shrink-window-horizontally (columns)
1925   (shrink-window columns t))
1926 @end group
1927 @end example
1928 @end deffn
1930 @deffn Command shrink-window-if-larger-than-buffer &optional window
1931 This command shrinks @var{window} to be as small as possible while still
1932 showing the full contents of its buffer---but not less than
1933 @code{window-min-height} lines.  If @var{window} is not given,
1934 it defaults to the selected window.
1936 However, the command does nothing if the window is already too small to
1937 display the whole text of the buffer, or if part of the contents are
1938 currently scrolled off screen, or if the window is not the full width of
1939 its frame, or if the window is the only window in its frame.
1940 @end deffn
1942 @tindex window-size-fixed
1943 @defvar window-size-fixed
1944 If this variable is non-@code{nil}, in any given buffer,
1945 then the size of any window displaying the buffer remains fixed
1946 unless you explicitly change it or Emacs has no other choice.
1947 (This feature is new in Emacs 21.)
1949 If the value is @code{height}, then only the window's height is fixed;
1950 if the value is @code{width}, then only the window's width is fixed.
1951 Any other non-@code{nil} value fixes both the width and the height.
1953 The usual way to use this variable is to give it a buffer-local value in
1954 a particular buffer.  That way, the windows (but usually there is only
1955 one) displaying that buffer have fixed size.
1957 Explicit size-change functions such as @code{enlarge-window}
1958 get an error if they would have to change a window size which is fixed.
1959 Therefore, when you want to change the size of such a window,
1960 you should bind @code{window-size-fixed} to @code{nil}, like this:
1962 @example
1963 (let ((window-size-fixed nil))
1964    (enlarge-window 10))
1965 @end example
1967 Note that changing the frame size will change the size of a
1968 fixed-size window, if there is no other alternative.
1969 @end defvar
1971 @cindex minimum window size
1972   The following two variables constrain the window-structure-changing
1973 functions to a minimum height and width.
1975 @defopt window-min-height
1976 The value of this variable determines how short a window may become
1977 before it is automatically deleted.  Making a window smaller than
1978 @code{window-min-height} automatically deletes it, and no window may
1979 be created shorter than this.  The default value is 4.
1981 The absolute minimum window height is one; actions that change window
1982 sizes reset this variable to one if it is less than one.
1983 @end defopt
1985 @defopt window-min-width
1986 The value of this variable determines how narrow a window may become
1987 before it is automatically deleted.  Making a window smaller than
1988 @code{window-min-width} automatically deletes it, and no window may be
1989 created narrower than this.  The default value is 10.
1991 The absolute minimum window width is two; actions that change window
1992 sizes reset this variable to two if it is less than two.
1993 @end defopt
1995 @node Coordinates and Windows
1996 @section Coordinates and Windows
1998 This section describes how to relate screen coordinates to windows.
2000 @defun window-at x y &optional frame
2001 This function returns the window containing the specified cursor
2002 position in the frame @var{frame}.  The coordinates @var{x} and @var{y}
2003 are measured in characters and count from the top left corner of the
2004 frame.  If they are out of range, @code{window-at} returns @code{nil}.
2006 If you omit @var{frame}, the selected frame is used.
2007 @end defun
2009 @defun coordinates-in-window-p coordinates window
2010 This function checks whether a particular frame position falls within
2011 the window @var{window}.
2013 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
2014 . @var{y})}.  The coordinates @var{x} and @var{y} are measured in
2015 characters, and count from the top left corner of the screen or frame.
2017 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
2018 if the coordinates are inside @var{window}.  The value also indicates
2019 what part of the window the position is in, as follows:
2021 @table @code
2022 @item (@var{relx} . @var{rely})
2023 The coordinates are inside @var{window}.  The numbers @var{relx} and
2024 @var{rely} are the equivalent window-relative coordinates for the
2025 specified position, counting from 0 at the top left corner of the
2026 window.
2028 @item mode-line
2029 The coordinates are in the mode line of @var{window}.
2031 @item header-line
2032 The coordinates are in the header line of @var{window}.
2034 @item vertical-line
2035 The coordinates are in the vertical line between @var{window} and its
2036 neighbor to the right.  This value occurs only if the window doesn't
2037 have a scroll bar; positions in a scroll bar are considered outside the
2038 window for these purposes.
2040 @item left-fringe
2041 @itemx right-fringe
2042 The coordinates are in the left or right fringe of the window.
2044 @item left-margin
2045 @itemx right-margin
2046 The coordinates are in the left or right margin of the window.
2048 @item nil
2049 The coordinates are not in any part of @var{window}.
2050 @end table
2052 The function @code{coordinates-in-window-p} does not require a frame as
2053 argument because it always uses the frame that @var{window} is on.
2054 @end defun
2056 @node Window Configurations
2057 @section Window Configurations
2058 @cindex window configurations
2059 @cindex saving window information
2061   A @dfn{window configuration} records the entire layout of one
2062 frame---all windows, their sizes, which buffers they contain, what
2063 part of each buffer is displayed, and the values of point and the
2064 mark; also their fringes, margins, and scroll bar settings.  It also
2065 includes the values of @code{window-min-height},
2066 @code{window-min-width} and @code{minibuffer-scroll-window}.  An
2067 exception is made for point in the selected window for the current
2068 buffer; its value is not saved in the window configuration.
2070   You can bring back an entire previous layout by restoring a window
2071 configuration previously saved.  If you want to record all frames
2072 instead of just one, use a frame configuration instead of a window
2073 configuration.  @xref{Frame Configurations}.
2075 @defun current-window-configuration &optional frame
2076 This function returns a new object representing @var{frame}'s current
2077 window configuration.  If @var{frame} is omitted, the selected frame
2078 is used.
2079 @end defun
2081 @defun set-window-configuration configuration
2082 This function restores the configuration of windows and buffers as
2083 specified by @var{configuration}, for the frame that @var{configuration}
2084 was created for.
2086 The argument @var{configuration} must be a value that was previously
2087 returned by @code{current-window-configuration}.  This configuration is
2088 restored in the frame from which @var{configuration} was made, whether
2089 that frame is selected or not.  This always counts as a window size
2090 change and triggers execution of the @code{window-size-change-functions}
2091 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
2092 know how to tell whether the new configuration actually differs from the
2093 old one.
2095 If the frame which @var{configuration} was saved from is dead, all this
2096 function does is restore the three variables @code{window-min-height},
2097 @code{window-min-width} and @code{minibuffer-scroll-window}.
2099 Here is a way of using this function to get the same effect
2100 as @code{save-window-excursion}:
2102 @example
2103 @group
2104 (let ((config (current-window-configuration)))
2105   (unwind-protect
2106       (progn (split-window-vertically nil)
2107              @dots{})
2108     (set-window-configuration config)))
2109 @end group
2110 @end example
2111 @end defun
2113 @defspec save-window-excursion forms@dots{}
2114 This special form records the window configuration, executes @var{forms}
2115 in sequence, then restores the earlier window configuration.  The window
2116 configuration includes the value of point and the portion of the buffer
2117 that is visible.  It also includes the choice of selected window.
2118 However, it does not include the value of point in the current buffer;
2119 use @code{save-excursion} also, if you wish to preserve that.
2121 Don't use this construct when @code{save-selected-window} is sufficient.
2123 Exit from @code{save-window-excursion} always triggers execution of the
2124 @code{window-size-change-functions}.  (It doesn't know how to tell
2125 whether the restored configuration actually differs from the one in
2126 effect at the end of the @var{forms}.)
2128 The return value is the value of the final form in @var{forms}.
2129 For example:
2131 @example
2132 @group
2133 (split-window)
2134      @result{} #<window 25 on control.texi>
2135 @end group
2136 @group
2137 (setq w (selected-window))
2138      @result{} #<window 19 on control.texi>
2139 @end group
2140 @group
2141 (save-window-excursion
2142   (delete-other-windows w)
2143   (switch-to-buffer "foo")
2144   'do-something)
2145      @result{} do-something
2146      ;; @r{The screen is now split again.}
2147 @end group
2148 @end example
2149 @end defspec
2151 @defun window-configuration-p object
2152 This function returns @code{t} if @var{object} is a window configuration.
2153 @end defun
2155 @defun compare-window-configurations config1 config2
2156 This function compares two window configurations as regards the
2157 structure of windows, but ignores the values of point and mark and the
2158 saved scrolling positions---it can return @code{t} even if those
2159 aspects differ.
2161 The function @code{equal} can also compare two window configurations; it
2162 regards configurations as unequal if they differ in any respect, even a
2163 saved point or mark.
2164 @end defun
2166 @defun window-configuration-frame config
2167 This function returns the frame for which the window configuration
2168 @var{config} was made.
2169 @end defun
2171   Other primitives to look inside of window configurations would make
2172 sense, but are not implemented because we did not need them.  See the
2173 file @file{winner.el} for some more operations on windows
2174 configurations.
2176 @node Window Hooks
2177 @section Hooks for Window Scrolling and Changes
2179 This section describes how a Lisp program can take action whenever a
2180 window displays a different part of its buffer or a different buffer.
2181 There are three actions that can change this: scrolling the window,
2182 switching buffers in the window, and changing the size of the window.
2183 The first two actions run @code{window-scroll-functions}; the last runs
2184 @code{window-size-change-functions}.  The paradigmatic use of these
2185 hooks is in the implementation of Lazy Lock mode; see @file{lazy-lock.el}.
2187 @defvar window-scroll-functions
2188 This variable holds a list of functions that Emacs should call before
2189 redisplaying a window with scrolling.  It is not a normal hook, because
2190 each function is called with two arguments: the window, and its new
2191 display-start position.
2193 Displaying a different buffer in the window also runs these functions.
2195 These functions must be careful in using @code{window-end}
2196 (@pxref{Window Start}); if you need an up-to-date value, you must use
2197 the @var{update} argument to ensure you get it.
2198 @end defvar
2200 @defvar window-size-change-functions
2201 This variable holds a list of functions to be called if the size of any
2202 window changes for any reason.  The functions are called just once per
2203 redisplay, and just once for each frame on which size changes have
2204 occurred.
2206 Each function receives the frame as its sole argument.  There is no
2207 direct way to find out which windows on that frame have changed size, or
2208 precisely how.  However, if a size-change function records, at each
2209 call, the existing windows and their sizes, it can also compare the
2210 present sizes and the previous sizes.
2212 Creating or deleting windows counts as a size change, and therefore
2213 causes these functions to be called.  Changing the frame size also
2214 counts, because it changes the sizes of the existing windows.
2216 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
2217 Configurations}) in these functions, because that always counts as a
2218 size change, and it would cause these functions to be called over and
2219 over.  In most cases, @code{save-selected-window} (@pxref{Selecting
2220 Windows}) is what you need here.
2221 @end defvar
2223 @defvar redisplay-end-trigger-functions
2224 This abnormal hook is run whenever redisplay in a window uses text that
2225 extends past a specified end trigger position.  You set the end trigger
2226 position with the function @code{set-window-redisplay-end-trigger}.  The
2227 functions are called with two arguments: the window, and the end trigger
2228 position.  Storing @code{nil} for the end trigger position turns off the
2229 feature, and the trigger value is automatically reset to @code{nil} just
2230 after the hook is run.
2231 @end defvar
2233 @defun set-window-redisplay-end-trigger window position
2234 This function sets @var{window}'s end trigger position at
2235 @var{position}.
2236 @end defun
2238 @defun window-redisplay-end-trigger &optional window
2239 This function returns @var{window}'s current end trigger position.
2240 @end defun
2242 @defvar window-configuration-change-hook
2243 A normal hook that is run every time you change the window configuration
2244 of an existing frame.  This includes splitting or deleting windows,
2245 changing the sizes of windows, or displaying a different buffer in a
2246 window.  The frame whose window configuration has changed is the
2247 selected frame when this hook runs.
2248 @end defvar
2250 @ignore
2251    arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
2252 @end ignore