2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
4 @c 2004, 2005 Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/windows
7 @node Windows, Frames, Buffers, Top
10 This chapter describes most of the functions and variables related to
11 Emacs windows. See @ref{Display}, for information on how text is
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 Split Tree:: The layout and sizes of all windows in a frame.
34 * Window Configurations:: Saving and restoring the state of the screen.
35 * Window Hooks:: Hooks for scrolling, window size changes,
36 redisplay going past a certain point,
37 or window configuration changes.
41 @section Basic Concepts of Emacs Windows
43 @cindex selected window
45 A @dfn{window} in Emacs is the physical area of the screen in which a
46 buffer is displayed. The term is also used to refer to a Lisp object that
47 represents that screen area in Emacs Lisp. It should be
48 clear from the context which is meant.
50 Emacs groups windows into frames. A frame represents an area of
51 screen available for Emacs to use. Each frame always contains at least
52 one window, but you can subdivide it vertically or horizontally into
53 multiple nonoverlapping Emacs windows.
55 In each frame, at any time, one and only one window is designated as
56 @dfn{selected within the frame}. The frame's cursor appears in that
57 window, but the other windows have ``non-selected'' cursors, normally
58 less visible. At any time, one frame is the selected frame; and the
59 window selected within that frame is @dfn{the selected window}. The
60 selected window's buffer is usually the current buffer (except when
61 @code{set-buffer} has been used). @xref{Current Buffer}.
63 @defvar cursor-in-non-selected-windows
64 If this variable is @code{nil}, Emacs displays only one cursor,
65 in the selected window. Other windows have no cursor at all.
68 For practical purposes, a window exists only while it is displayed in
69 a frame. Once removed from the frame, the window is effectively deleted
70 and should not be used, @emph{even though there may still be references
71 to it} from other Lisp objects. Restoring a saved window configuration
72 is the only way for a window no longer on the screen to come back to
73 life. (@xref{Deleting Windows}.)
75 Each window has the following attributes:
88 window edges with respect to the screen or frame
91 the buffer it displays
94 position within the buffer at the upper left of the window
97 amount of horizontal scrolling, in columns
106 how recently the window was selected
118 @cindex multiple windows
119 Users create multiple windows so they can look at several buffers at
120 once. Lisp libraries use multiple windows for a variety of reasons, but
121 most often to display related information. In Rmail, for example, you
122 can move through a summary buffer in one window while the other window
123 shows messages one at a time as they are reached.
125 The meaning of ``window'' in Emacs is similar to what it means in the
126 context of general-purpose window systems such as X, but not identical.
127 The X Window System places X windows on the screen; Emacs uses one or
128 more X windows as frames, and subdivides them into
129 Emacs windows. When you use Emacs on a character-only terminal, Emacs
130 treats the whole terminal screen as one frame.
132 @cindex terminal screen
133 @cindex screen of terminal
134 @cindex tiled windows
135 Most window systems support arbitrarily located overlapping windows.
136 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
137 together they fill the whole screen or frame. Because of the way in
138 which Emacs creates new windows and resizes them, not all conceivable
139 tilings of windows on an Emacs frame are actually possible.
140 @xref{Splitting Windows}, and @ref{Size of Window}.
142 @xref{Display}, for information on how the contents of the
143 window's buffer are displayed in the window.
145 @defun windowp object
146 This function returns @code{t} if @var{object} is a window.
149 @node Splitting Windows
150 @section Splitting Windows
151 @cindex splitting windows
152 @cindex window splitting
154 The functions described here are the primitives used to split a window
155 into two windows. Two higher level functions sometimes split a window,
156 but not always: @code{pop-to-buffer} and @code{display-buffer}
157 (@pxref{Displaying Buffers}).
159 The functions described here do not accept a buffer as an argument.
160 The two ``halves'' of the split window initially display the same buffer
161 previously visible in the window that was split.
163 @deffn Command split-window &optional window size horizontal
164 This function splits @var{window} into two windows. The original
165 window @var{window} remains the selected window, but occupies only
166 part of its former screen area. The rest is occupied by a newly created
167 window which is returned as the value of this function.
169 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
170 two side by side windows. The original window @var{window} keeps the
171 leftmost @var{size} columns, and gives the rest of the columns to the
172 new window. Otherwise, it splits into windows one above the other, and
173 @var{window} keeps the upper @var{size} lines and gives the rest of the
174 lines to the new window. The original window is therefore the
175 left-hand or upper of the two, and the new window is the right-hand or
178 If @var{window} is omitted or @code{nil}, then the selected window is
179 split. If @var{size} is omitted or @code{nil}, then @var{window} is
180 divided evenly into two parts. (If there is an odd line, it is
181 allocated to the new window.) When @code{split-window} is called
182 interactively, all its arguments are @code{nil}.
184 If splitting would result in making a window that is smaller than
185 @code{window-min-height} or @code{window-min-width}, the function
186 signals an error and does not split the window at all.
188 The following example starts with one window on a screen that is 50
189 lines high by 80 columns wide; then it splits the window.
193 (setq w (selected-window))
194 @result{} #<window 8 on windows.texi>
195 (window-edges) ; @r{Edges in order:}
196 @result{} (0 0 80 50) ; @r{left--top--right--bottom}
200 ;; @r{Returns window created}
201 (setq w2 (split-window w 15))
202 @result{} #<window 28 on windows.texi>
206 @result{} (0 15 80 50) ; @r{Bottom window;}
211 @result{} (0 0 80 15) ; @r{Top window}
215 The screen looks like this:
231 Next, split the top window horizontally:
235 (setq w3 (split-window w 35 t))
236 @result{} #<window 32 on windows.texi>
240 @result{} (35 0 80 15) ; @r{Left edge at column 35}
244 @result{} (0 0 35 15) ; @r{Right edge at column 35}
248 @result{} (0 15 80 50) ; @r{Bottom window unchanged}
253 Now the screen looks like this:
270 Normally, Emacs indicates the border between two side-by-side windows
271 with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|}
272 characters. The display table can specify alternative border
273 characters; see @ref{Display Tables}.
276 @deffn Command split-window-vertically &optional size
277 This function splits the selected window into two windows, one above the
278 other, leaving the upper of the two windows selected, with @var{size}
279 lines. (If @var{size} is negative, then the lower of the two windows
280 gets @minus{} @var{size} lines and the upper window gets the rest, but
281 the upper window is still the one selected.) However, if
282 @code{split-window-keep-point} (see below) is @code{nil}, then either
283 window can be selected.
285 In other respects, this function is similar to @code{split-window}.
286 In particular, the upper window is the original one and the return
287 value is the new, lower window.
290 @defopt split-window-keep-point
291 If this variable is non-@code{nil} (the default), then
292 @code{split-window-vertically} behaves as described above.
294 If it is @code{nil}, then @code{split-window-vertically} adjusts point
295 in each of the two windows to avoid scrolling. (This is useful on
296 slow terminals.) It selects whichever window contains the screen line
297 that point was previously on.
299 This variable only affects the behavior of @code{split-window-vertically}.
300 It has no effect on the other functions described here.
303 @deffn Command split-window-horizontally &optional size
304 This function splits the selected window into two windows
305 side-by-side, leaving the selected window on the left with @var{size}
306 columns. If @var{size} is negative, the rightmost window gets
307 @minus{} @var{size} columns, but the leftmost window still remains
310 This function is basically an interface to @code{split-window}.
311 You could define a simplified version of the function like this:
315 (defun split-window-horizontally (&optional arg)
316 "Split selected window into two windows, side by side..."
320 (let ((size (and arg (prefix-numeric-value arg))))
322 (setq size (+ (window-width) size)))
323 (split-window nil size t)))
328 @defun one-window-p &optional no-mini all-frames
329 This function returns non-@code{nil} if there is only one window. The
330 argument @var{no-mini}, if non-@code{nil}, means don't count the
331 minibuffer even if it is active; otherwise, the minibuffer window is
332 counted when it is active.
334 The argument @var{all-frames} specifies which frames to consider. Here
335 are the possible values and their meanings:
339 Count the windows in the selected frame, plus the minibuffer used
340 by that frame even if it lies in some other frame.
343 Count all windows in all existing frames.
346 Count all windows in all visible frames.
349 Count all windows in all visible or iconified frames.
352 Count precisely the windows in the selected frame, and no others.
356 @node Deleting Windows
357 @section Deleting Windows
358 @cindex deleting windows
360 A window remains visible on its frame unless you @dfn{delete} it by
361 calling certain functions that delete windows. A deleted window cannot
362 appear on the screen, but continues to exist as a Lisp object until
363 there are no references to it. There is no way to cancel the deletion
364 of a window aside from restoring a saved window configuration
365 (@pxref{Window Configurations}). Restoring a window configuration also
366 deletes any windows that aren't part of that configuration.
368 When you delete a window, the space it took up is given to one
372 @defun window-live-p window
373 This function returns @code{nil} if @var{window} is deleted, and
376 @strong{Warning:} Erroneous information or fatal errors may result from
377 using a deleted window as if it were live.
380 @deffn Command delete-window &optional window
381 This function removes @var{window} from display, and returns @code{nil}.
382 If @var{window} is omitted, then the selected window is deleted. An
383 error is signaled if there is only one window when @code{delete-window}
387 @deffn Command delete-other-windows &optional window
388 This function makes @var{window} the only window on its frame, by
389 deleting the other windows in that frame. If @var{window} is omitted or
390 @code{nil}, then the selected window is used by default.
392 The return value is @code{nil}.
395 @deffn Command delete-windows-on buffer-or-name &optional frame
396 This function deletes all windows showing @var{buffer-or-name}. If
397 there are no windows showing @var{buffer-or-name}, it does nothing.
398 @var{buffer-or-name} must be a buffer or the name of an existing
401 @code{delete-windows-on} operates frame by frame. If a frame has
402 several windows showing different buffers, then those showing
403 @var{buffer-or-name} are removed, and the others expand to fill the
404 space. If all windows in some frame are showing @var{buffer-or-name}
405 (including the case where there is only one window), then the frame
406 winds up with a single window showing another buffer chosen with
407 @code{other-buffer}. @xref{The Buffer List}.
409 The argument @var{frame} controls which frames to operate on. This
410 function does not use it in quite the same way as the other functions
411 which scan all windows; specifically, the values @code{t} and @code{nil}
412 have the opposite of their meanings in other functions. Here are the
417 If it is @code{nil}, operate on all frames.
419 If it is @code{t}, operate on the selected frame.
421 If it is @code{visible}, operate on all visible frames.
423 If it is 0, operate on all visible or iconified frames.
425 If it is a frame, operate on that frame.
428 This function always returns @code{nil}.
431 @node Selecting Windows
432 @section Selecting Windows
433 @cindex selecting windows
435 When a window is selected, the buffer in the window becomes the current
436 buffer, and the cursor will appear in it.
438 @defun selected-window
439 This function returns the selected window. This is the window in
440 which the cursor appears and to which many commands apply.
443 @defun select-window window &optional norecord
444 This function makes @var{window} the selected window. The cursor then
445 appears in @var{window} (on redisplay). Unless @var{window} was
446 already selected, @code{select-window} makes @var{window}'s buffer the
449 Normally @var{window}'s selected buffer is moved to the front of the
450 buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
453 The return value is @var{window}.
457 (setq w (next-window))
459 @result{} #<window 65 on windows.texi>
464 @defmac save-selected-window forms@dots{}
465 This macro records the selected frame, as well as the selected window
466 of each frame, executes @var{forms} in sequence, then restores the
467 earlier selected frame and windows. It also saves and restores the
468 current buffer. It returns the value of the last form in @var{forms}.
470 This macro does not save or restore anything about the sizes,
471 arrangement or contents of windows; therefore, if the @var{forms}
472 change them, the change persists. If the previously selected window
473 of some frame is no longer live at the time of exit from @var{forms},
474 that frame's selected window is left alone. If the previously
475 selected window is no longer live, then whatever window is selected at
476 the end of @var{forms} remains selected.
479 @defmac with-selected-window window forms@dots{}
480 This macro selects @var{window} (without changing the buffer list),
481 executes @var{forms} in sequence, then restores the previously
482 selected window and current buffer. It is just like
483 @code{save-selected-window}, except that it explicitly selects
484 @var{window}, also without altering the buffer list sequence.
487 @cindex finding windows
488 The following functions choose one of the windows on the screen,
489 offering various criteria for the choice.
491 @defun get-lru-window &optional frame
492 This function returns the window least recently ``used'' (that is,
493 selected). If any full-width windows are present, it only considers
494 these. The selected window is always the most recently used window.
496 The selected window can be the least recently used window if it is the
497 only window. A newly created window becomes the least recently used
498 window until it is selected. A minibuffer window is never a
499 candidate. Dedicated windows are never candidates, and if all
500 existing windows are dedicated, the value is @code{nil}.
502 The argument @var{frame} controls which windows are considered.
506 If it is @code{nil}, consider windows on the selected frame.
508 If it is @code{t}, consider windows on all frames.
510 If it is @code{visible}, consider windows on all visible frames.
512 If it is 0, consider windows on all visible or iconified frames.
514 If it is a frame, consider windows on that frame.
518 @defun get-largest-window &optional frame
519 This function returns the window with the largest area (height times
520 width). If there are no side-by-side windows, then this is the window
521 with the most lines. A minibuffer window is never a candidate.
522 Dedicated windows are never candidates, and if all existing windows
523 are dedicated, the value is @code{nil}.
525 If there are two candidate windows of the same size, this function
526 prefers the one that comes first in the cyclic ordering of windows
527 (see following section), starting from the selected window.
529 The argument @var{frame} controls which set of windows to
530 consider. See @code{get-lru-window}, above.
533 @cindex window that satisfies a predicate
534 @cindex conditional selection of windows
535 @defun get-window-with-predicate predicate &optional minibuf all-frames default
536 This function returns a window satisfying @var{predicate}. It cycles
537 through all visible windows using @code{walk-windows} (@pxref{Cyclic
538 Window Ordering}), calling @var{predicate} on each one of them
539 with that window as its argument. The function returns the first
540 window for which @var{predicate} returns a non-@code{nil} value; if
541 that never happens, it returns @var{default}.
543 The optional arguments @var{minibuf} and @var{all-frames} specify the
544 set of windows to include in the scan. See the description of
545 @code{next-window} in @ref{Cyclic Window Ordering}, for details.
548 @node Cyclic Window Ordering
549 @comment node-name, next, previous, up
550 @section Cyclic Ordering of Windows
551 @cindex cyclic ordering of windows
552 @cindex ordering of windows, cyclic
553 @cindex window ordering, cyclic
555 When you use the command @kbd{C-x o} (@code{other-window}) to select
556 the next window, it moves through all the windows on the screen in a
557 specific cyclic order. For any given configuration of windows, this
558 order never varies. It is called the @dfn{cyclic ordering of windows}.
560 This ordering generally goes from top to bottom, and from left to
561 right. But it may go down first or go right first, depending on the
562 order in which the windows were split.
564 If the first split was vertical (into windows one above each other),
565 and then the subwindows were split horizontally, then the ordering is
566 left to right in the top of the frame, and then left to right in the
567 next lower part of the frame, and so on. If the first split was
568 horizontal, the ordering is top to bottom in the left part, and so on.
569 In general, within each set of siblings at any level in the window tree,
570 the order is left to right, or top to bottom.
572 @defun next-window &optional window minibuf all-frames
573 @cindex minibuffer window
574 This function returns the window following @var{window} in the cyclic
575 ordering of windows. This is the window that @kbd{C-x o} would select
576 if typed when @var{window} is selected. If @var{window} is the only
577 window visible, then this function returns @var{window}. If omitted,
578 @var{window} defaults to the selected window.
580 The value of the argument @var{minibuf} determines whether the
581 minibuffer is included in the window order. Normally, when
582 @var{minibuf} is @code{nil}, the minibuffer is included if it is
583 currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
584 window is active while the minibuffer is in use. @xref{Minibuffers}.)
586 If @var{minibuf} is @code{t}, then the cyclic ordering includes the
587 minibuffer window even if it is not active.
589 If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
590 window is not included even if it is active.
592 The argument @var{all-frames} specifies which frames to consider. Here
593 are the possible values and their meanings:
597 Consider all the windows in @var{window}'s frame, plus the minibuffer
598 used by that frame even if it lies in some other frame. If the
599 minibuffer counts (as determined by @var{minibuf}), then all windows on
600 all frames that share that minibuffer count too.
603 Consider all windows in all existing frames.
606 Consider all windows in all visible frames. (To get useful results, you
607 must ensure @var{window} is in a visible frame.)
610 Consider all windows in all visible or iconified frames.
613 Consider all windows on that frame.
616 Consider precisely the windows in @var{window}'s frame, and no others.
619 This example assumes there are two windows, both displaying the
620 buffer @samp{windows.texi}:
625 @result{} #<window 56 on windows.texi>
628 (next-window (selected-window))
629 @result{} #<window 52 on windows.texi>
632 (next-window (next-window (selected-window)))
633 @result{} #<window 56 on windows.texi>
638 @defun previous-window &optional window minibuf all-frames
639 This function returns the window preceding @var{window} in the cyclic
640 ordering of windows. The other arguments specify which windows to
641 include in the cycle, as in @code{next-window}.
644 @deffn Command other-window count &optional all-frames
645 This function selects the @var{count}th following window in the cyclic
646 order. If count is negative, then it moves back @minus{}@var{count}
647 windows in the cycle, rather than forward. It returns @code{nil}.
649 The argument @var{all-frames} has the same meaning as in
650 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
651 is always effectively @code{nil}.
653 In an interactive call, @var{count} is the numeric prefix argument.
657 @defun walk-windows proc &optional minibuf all-frames
658 This function cycles through all windows. It calls the function
659 @code{proc} once for each window, with the window as its sole
662 The optional arguments @var{minibuf} and @var{all-frames} specify the
663 set of windows to include in the scan. See @code{next-window}, above,
667 @defun window-list &optional frame minibuf window
668 This function returns a list of the windows on @var{frame}, starting
669 with @var{window}. If @var{frame} is @code{nil} or omitted,
670 @code{window-list} uses the selected frame instead; if @var{window} is
671 @code{nil} or omitted, it uses the selected window.
673 The value of @var{minibuf} determines if the minibuffer window is
674 included in the result list. If @var{minibuf} is @code{t}, the result
675 always includes the minibuffer window. If @var{minibuf} is @code{nil}
676 or omitted, that includes the minibuffer window if it is active. If
677 @var{minibuf} is neither @code{nil} nor @code{t}, the result never
678 includes the minibuffer window.
681 @node Buffers and Windows
682 @section Buffers and Windows
683 @cindex examining windows
684 @cindex windows, controlling precisely
685 @cindex buffers, controlled in windows
687 This section describes low-level functions to examine windows or to
688 display buffers in windows in a precisely controlled fashion.
690 See the following section for
693 @xref{Displaying Buffers}, for
695 related functions that find a window to use and specify a buffer for it.
696 The functions described there are easier to use than these, but they
697 employ heuristics in choosing or creating a window; use these functions
698 when you need complete control.
700 @defun set-window-buffer window buffer-or-name &optional keep-margins
701 This function makes @var{window} display @var{buffer-or-name} as its
702 contents. It returns @code{nil}. @var{buffer-or-name} must be a
703 buffer, or the name of an existing buffer. This is the fundamental
704 primitive for changing which buffer is displayed in a window, and all
705 ways of doing that call this function.
709 (set-window-buffer (selected-window) "foo")
714 Normally, displaying @var{buffer} in @var{window} resets the window's
715 display margins, fringe widths, scroll bar settings, and position
716 based on the local variables of @var{buffer}. However, if
717 @var{keep-margins} is non-@code{nil}, the display margins and fringe
718 widths of @var{window} remain unchanged. @xref{Fringes}.
721 @defvar buffer-display-count
722 This buffer-local variable records the number of times a buffer is
723 displayed in a window. It is incremented each time
724 @code{set-window-buffer} is called for the buffer.
727 @defun window-buffer &optional window
728 This function returns the buffer that @var{window} is displaying. If
729 @var{window} is omitted, this function returns the buffer for the
735 @result{} #<buffer windows.texi>
740 @defun get-buffer-window buffer-or-name &optional all-frames
741 This function returns a window currently displaying
742 @var{buffer-or-name}, or @code{nil} if there is none. If there are
743 several such windows, then the function returns the first one in the
744 cyclic ordering of windows, starting from the selected window.
745 @xref{Cyclic Window Ordering}.
747 The argument @var{all-frames} controls which windows to consider.
751 If it is @code{nil}, consider windows on the selected frame.
753 If it is @code{t}, consider windows on all frames.
755 If it is @code{visible}, consider windows on all visible frames.
757 If it is 0, consider windows on all visible or iconified frames.
759 If it is a frame, consider windows on that frame.
763 @defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
764 This function returns a list of all the windows currently displaying
765 @var{buffer-or-name}.
767 The two optional arguments work like the optional arguments of
768 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
769 like the single optional argument of @code{get-buffer-window}. Perhaps
770 we should change @code{get-buffer-window} in the future to make it
771 compatible with the other functions.
774 @defvar buffer-display-time
775 This variable records the time at which a buffer was last made visible
776 in a window. It is always local in each buffer; each time
777 @code{set-window-buffer} is called, it sets this variable to
778 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
779 When a buffer is first created, @code{buffer-display-time} starts out
780 with the value @code{nil}.
783 @node Displaying Buffers
784 @section Displaying Buffers in Windows
785 @cindex switching to a buffer
786 @cindex displaying a buffer
788 In this section we describe convenient functions that choose a window
789 automatically and use it to display a specified buffer. These functions
790 can also split an existing window in certain circumstances. We also
791 describe variables that parameterize the heuristics used for choosing a
794 See the preceding section for
797 @xref{Buffers and Windows}, for
799 low-level functions that give you more precise control. All of these
800 functions work by calling @code{set-window-buffer}.
802 Do not use the functions in this section in order to make a buffer
803 current so that a Lisp program can access or modify it; they are too
804 drastic for that purpose, since they change the display of buffers in
805 windows, which would be gratuitous and surprise the user. Instead, use
806 @code{set-buffer} and @code{save-current-buffer} (@pxref{Current
807 Buffer}), which designate buffers as current for programmed access
808 without affecting the display of buffers in windows.
810 @deffn Command switch-to-buffer buffer-or-name &optional norecord
811 This function makes @var{buffer-or-name} the current buffer, and also
812 displays the buffer in the selected window. This means that a human can
813 see the buffer and subsequent keyboard commands will apply to it.
814 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
815 the current buffer but does not display it in the selected window.
816 @xref{Current Buffer}.
818 If @var{buffer-or-name} does not identify an existing buffer, then a new
819 buffer by that name is created. The major mode for the new buffer is
820 set according to the variable @code{default-major-mode}. @xref{Auto
821 Major Mode}. If @var{buffer-or-name} is @code{nil},
822 @code{switch-to-buffer} chooses a buffer using @code{other-buffer}.
824 Normally the specified buffer is put at the front of the buffer list
825 (both the selected frame's buffer list and the frame-independent buffer
826 list). This affects the operation of @code{other-buffer}. However, if
827 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
830 The @code{switch-to-buffer} function is often used interactively, as
831 the binding of @kbd{C-x b}. It is also used frequently in programs. It
832 returns the buffer that it switched to.
835 The next two functions are similar to @code{switch-to-buffer}, except
836 for the described features.
838 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
839 This function makes @var{buffer-or-name} the current buffer and
840 displays it in a window not currently selected. It then selects that
841 window. The handling of the buffer is the same as in
842 @code{switch-to-buffer}.
844 The currently selected window is absolutely never used to do the job.
845 If it is the only window, then it is split to make a distinct window for
846 this purpose. If the selected window is already displaying the buffer,
847 then it continues to do so, but another window is nonetheless found to
848 display it in as well.
850 This function updates the buffer list just like @code{switch-to-buffer}
851 unless @var{norecord} is non-@code{nil}.
854 @defun pop-to-buffer buffer-or-name &optional other-window norecord
855 This function makes @var{buffer-or-name} the current buffer and
856 switches to it in some window, preferably not the window previously
857 selected. The ``popped-to'' window becomes the selected window within
858 its frame. The return value is the buffer that was switched to.
859 If @var{buffer-or-name} is @code{nil}, that means to choose some
860 other buffer, but you don't specify which.
862 If the variable @code{pop-up-frames} is non-@code{nil},
863 @code{pop-to-buffer} looks for a window in any visible frame already
864 displaying the buffer; if there is one, it returns that window and makes
865 it be selected within its frame. If there is none, it creates a new
866 frame and displays the buffer in it.
868 If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
869 operates entirely within the selected frame. (If the selected frame has
870 just a minibuffer, @code{pop-to-buffer} operates within the most
871 recently selected frame that was not just a minibuffer.)
873 If the variable @code{pop-up-windows} is non-@code{nil}, windows may
874 be split to create a new window that is different from the original
875 window. For details, see @ref{Choosing Window}.
877 If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
878 creates another window even if @var{buffer-or-name} is already visible
879 in the selected window. Thus @var{buffer-or-name} could end up
880 displayed in two windows. On the other hand, if @var{buffer-or-name} is
881 already displayed in the selected window and @var{other-window} is
882 @code{nil}, then the selected window is considered sufficient display
883 for @var{buffer-or-name}, so that nothing needs to be done.
885 All the variables that affect @code{display-buffer} affect
886 @code{pop-to-buffer} as well. @xref{Choosing Window}.
888 If @var{buffer-or-name} is a string that does not name an existing
889 buffer, a buffer by that name is created. The major mode for the new
890 buffer is set according to the variable @code{default-major-mode}.
891 @xref{Auto Major Mode}.
893 This function updates the buffer list just like @code{switch-to-buffer}
894 unless @var{norecord} is non-@code{nil}.
897 @deffn Command replace-buffer-in-windows buffer-or-name
898 This function replaces @var{buffer-or-name} with some other buffer in all
899 windows displaying it. It chooses the other buffer with
900 @code{other-buffer}. In the usual applications of this function, you
901 don't care which other buffer is used; you just want to make sure that
902 @var{buffer-or-name} is no longer displayed.
904 This function returns @code{nil}.
907 @node Choosing Window
908 @section Choosing a Window for Display
910 This section describes the basic facility that chooses a window to
911 display a buffer in---@code{display-buffer}. All the higher-level
912 functions and commands use this subroutine. Here we describe how to use
913 @code{display-buffer} and how to customize it.
915 @deffn Command display-buffer buffer-or-name &optional not-this-window frame
916 This command makes @var{buffer-or-name} appear in some window, like
917 @code{pop-to-buffer}, but it does not select that window and does not
918 make the buffer current. The identity of the selected window is
919 unaltered by this function. @var{buffer-or-name} must be a buffer, or
920 the name of an existing buffer.
922 If @var{not-this-window} is non-@code{nil}, it means to display the
923 specified buffer in a window other than the selected one, even if it is
924 already on display in the selected window. This can cause the buffer to
925 appear in two windows at once. Otherwise, if @var{buffer-or-name} is
926 already being displayed in any window, that is good enough, so this
927 function does nothing.
929 @code{display-buffer} returns the window chosen to display
930 @var{buffer-or-name}.
932 If the argument @var{frame} is non-@code{nil}, it specifies which frames
933 to check when deciding whether the buffer is already displayed. If the
934 buffer is already displayed in some window on one of these frames,
935 @code{display-buffer} simply returns that window. Here are the possible
936 values of @var{frame}:
940 If it is @code{nil}, consider windows on the selected frame.
941 (Actually, the last non-minibuffer frame.)
943 If it is @code{t}, consider windows on all frames.
945 If it is @code{visible}, consider windows on all visible frames.
947 If it is 0, consider windows on all visible or iconified frames.
949 If it is a frame, consider windows on that frame.
952 Precisely how @code{display-buffer} finds or creates a window depends on
953 the variables described below.
956 @defopt display-buffer-reuse-frames
957 If this variable is non-@code{nil}, @code{display-buffer} searches
958 existing frames for a window displaying the buffer. If the buffer is
959 already displayed in a window in some frame, @code{display-buffer} makes
960 the frame visible and raises it, to use that window. If the buffer is
961 not already displayed, or if @code{display-buffer-reuse-frames} is
962 @code{nil}, @code{display-buffer}'s behavior is determined by other
963 variables, described below.
966 @defopt pop-up-windows
967 This variable controls whether @code{display-buffer} makes new windows.
968 If it is non-@code{nil} and there is only one window, then that window
969 is split. If it is @code{nil}, then @code{display-buffer} does not
970 split the single window, but uses it whole.
973 @defopt split-height-threshold
974 This variable determines when @code{display-buffer} may split a window,
975 if there are multiple windows. @code{display-buffer} always splits the
976 largest window if it has at least this many lines. If the largest
977 window is not this tall, it is split only if it is the sole window and
978 @code{pop-up-windows} is non-@code{nil}.
981 @defopt even-window-heights
982 This variable determines if @code{display-buffer} should even out window
983 heights if the buffer gets displayed in an existing window, above or
984 beneath another existing window. If @code{even-window-heights} is
985 @code{t}, the default, window heights will be evened out. If
986 @code{even-window-heights} is @code{nil}, the original window heights
991 @defopt pop-up-frames
992 This variable controls whether @code{display-buffer} makes new frames.
993 If it is non-@code{nil}, @code{display-buffer} looks for an existing
994 window already displaying the desired buffer, on any visible frame. If
995 it finds one, it returns that window. Otherwise it makes a new frame.
996 The variables @code{pop-up-windows} and @code{split-height-threshold} do
997 not matter if @code{pop-up-frames} is non-@code{nil}.
999 If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
1000 splits a window or reuses one.
1002 @xref{Frames}, for more information.
1006 @defopt pop-up-frame-function
1007 This variable specifies how to make a new frame if @code{pop-up-frames}
1010 Its value should be a function of no arguments. When
1011 @code{display-buffer} makes a new frame, it does so by calling that
1012 function, which should return a frame. The default value of the
1013 variable is a function that creates a frame using parameters from
1014 @code{pop-up-frame-alist}.
1017 @defopt pop-up-frame-alist
1018 This variable holds an alist specifying frame parameters used when
1019 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
1020 more information about frame parameters.
1023 @defopt special-display-buffer-names
1024 A list of buffer names for buffers that should be displayed specially.
1025 If the buffer's name is in this list, @code{display-buffer} handles the
1028 By default, special display means to give the buffer a dedicated frame.
1030 If an element is a list, instead of a string, then the @sc{car} of the
1031 list is the buffer name, and the rest of the list says how to create
1032 the frame. There are two possibilities for the rest of the list (its
1033 @sc{cdr}). It can be an alist, specifying frame parameters, or it can
1034 contain a function and arguments to give to it. (The function's first
1035 argument is always the buffer to be displayed; the arguments from the
1036 list come after that.)
1041 (("myfile" (minibuffer) (menu-bar-lines . 0)))
1045 specifies to display a buffer named @samp{myfile} in a dedicated frame
1046 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
1048 The list of frame parameters can also use the phony frame parameters
1049 @code{same-frame} and @code{same-window}. If the specified frame
1050 parameters include @code{(same-window . @var{value})} and @var{value}
1051 is non-@code{nil}, that means to display the buffer in the current
1052 selected window. Otherwise, if they include @code{(same-frame .
1053 @var{value})} and @var{value} is non-@code{nil}, that means to display
1054 the buffer in a new window in the currently selected frame.
1057 @defopt special-display-regexps
1058 A list of regular expressions that specify buffers that should be
1059 displayed specially. If the buffer's name matches any of the regular
1060 expressions in this list, @code{display-buffer} handles the buffer
1063 By default, special display means to give the buffer a dedicated frame.
1065 If an element is a list, instead of a string, then the @sc{car} of the
1066 list is the regular expression, and the rest of the list says how to
1067 create the frame. See above, under @code{special-display-buffer-names}.
1070 @defun special-display-p buffer-name
1071 This function returns non-@code{nil} if displaying a buffer
1072 named @var{buffer-name} with @code{display-buffer} would
1073 create a special frame. The value is @code{t} if it would
1074 use the default frame parameters, or else the specified list
1075 of frame parameters.
1078 @defvar special-display-function
1079 This variable holds the function to call to display a buffer specially.
1080 It receives the buffer as an argument, and should return the window in
1081 which it is displayed.
1083 The default value of this variable is
1084 @code{special-display-popup-frame}.
1087 @defun special-display-popup-frame buffer &optional args
1088 This function makes @var{buffer} visible in a frame of its own. If
1089 @var{buffer} is already displayed in a window in some frame, it makes
1090 the frame visible and raises it, to use that window. Otherwise, it
1091 creates a frame that will be dedicated to @var{buffer}. This
1092 function returns the window it used.
1094 If @var{args} is an alist, it specifies frame parameters for the new
1097 If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
1098 @var{args})} is called as a function to actually create and set up the
1099 frame; it is called with @var{buffer} as first argument, and @code{(cdr
1100 @var{args})} as additional arguments.
1102 This function always uses an existing window displaying @var{buffer},
1103 whether or not it is in a frame of its own; but if you set up the above
1104 variables in your init file, before @var{buffer} was created, then
1105 presumably the window was previously made by this function.
1108 @defopt special-display-frame-alist
1109 @anchor{Definition of special-display-frame-alist}
1110 This variable holds frame parameters for
1111 @code{special-display-popup-frame} to use when it creates a frame.
1114 @defopt same-window-buffer-names
1115 A list of buffer names for buffers that should be displayed in the
1116 selected window. If the buffer's name is in this list,
1117 @code{display-buffer} handles the buffer by switching to it in the
1121 @defopt same-window-regexps
1122 A list of regular expressions that specify buffers that should be
1123 displayed in the selected window. If the buffer's name matches any of
1124 the regular expressions in this list, @code{display-buffer} handles the
1125 buffer by switching to it in the selected window.
1128 @defun same-window-p buffer-name
1129 This function returns @code{t} if displaying a buffer
1130 named @var{buffer-name} with @code{display-buffer} would
1131 put it in the selected window.
1135 @defvar display-buffer-function
1136 This variable is the most flexible way to customize the behavior of
1137 @code{display-buffer}. If it is non-@code{nil}, it should be a function
1138 that @code{display-buffer} calls to do the work. The function should
1139 accept two arguments, the first two arguments that @code{display-buffer}
1140 received. It should choose or create a window, display the specified
1141 buffer in it, and then return the window.
1143 This hook takes precedence over all the other options and hooks
1148 @cindex dedicated window
1149 A window can be marked as ``dedicated'' to its buffer. Then
1150 @code{display-buffer} will not try to use that window to display any
1153 @defun window-dedicated-p window
1154 This function returns non-@code{nil} if @var{window} is marked as
1155 dedicated; otherwise @code{nil}.
1158 @defun set-window-dedicated-p window flag
1159 This function marks @var{window} as dedicated if @var{flag} is
1160 non-@code{nil}, and nondedicated otherwise.
1164 @section Windows and Point
1165 @cindex window position
1166 @cindex window point
1167 @cindex position in window
1168 @cindex point in window
1170 Each window has its own value of point, independent of the value of
1171 point in other windows displaying the same buffer. This makes it useful
1172 to have multiple windows showing one buffer.
1176 The window point is established when a window is first created; it is
1177 initialized from the buffer's point, or from the window point of another
1178 window opened on the buffer if such a window exists.
1181 Selecting a window sets the value of point in its buffer from the
1182 window's value of point. Conversely, deselecting a window sets the
1183 window's value of point from that of the buffer. Thus, when you switch
1184 between windows that display a given buffer, the point value for the
1185 selected window is in effect in the buffer, while the point values for
1186 the other windows are stored in those windows.
1189 As long as the selected window displays the current buffer, the window's
1190 point and the buffer's point always move together; they remain equal.
1194 @xref{Positions}, for more details on buffer positions.
1196 As far as the user is concerned, point is where the cursor is, and
1197 when the user switches to another buffer, the cursor jumps to the
1198 position of point in that buffer.
1200 @defun window-point &optional window
1201 This function returns the current position of point in @var{window}.
1202 For a nonselected window, this is the value point would have (in that
1203 window's buffer) if that window were selected. If @var{window} is
1204 @code{nil}, the selected window is used.
1206 When @var{window} is the selected window and its buffer is also the
1207 current buffer, the value returned is the same as point in that buffer.
1209 Strictly speaking, it would be more correct to return the
1210 ``top-level'' value of point, outside of any @code{save-excursion}
1211 forms. But that value is hard to find.
1214 @defun set-window-point window position
1215 This function positions point in @var{window} at position
1216 @var{position} in @var{window}'s buffer. It returns @var{position}.
1220 @section The Window Start Position
1222 Each window contains a marker used to keep track of a buffer position
1223 that specifies where in the buffer display should start. This position
1224 is called the @dfn{display-start} position of the window (or just the
1225 @dfn{start}). The character after this position is the one that appears
1226 at the upper left corner of the window. It is usually, but not
1227 inevitably, at the beginning of a text line.
1229 @defun window-start &optional window
1230 @cindex window top line
1231 This function returns the display-start position of window
1232 @var{window}. If @var{window} is @code{nil}, the selected window is
1242 When you create a window, or display a different buffer in it, the
1243 display-start position is set to a display-start position recently used
1244 for the same buffer, or 1 if the buffer doesn't have any.
1246 Redisplay updates the window-start position (if you have not specified
1247 it explicitly since the previous redisplay)---for example, to make sure
1248 point appears on the screen. Nothing except redisplay automatically
1249 changes the window-start position; if you move point, do not expect the
1250 window-start position to change in response until after the next
1253 For a realistic example of using @code{window-start}, see the
1254 description of @code{count-lines}. @xref{Definition of count-lines}.
1257 @defun window-end &optional window update
1258 This function returns the position of the end of the display in window
1259 @var{window}. If @var{window} is @code{nil}, the selected window is
1262 Simply changing the buffer text or moving point does not update the
1263 value that @code{window-end} returns. The value is updated only when
1264 Emacs redisplays and redisplay completes without being preempted.
1266 If the last redisplay of @var{window} was preempted, and did not finish,
1267 Emacs does not know the position of the end of display in that window.
1268 In that case, this function returns @code{nil}.
1270 If @var{update} is non-@code{nil}, @code{window-end} always returns an
1271 up-to-date value for where the window ends, based on the current
1272 @code{window-start} value. If the saved value is valid,
1273 @code{window-end} returns that; otherwise it computes the correct
1274 value by scanning the buffer text.
1276 Even if @var{update} is non-@code{nil}, @code{window-end} does not
1277 attempt to scroll the display if point has moved off the screen, the
1278 way real redisplay would do. It does not alter the
1279 @code{window-start} value. In effect, it reports where the displayed
1280 text will end if scrolling is not required.
1283 @defun set-window-start window position &optional noforce
1284 This function sets the display-start position of @var{window} to
1285 @var{position} in @var{window}'s buffer. It returns @var{position}.
1287 The display routines insist that the position of point be visible when a
1288 buffer is displayed. Normally, they change the display-start position
1289 (that is, scroll the window) whenever necessary to make point visible.
1290 However, if you specify the start position with this function using
1291 @code{nil} for @var{noforce}, it means you want display to start at
1292 @var{position} even if that would put the location of point off the
1293 screen. If this does place point off screen, the display routines move
1294 point to the left margin on the middle line in the window.
1296 For example, if point @w{is 1} and you set the start of the window @w{to
1297 2}, then point would be ``above'' the top of the window. The display
1298 routines will automatically move point if it is still 1 when redisplay
1299 occurs. Here is an example:
1303 ;; @r{Here is what @samp{foo} looks like before executing}
1304 ;; @r{the @code{set-window-start} expression.}
1308 ---------- Buffer: foo ----------
1309 @point{}This is the contents of buffer foo.
1315 ---------- Buffer: foo ----------
1321 (1+ (window-start)))
1326 ;; @r{Here is what @samp{foo} looks like after executing}
1327 ;; @r{the @code{set-window-start} expression.}
1328 ---------- Buffer: foo ----------
1329 his is the contents of buffer foo.
1335 ---------- Buffer: foo ----------
1339 If @var{noforce} is non-@code{nil}, and @var{position} would place point
1340 off screen at the next redisplay, then redisplay computes a new window-start
1341 position that works well with point, and thus @var{position} is not used.
1344 @defun pos-visible-in-window-p &optional position window partially
1345 This function returns non-@code{nil} if @var{position} is within the
1346 range of text currently visible on the screen in @var{window}. It
1347 returns @code{nil} if @var{position} is scrolled vertically out of
1348 view. Locations that are partially obscured are not considered
1349 visible unless @var{partially} is non-@code{nil}. The argument
1350 @var{position} defaults to the current position of point in
1351 @var{window}; @var{window}, to the selected window.
1353 The @code{pos-visible-in-window-p} function considers only vertical
1354 scrolling. If @var{position} is out of view only because @var{window}
1355 has been scrolled horizontally, @code{pos-visible-in-window-p} returns
1356 non-@code{nil} anyway. @xref{Horizontal Scrolling}.
1358 If @var{position} is visible, @code{pos-visible-in-window-p} returns
1359 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
1360 non-@code{nil}, it returns a list of the form @code{(@var{x} @var{y}
1361 @var{partial})}, where @var{x} and @var{y} are the pixel coordinates
1362 relative to the top left corner of the window, and @var{partial} is
1363 @code{nil} if the character after @var{position} is fully visible;
1364 otherwise it is a cons @code{(@var{rtop} . @var{rbot})} where the
1365 @var{rtop} and @var{rbot} specify the number of invisible pixels at
1366 the top and bottom of the row at @var{position}.
1372 ;; @r{If point is off the screen now, recenter it now.}
1373 (or (pos-visible-in-window-p
1374 (point) (selected-window))
1380 @node Textual Scrolling
1381 @section Textual Scrolling
1382 @cindex textual scrolling
1383 @cindex scrolling textually
1385 @dfn{Textual scrolling} means moving the text up or down through a
1386 window. It works by changing the value of the window's display-start
1387 location. It may also change the value of @code{window-point} to keep
1388 point on the screen.
1390 Textual scrolling was formerly called ``vertical scrolling,'' but we
1391 changed its name to distinguish it from the new vertical fractional
1392 scrolling feature (@pxref{Vertical Scrolling}).
1394 In the commands @code{scroll-up} and @code{scroll-down}, the directions
1395 ``up'' and ``down'' refer to the motion of the text in the buffer at which
1396 you are looking through the window. Imagine that the text is
1397 written on a long roll of paper and that the scrolling commands move the
1398 paper up and down. Thus, if you are looking at text in the middle of a
1399 buffer and repeatedly call @code{scroll-down}, you will eventually see
1400 the beginning of the buffer.
1402 Some people have urged that the opposite convention be used: they
1403 imagine that the window moves over text that remains in place. Then
1404 ``down'' commands would take you to the end of the buffer. This view is
1405 more consistent with the actual relationship between windows and the
1406 text in the buffer, but it is less like what the user sees. The
1407 position of a window on the terminal does not move, and short scrolling
1408 commands clearly move the text up or down on the screen. We have chosen
1409 names that fit the user's point of view.
1411 The textual scrolling functions (aside from
1412 @code{scroll-other-window}) have unpredictable results if the current
1413 buffer is different from the buffer that is displayed in the selected
1414 window. @xref{Current Buffer}.
1416 If the window contains a row which is taller than the height of the
1417 window (for example in the presense of a large image), the scroll
1418 functions will adjust the window vscroll to scroll the partially
1419 visible row. To disable this feature, Lisp code may bind the variable
1420 `auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}).
1422 @deffn Command scroll-up &optional count
1423 This function scrolls the text in the selected window upward
1424 @var{count} lines. If @var{count} is negative, scrolling is actually
1427 If @var{count} is @code{nil} (or omitted), then the length of scroll
1428 is @code{next-screen-context-lines} lines less than the usable height of
1429 the window (not counting its mode line).
1431 @code{scroll-up} returns @code{nil}, unless it gets an error
1432 because it can't scroll any further.
1435 @deffn Command scroll-down &optional count
1436 This function scrolls the text in the selected window downward
1437 @var{count} lines. If @var{count} is negative, scrolling is actually
1440 If @var{count} is omitted or @code{nil}, then the length of the scroll
1441 is @code{next-screen-context-lines} lines less than the usable height of
1442 the window (not counting its mode line).
1444 @code{scroll-down} returns @code{nil}, unless it gets an error because
1445 it can't scroll any further.
1448 @deffn Command scroll-other-window &optional count
1449 This function scrolls the text in another window upward @var{count}
1450 lines. Negative values of @var{count}, or @code{nil}, are handled
1451 as in @code{scroll-up}.
1453 You can specify which buffer to scroll by setting the variable
1454 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
1455 already displayed, @code{scroll-other-window} displays it in some
1458 When the selected window is the minibuffer, the next window is normally
1459 the one at the top left corner. You can specify a different window to
1460 scroll, when the minibuffer is selected, by setting the variable
1461 @code{minibuffer-scroll-window}. This variable has no effect when any
1462 other window is selected. When it is non-@code{nil} and the
1463 minibuffer is selected, it takes precedence over
1464 @code{other-window-scroll-buffer}. @xref{Definition of
1465 minibuffer-scroll-window}.
1467 When the minibuffer is active, it is the next window if the selected
1468 window is the one at the bottom right corner. In this case,
1469 @code{scroll-other-window} attempts to scroll the minibuffer. If the
1470 minibuffer contains just one line, it has nowhere to scroll to, so the
1471 line reappears after the echo area momentarily displays the message
1472 ``Beginning of buffer''.
1476 @defvar other-window-scroll-buffer
1477 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
1478 which buffer to scroll.
1481 @defopt scroll-margin
1482 This option specifies the size of the scroll margin---a minimum number
1483 of lines between point and the top or bottom of a window. Whenever
1484 point gets within this many lines of the top or bottom of the window,
1485 redisplay scrolls the text automatically (if possible) to move point
1486 out of the margin, closer to the center of the window.
1489 @defopt scroll-conservatively
1490 This variable controls how scrolling is done automatically when point
1491 moves off the screen (or into the scroll margin). If the value is a
1492 positive integer @var{n}, then redisplay scrolls the text up to
1493 @var{n} lines in either direction, if that will bring point back into
1494 proper view. This action is called @dfn{conservative scrolling}.
1495 Otherwise, scrolling happens in the usual way, under the control of
1496 other variables such as @code{scroll-up-aggressively} and
1497 @code{scroll-down-aggressively}.
1499 The default value is zero, which means that conservative scrolling
1503 @defopt scroll-down-aggressively
1504 @tindex scroll-down-aggressively
1505 The value of this variable should be either @code{nil} or a fraction
1506 @var{f} between 0 and 1. If it is a fraction, that specifies where on
1507 the screen to put point when scrolling down. More precisely, when a
1508 window scrolls down because point is above the window start, the new
1509 start position is chosen to put point @var{f} part of the window
1510 height from the top. The larger @var{f}, the more aggressive the
1513 A value of @code{nil} is equivalent to .5, since its effect is to center
1514 point. This variable automatically becomes buffer-local when set in any
1518 @defopt scroll-up-aggressively
1519 @tindex scroll-up-aggressively
1520 Likewise, for scrolling up. The value, @var{f}, specifies how far
1521 point should be placed from the bottom of the window; thus, as with
1522 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
1526 This variable is an older variant of @code{scroll-conservatively}. The
1527 difference is that it if its value is @var{n}, that permits scrolling
1528 only by precisely @var{n} lines, not a smaller number. This feature
1529 does not work with @code{scroll-margin}. The default value is zero.
1532 @defopt scroll-preserve-screen-position
1533 If this option is @code{t}, scrolling which would move the current
1534 point position out of the window chooses the new position of point
1535 so that the vertical position of the cursor is unchanged, if possible.
1537 If it is non-@code{nil} and not @code{t}, then the scrolling functions
1538 always preserve the vertical position of point, if possible.
1541 @defopt next-screen-context-lines
1542 The value of this variable is the number of lines of continuity to
1543 retain when scrolling by full screens. For example, @code{scroll-up}
1544 with an argument of @code{nil} scrolls so that this many lines at the
1545 bottom of the window appear instead at the top. The default value is
1549 @deffn Command recenter &optional count
1550 @cindex centering point
1551 This function scrolls the text in the selected window so that point is
1552 displayed at a specified vertical position within the window. It does
1553 not ``move point'' with respect to the text.
1555 If @var{count} is a nonnegative number, that puts the line containing
1556 point @var{count} lines down from the top of the window. If
1557 @var{count} is a negative number, then it counts upward from the
1558 bottom of the window, so that @minus{}1 stands for the last usable
1559 line in the window. If @var{count} is a non-@code{nil} list, then it
1560 stands for the line in the middle of the window.
1562 If @var{count} is @code{nil}, @code{recenter} puts the line containing
1563 point in the middle of the window, then clears and redisplays the entire
1566 When @code{recenter} is called interactively, @var{count} is the raw
1567 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
1568 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
1569 @var{count} to 4, which positions the current line four lines from the
1572 With an argument of zero, @code{recenter} positions the current line at
1573 the top of the window. This action is so handy that some people make a
1574 separate key binding to do this. For example,
1578 (defun line-to-top-of-window ()
1579 "Scroll current line to top of window.
1580 Replaces three keystroke sequence C-u 0 C-l."
1584 (global-set-key [kp-multiply] 'line-to-top-of-window)
1589 @node Vertical Scrolling
1590 @section Vertical Fractional Scrolling
1591 @cindex Vertical Fractional Scrolling
1593 @dfn{Vertical fractional scrolling} means shifting the image in the
1594 window up or down by a specified multiple or fraction of a line.
1595 Each window has a @dfn{vertical scroll position},
1596 which is a number, never less than zero. It specifies how far to raise
1597 the contents of the window. Raising the window contents generally makes
1598 all or part of some lines disappear off the top, and all or part of some
1599 other lines appear at the bottom. The usual value is zero.
1601 The vertical scroll position is measured in units of the normal line
1602 height, which is the height of the default font. Thus, if the value is
1603 .5, that means the window contents are scrolled up half the normal line
1604 height. If it is 3.3, that means the window contents are scrolled up
1605 somewhat over three times the normal line height.
1607 What fraction of a line the vertical scrolling covers, or how many
1608 lines, depends on what the lines contain. A value of .5 could scroll a
1609 line whose height is very short off the screen, while a value of 3.3
1610 could scroll just part of the way through a tall line or an image.
1612 @defun window-vscroll &optional window pixels-p
1613 This function returns the current vertical scroll position of
1614 @var{window}. If @var{window} is @code{nil}, the selected window is
1615 used. If @var{pixels-p} is non-@code{nil}, the return value is
1616 measured in pixels, rather than in units of the normal line height.
1626 @defun set-window-vscroll window lines &optional pixels-p
1627 This function sets @var{window}'s vertical scroll position to
1628 @var{lines}. The argument @var{lines} should be zero or positive; if
1629 not, it is taken as zero.
1631 If @var{window} is @code{nil}, the selected window is used.
1633 The actual vertical scroll position must always correspond
1634 to an integral number of pixels, so the value you specify
1635 is rounded accordingly.
1637 The return value is the result of this rounding.
1641 (set-window-vscroll (selected-window) 1.2)
1646 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
1647 pixels. In this case, the return value is @var{lines}.
1650 @defvar auto-window-vscroll
1651 If this variable is non-@code{nil}, the line-move, scroll-up, and
1652 scroll-down functions will automatically modify the window vscroll to
1653 scroll through display rows that are taller that the height of the
1654 window, for example in the presense of large images.
1657 @node Horizontal Scrolling
1658 @section Horizontal Scrolling
1659 @cindex horizontal scrolling
1661 @dfn{Horizontal scrolling} means shifting the image in the window left
1662 or right by a specified multiple of the normal character width. Each
1663 window has a @dfn{horizontal scroll position}, which is a number, never
1664 less than zero. It specifies how far to shift the contents left.
1665 Shifting the window contents left generally makes all or part of some
1666 characters disappear off the left, and all or part of some other
1667 characters appear at the right. The usual value is zero.
1669 The horizontal scroll position is measured in units of the normal
1670 character width, which is the width of space in the default font. Thus,
1671 if the value is 5, that means the window contents are scrolled left by 5
1672 times the normal character width. How many characters actually
1673 disappear off to the left depends on their width, and could vary from
1676 Because we read from side to side in the ``inner loop'', and from top
1677 to bottom in the ``outer loop'', the effect of horizontal scrolling is
1678 not like that of textual or vertical scrolling. Textual scrolling
1679 involves selection of a portion of text to display, and vertical
1680 scrolling moves the window contents contiguously; but horizontal
1681 scrolling causes part of @emph{each line} to go off screen.
1683 Usually, no horizontal scrolling is in effect; then the leftmost
1684 column is at the left edge of the window. In this state, scrolling to
1685 the right is meaningless, since there is no data to the left of the edge
1686 to be revealed by it; so this is not allowed. Scrolling to the left is
1687 allowed; it scrolls the first columns of text off the edge of the window
1688 and can reveal additional columns on the right that were truncated
1689 before. Once a window has a nonzero amount of leftward horizontal
1690 scrolling, you can scroll it back to the right, but only so far as to
1691 reduce the net horizontal scroll to zero. There is no limit to how far
1692 left you can scroll, but eventually all the text will disappear off the
1695 @vindex auto-hscroll-mode
1696 If @code{auto-hscroll-mode} is set, redisplay automatically alters
1697 the horizontal scrolling of a window as necessary to ensure that point
1698 is always visible. However, you can still set the horizontal
1699 scrolling value explicitly. The value you specify serves as a lower
1700 bound for automatic scrolling, i.e. automatic scrolling will not
1701 scroll a window to a column less than the specified one.
1703 @deffn Command scroll-left &optional count
1704 This function scrolls the selected window @var{count} columns to the
1705 left (or to the right if @var{count} is negative). The default
1706 for @var{count} is the window width, minus 2.
1708 The return value is the total amount of leftward horizontal scrolling in
1709 effect after the change---just like the value returned by
1710 @code{window-hscroll} (below).
1713 @deffn Command scroll-right &optional count
1714 This function scrolls the selected window @var{count} columns to the
1715 right (or to the left if @var{count} is negative). The default
1716 for @var{count} is the window width, minus 2.
1718 The return value is the total amount of leftward horizontal scrolling in
1719 effect after the change---just like the value returned by
1720 @code{window-hscroll} (below).
1722 Once you scroll a window as far right as it can go, back to its normal
1723 position where the total leftward scrolling is zero, attempts to scroll
1724 any farther right have no effect.
1727 @defun window-hscroll &optional window
1728 This function returns the total leftward horizontal scrolling of
1729 @var{window}---the number of columns by which the text in @var{window}
1730 is scrolled left past the left margin.
1732 The value is never negative. It is zero when no horizontal scrolling
1733 has been done in @var{window} (which is usually the case).
1735 If @var{window} is @code{nil}, the selected window is used.
1753 @defun set-window-hscroll window columns
1754 This function sets horizontal scrolling of @var{window}. The value of
1755 @var{columns} specifies the amount of scrolling, in terms of columns
1756 from the left margin. The argument @var{columns} should be zero or
1757 positive; if not, it is taken as zero. Fractional values of
1758 @var{columns} are not supported at present.
1760 Note that @code{set-window-hscroll} may appear not to work if you test
1761 it by evaluating a call with @kbd{M-:} in a simple way. What happens
1762 is that the function sets the horizontal scroll value and returns, but
1763 then redisplay adjusts the horizontal scrolling to make point visible,
1764 and this overrides what the function did. You can observe the
1765 function's effect if you call it while point is sufficiently far from
1766 the left margin that it will remain visible.
1768 The value returned is @var{columns}.
1772 (set-window-hscroll (selected-window) 10)
1778 Here is how you can determine whether a given position @var{position}
1779 is off the screen due to horizontal scrolling:
1783 (defun hscroll-on-screen (window position)
1785 (goto-char position)
1787 (>= (- (current-column) (window-hscroll window)) 0)
1788 (< (- (current-column) (window-hscroll window))
1789 (window-width window)))))
1793 @node Size of Window
1794 @section The Size of a Window
1796 @cindex size of window
1798 An Emacs window is rectangular, and its size information consists of
1799 the height (the number of lines) and the width (the number of character
1800 positions in each line). The mode line is included in the height. But
1801 the width does not count the scroll bar or the column of @samp{|}
1802 characters that separates side-by-side windows.
1804 The following three functions return size information about a window:
1806 @defun window-height &optional window
1807 This function returns the number of lines in @var{window}, including
1808 its mode line and header line, if any. If @var{window} fills its
1809 entire frame except for the echo area, this is typically one less than
1810 the value of @code{frame-height} on that frame.
1812 If @var{window} is @code{nil}, the function uses the selected window.
1820 (split-window-vertically)
1821 @result{} #<window 4 on windows.texi>
1830 @tindex window-body-height
1831 @defun window-body-height &optional window
1832 Like @code{window-height} but the value does not include the
1833 mode line (if any) or the header line (if any).
1836 @defun window-width &optional window
1837 This function returns the number of columns in @var{window}. If
1838 @var{window} fills its entire frame, this is the same as the value of
1839 @code{frame-width} on that frame. The width does not include the
1840 window's scroll bar or the column of @samp{|} characters that separates
1841 side-by-side windows.
1843 If @var{window} is @code{nil}, the function uses the selected window.
1853 @defun window-edges &optional window
1854 This function returns a list of the edge coordinates of @var{window}.
1855 If @var{window} is @code{nil}, the selected window is used.
1857 The order of the list is @code{(@var{left} @var{top} @var{right}
1858 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
1859 the frame. The element @var{right} of the value is one more than the
1860 rightmost column used by @var{window}, and @var{bottom} is one more than
1861 the bottommost row used by @var{window} and its mode-line.
1863 The edges include the space used by the window's scroll bar, display
1864 margins, fringes, header line, and mode line, if it has them. Also,
1865 if the window has a neighbor on the right, its right edge value
1866 includes the width of the separator line between the window and that
1867 neighbor. Since the width of the window does not include this
1868 separator, the width does not usually equal the difference between the
1869 right and left edges.
1872 @defun window-inside-edges &optional window
1873 This is similar to @code{window-edges}, but the edge values
1874 it returns include only the text area of the window. They
1875 do not include the header line, mode line, scroll bar or
1876 vertical separator, fringes, or display margins.
1879 Here are the results obtained on a typical 24-line terminal with just
1880 one window, with menu bar enabled:
1884 (window-edges (selected-window))
1885 @result{} (0 1 80 23)
1888 (window-inside-edges (selected-window))
1889 @result{} (0 1 80 22)
1894 The bottom edge is at line 23 because the last line is the echo area.
1895 The bottom inside edge is at line 22, which is the window's mode line.
1897 If @var{window} is at the upper left corner of its frame, and there is
1898 no menu bar, then @var{bottom} returned by @code{window-edges} is the
1899 same as the value of @code{(window-height)}, @var{right} is almost the
1900 same as the value of @code{(window-width)}, and @var{top} and
1901 @var{left} are zero. For example, the edges of the following window
1902 are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8
1903 columns, the last column of the window (column 7) holds a border
1904 rather than text. The last row (row 4) holds the mode line, shown
1905 here with @samp{xxxxxxxxx}.
1921 In the following example, let's suppose that the frame is 7
1922 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
1923 and the edges of the right window are @w{@samp{4 0 7 3}}.
1924 The inside edges of the left window are @w{@samp{0 0 3 2}},
1925 and the inside edges of the right window are @w{@samp{4 0 7 2}},
1938 @defun window-pixel-edges &optional window
1939 This function is like @code{window-edges} except that, on a graphical
1940 display, the edge values are measured in pixels instead of in
1941 character lines and columns.
1944 @defun window-inside-pixel-edges &optional window
1945 This function is like @code{window-inside-edges} except that, on a
1946 graphical display, the edge values are measured in pixels instead of
1947 in character lines and columns.
1950 @node Resizing Windows
1951 @section Changing the Size of a Window
1952 @cindex window resizing
1953 @cindex changing window size
1954 @cindex window size, changing
1956 The window size functions fall into two classes: high-level commands
1957 that change the size of windows and low-level functions that access
1958 window size. Emacs does not permit overlapping windows or gaps between
1959 windows, so resizing one window affects other windows.
1961 @deffn Command enlarge-window size &optional horizontal preserve-before
1962 This function makes the selected window @var{size} lines taller,
1963 stealing lines from neighboring windows. It takes the lines from one
1964 window at a time until that window is used up, then takes from another.
1965 If a window from which lines are stolen shrinks below
1966 @code{window-min-height} lines, that window disappears.
1968 If @var{horizontal} is non-@code{nil}, this function makes
1969 @var{window} wider by @var{size} columns, stealing columns instead of
1970 lines. If a window from which columns are stolen shrinks below
1971 @code{window-min-width} columns, that window disappears.
1973 If the requested size would exceed that of the window's frame, then the
1974 function makes the window occupy the entire height (or width) of the
1977 If there are various other windows from which lines or columns can be
1978 stolen, and some of them specify fixed size (using
1979 @code{window-size-fixed}, see below), they are left untouched while
1980 other windows are ``robbed.'' If it would be necessary to alter the
1981 size of a fixed-size window, @code{enlarge-window} gets an error
1984 If @var{preserve-before} is non-@code{nil}, this function does not
1985 change the size of the siblings above or to the left of the selected
1986 window. Only the size of the siblings below or to the right of the
1987 selected window are changed.
1989 If @var{size} is negative, this function shrinks the window by
1990 @minus{}@var{size} lines or columns. If that makes the window smaller
1991 than the minimum size (@code{window-min-height} and
1992 @code{window-min-width}), @code{enlarge-window} deletes the window.
1994 @code{enlarge-window} returns @code{nil}.
1997 @deffn Command enlarge-window-horizontally columns
1998 This function makes the selected window @var{columns} wider.
1999 It could be defined as follows:
2003 (defun enlarge-window-horizontally (columns)
2005 (enlarge-window columns t))
2010 @deffn Command shrink-window size &optional horizontal preserve-before
2011 This function is like @code{enlarge-window} but negates the argument
2012 @var{size}, making the selected window smaller by giving lines (or
2013 columns) to the other windows. If the window shrinks below
2014 @code{window-min-height} or @code{window-min-width}, then it disappears.
2016 If @var{size} is negative, the window is enlarged by @minus{}@var{size}
2020 @deffn Command shrink-window-horizontally columns
2021 This function makes the selected window @var{columns} narrower.
2022 It could be defined as follows:
2026 (defun shrink-window-horizontally (columns)
2028 (shrink-window columns t))
2033 @defun fit-window-to-buffer &optional window max-height min-height
2034 This function makes @var{window} the right height to display its
2035 contents exactly. If @var{window} is omitted or @code{nil}, it uses
2036 the selected window.
2038 The argument @var{max-height} specifies the maximum height the window
2039 is allowed to be; @code{nil} means use the frame height. The argument
2040 @var{min-height} specifies the minimum height for the window;
2041 @code{nil} means use @code{window-min-height}. All these height
2042 values include the mode-line and/or header-line.
2045 @deffn Command shrink-window-if-larger-than-buffer &optional window
2046 This command shrinks @var{window} vertically to be as small as
2047 possible while still showing the full contents of its buffer---but not
2048 less than @code{window-min-height} lines. If @var{window} is not
2049 given, it defaults to the selected window.
2051 However, the command does nothing if the window is already too small to
2052 display the whole text of the buffer, or if part of the contents are
2053 currently scrolled off screen, or if the window is not the full width of
2054 its frame, or if the window is the only window in its frame.
2056 This command returns non-@code{nil} if it actually shrank the window
2057 and @code{nil} otherwise.
2060 @tindex window-size-fixed
2061 @defvar window-size-fixed
2062 If this variable is non-@code{nil}, in any given buffer,
2063 then the size of any window displaying the buffer remains fixed
2064 unless you explicitly change it or Emacs has no other choice.
2066 If the value is @code{height}, then only the window's height is fixed;
2067 if the value is @code{width}, then only the window's width is fixed.
2068 Any other non-@code{nil} value fixes both the width and the height.
2070 This variable automatically becomes buffer-local when set.
2072 Explicit size-change functions such as @code{enlarge-window}
2073 get an error if they would have to change a window size which is fixed.
2074 Therefore, when you want to change the size of such a window,
2075 you should bind @code{window-size-fixed} to @code{nil}, like this:
2078 (let ((window-size-fixed nil))
2079 (enlarge-window 10))
2082 Note that changing the frame size will change the size of a
2083 fixed-size window, if there is no other alternative.
2086 @cindex minimum window size
2087 The following two variables constrain the window-structure-changing
2088 functions to a minimum height and width.
2090 @defopt window-min-height
2091 The value of this variable determines how short a window may become
2092 before it is automatically deleted. Making a window smaller than
2093 @code{window-min-height} automatically deletes it, and no window may
2094 be created shorter than this. The default value is 4.
2096 The absolute minimum window height is one; actions that change window
2097 sizes reset this variable to one if it is less than one.
2100 @defopt window-min-width
2101 The value of this variable determines how narrow a window may become
2102 before it is automatically deleted. Making a window smaller than
2103 @code{window-min-width} automatically deletes it, and no window may be
2104 created narrower than this. The default value is 10.
2106 The absolute minimum window width is two; actions that change window
2107 sizes reset this variable to two if it is less than two.
2110 @node Coordinates and Windows
2111 @section Coordinates and Windows
2113 This section describes how to relate screen coordinates to windows.
2115 @defun window-at x y &optional frame
2116 This function returns the window containing the specified cursor
2117 position in the frame @var{frame}. The coordinates @var{x} and @var{y}
2118 are measured in characters and count from the top left corner of the
2119 frame. If they are out of range, @code{window-at} returns @code{nil}.
2121 If you omit @var{frame}, the selected frame is used.
2124 @defun coordinates-in-window-p coordinates window
2125 This function checks whether a particular frame position falls within
2126 the window @var{window}.
2128 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
2129 . @var{y})}. The coordinates @var{x} and @var{y} are measured in
2130 characters, and count from the top left corner of the screen or frame.
2132 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
2133 if the coordinates are inside @var{window}. The value also indicates
2134 what part of the window the position is in, as follows:
2137 @item (@var{relx} . @var{rely})
2138 The coordinates are inside @var{window}. The numbers @var{relx} and
2139 @var{rely} are the equivalent window-relative coordinates for the
2140 specified position, counting from 0 at the top left corner of the
2144 The coordinates are in the mode line of @var{window}.
2147 The coordinates are in the header line of @var{window}.
2150 The coordinates are in the vertical line between @var{window} and its
2151 neighbor to the right. This value occurs only if the window doesn't
2152 have a scroll bar; positions in a scroll bar are considered outside the
2153 window for these purposes.
2157 The coordinates are in the left or right fringe of the window.
2161 The coordinates are in the left or right margin of the window.
2164 The coordinates are not in any part of @var{window}.
2167 The function @code{coordinates-in-window-p} does not require a frame as
2168 argument because it always uses the frame that @var{window} is on.
2171 @node Window Split Tree
2172 @section The Window Split Tree
2173 @cindex window split tree
2175 A @dfn{window split tree} specifies the layout, size, and relationship
2176 between all windows in one frame.
2178 @defun split-window-tree &optional frame
2179 This function returns the window split tree for frame @var{frame}.
2180 If @var{frame} is omitted, the selected frame is used.
2182 The return value is a list of the form @code{(@var{root} @var{mini})},
2183 where @var{root} represents the window split tree of the frame's
2184 root window, and @var{mini} is the frame's minibuffer window.
2186 If the root window is not split, @var{root} is the root window itself.
2187 Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
2188 @var{w2} ...)} where @var{dir} is @code{nil} for a horisontal split,
2189 and @code{t} for a vertical split, @var{edges} gives the combined size and
2190 position of the subwindows in the split, and the rest of the elements
2191 are the subwindows in the split. Each of the subwindows may again be
2192 a window or a list representing a window split, and so on. The
2193 @var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})}
2194 similar to the value returned by @code{window-edges}.
2197 @node Window Configurations
2198 @section Window Configurations
2199 @cindex window configurations
2200 @cindex saving window information
2202 A @dfn{window configuration} records the entire layout of one
2203 frame---all windows, their sizes, which buffers they contain, what
2204 part of each buffer is displayed, and the values of point and the
2205 mark; also their fringes, margins, and scroll bar settings. It also
2206 includes the values of @code{window-min-height},
2207 @code{window-min-width} and @code{minibuffer-scroll-window}. An
2208 exception is made for point in the selected window for the current
2209 buffer; its value is not saved in the window configuration.
2211 You can bring back an entire previous layout by restoring a window
2212 configuration previously saved. If you want to record all frames
2213 instead of just one, use a frame configuration instead of a window
2214 configuration. @xref{Frame Configurations}.
2216 @defun current-window-configuration &optional frame
2217 This function returns a new object representing @var{frame}'s current
2218 window configuration. If @var{frame} is omitted, the selected frame
2222 @defun set-window-configuration configuration
2223 This function restores the configuration of windows and buffers as
2224 specified by @var{configuration}, for the frame that @var{configuration}
2227 The argument @var{configuration} must be a value that was previously
2228 returned by @code{current-window-configuration}. This configuration is
2229 restored in the frame from which @var{configuration} was made, whether
2230 that frame is selected or not. This always counts as a window size
2231 change and triggers execution of the @code{window-size-change-functions}
2232 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
2233 know how to tell whether the new configuration actually differs from the
2236 If the frame which @var{configuration} was saved from is dead, all this
2237 function does is restore the three variables @code{window-min-height},
2238 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
2239 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
2241 Here is a way of using this function to get the same effect
2242 as @code{save-window-excursion}:
2246 (let ((config (current-window-configuration)))
2248 (progn (split-window-vertically nil)
2250 (set-window-configuration config)))
2255 @defspec save-window-excursion forms@dots{}
2256 This special form records the window configuration, executes @var{forms}
2257 in sequence, then restores the earlier window configuration. The window
2258 configuration includes, for each window, the value of point and the
2259 portion of the buffer that is visible. It also includes the choice of
2260 selected window. However, it does not include the value of point in
2261 the current buffer; use @code{save-excursion} also, if you wish to
2264 Don't use this construct when @code{save-selected-window} is sufficient.
2266 Exit from @code{save-window-excursion} always triggers execution of the
2267 @code{window-size-change-functions}. (It doesn't know how to tell
2268 whether the restored configuration actually differs from the one in
2269 effect at the end of the @var{forms}.)
2271 The return value is the value of the final form in @var{forms}.
2277 @result{} #<window 25 on control.texi>
2280 (setq w (selected-window))
2281 @result{} #<window 19 on control.texi>
2284 (save-window-excursion
2285 (delete-other-windows w)
2286 (switch-to-buffer "foo")
2288 @result{} do-something
2289 ;; @r{The screen is now split again.}
2294 @defun window-configuration-p object
2295 This function returns @code{t} if @var{object} is a window configuration.
2298 @defun compare-window-configurations config1 config2
2299 This function compares two window configurations as regards the
2300 structure of windows, but ignores the values of point and mark and the
2301 saved scrolling positions---it can return @code{t} even if those
2304 The function @code{equal} can also compare two window configurations; it
2305 regards configurations as unequal if they differ in any respect, even a
2306 saved point or mark.
2309 @defun window-configuration-frame config
2310 This function returns the frame for which the window configuration
2311 @var{config} was made.
2314 Other primitives to look inside of window configurations would make
2315 sense, but are not implemented because we did not need them. See the
2316 file @file{winner.el} for some more operations on windows
2320 @section Hooks for Window Scrolling and Changes
2322 This section describes how a Lisp program can take action whenever a
2323 window displays a different part of its buffer or a different buffer.
2324 There are three actions that can change this: scrolling the window,
2325 switching buffers in the window, and changing the size of the window.
2326 The first two actions run @code{window-scroll-functions}; the last runs
2327 @code{window-size-change-functions}.
2329 @defvar window-scroll-functions
2330 This variable holds a list of functions that Emacs should call before
2331 redisplaying a window with scrolling. It is not a normal hook, because
2332 each function is called with two arguments: the window, and its new
2333 display-start position.
2335 Displaying a different buffer in the window also runs these functions.
2337 These functions must be careful in using @code{window-end}
2338 (@pxref{Window Start}); if you need an up-to-date value, you must use
2339 the @var{update} argument to ensure you get it.
2342 @defvar window-size-change-functions
2343 This variable holds a list of functions to be called if the size of any
2344 window changes for any reason. The functions are called just once per
2345 redisplay, and just once for each frame on which size changes have
2348 Each function receives the frame as its sole argument. There is no
2349 direct way to find out which windows on that frame have changed size, or
2350 precisely how. However, if a size-change function records, at each
2351 call, the existing windows and their sizes, it can also compare the
2352 present sizes and the previous sizes.
2354 Creating or deleting windows counts as a size change, and therefore
2355 causes these functions to be called. Changing the frame size also
2356 counts, because it changes the sizes of the existing windows.
2358 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
2359 Configurations}) in these functions, because that always counts as a
2360 size change, and it would cause these functions to be called over and
2361 over. In most cases, @code{save-selected-window} (@pxref{Selecting
2362 Windows}) is what you need here.
2365 @defvar redisplay-end-trigger-functions
2366 This abnormal hook is run whenever redisplay in a window uses text that
2367 extends past a specified end trigger position. You set the end trigger
2368 position with the function @code{set-window-redisplay-end-trigger}. The
2369 functions are called with two arguments: the window, and the end trigger
2370 position. Storing @code{nil} for the end trigger position turns off the
2371 feature, and the trigger value is automatically reset to @code{nil} just
2372 after the hook is run.
2375 @defun set-window-redisplay-end-trigger window position
2376 This function sets @var{window}'s end trigger position at
2380 @defun window-redisplay-end-trigger &optional window
2381 This function returns @var{window}'s current end trigger position.
2382 If @var{window} is @code{nil} or omitted, it uses the selected window.
2385 @defvar window-configuration-change-hook
2386 A normal hook that is run every time you change the window configuration
2387 of an existing frame. This includes splitting or deleting windows,
2388 changing the sizes of windows, or displaying a different buffer in a
2389 window. The frame whose window configuration has changed is the
2390 selected frame when this hook runs.
2394 arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3