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
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-lever 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.
40 @section Basic Concepts of Emacs Windows
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:
81 window edges with respect to the screen or frame
84 the buffer it displays
87 position within the buffer at the upper left of the window
90 amount of horizontal scrolling, in columns
99 how recently the window was selected
102 @cindex multiple windows
103 Users create multiple windows so they can look at several buffers at
104 once. Lisp libraries use multiple windows for a variety of reasons, but
105 most often to display related information. In Rmail, for example, you
106 can move through a summary buffer in one window while the other window
107 shows messages one at a time as they are reached.
109 The meaning of ``window'' in Emacs is similar to what it means in the
110 context of general-purpose window systems such as X, but not identical.
111 The X Window System places X windows on the screen; Emacs uses one or
112 more X windows as frames, and subdivides them into
113 Emacs windows. When you use Emacs on a character-only terminal, Emacs
114 treats the whole terminal screen as one frame.
116 @cindex terminal screen
117 @cindex screen of terminal
118 @cindex tiled windows
119 Most window systems support arbitrarily located overlapping windows.
120 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
121 together they fill the whole screen or frame. Because of the way in
122 which Emacs creates new windows and resizes them, not all conceivable
123 tilings of windows on an Emacs frame are actually possible.
124 @xref{Splitting Windows}, and @ref{Size of Window}.
126 @xref{Display}, for information on how the contents of the
127 window's buffer are displayed in the window.
129 @defun windowp object
130 This function returns @code{t} if @var{object} is a window.
133 @node Splitting Windows
134 @section Splitting Windows
135 @cindex splitting windows
136 @cindex window splitting
138 The functions described here are the primitives used to split a window
139 into two windows. Two higher level functions sometimes split a window,
140 but not always: @code{pop-to-buffer} and @code{display-buffer}
141 (@pxref{Displaying Buffers}).
143 The functions described here do not accept a buffer as an argument.
144 The two ``halves'' of the split window initially display the same buffer
145 previously visible in the window that was split.
147 @deffn Command split-window &optional window size horizontal
148 This function splits @var{window} into two windows. The original
149 window @var{window} remains the selected window, but occupies only
150 part of its former screen area. The rest is occupied by a newly created
151 window which is returned as the value of this function.
153 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
154 two side by side windows. The original window @var{window} keeps the
155 leftmost @var{size} columns, and gives the rest of the columns to the
156 new window. Otherwise, it splits into windows one above the other, and
157 @var{window} keeps the upper @var{size} lines and gives the rest of the
158 lines to the new window. The original window is therefore the
159 left-hand or upper of the two, and the new window is the right-hand or
162 If @var{window} is omitted or @code{nil}, then the selected window is
163 split. If @var{size} is omitted or @code{nil}, then @var{window} is
164 divided evenly into two parts. (If there is an odd line, it is
165 allocated to the new window.) When @code{split-window} is called
166 interactively, all its arguments are @code{nil}.
168 If splitting would result in making a window that is smaller than
169 @code{window-min-height} or @code{window-min-width}, the function
170 signals an error and does not split the window at all.
172 The following example starts with one window on a screen that is 50
173 lines high by 80 columns wide; then it splits the window.
177 (setq w (selected-window))
178 @result{} #<window 8 on windows.texi>
179 (window-edges) ; @r{Edges in order:}
180 @result{} (0 0 80 50) ; @r{left--top--right--bottom}
184 ;; @r{Returns window created}
185 (setq w2 (split-window w 15))
186 @result{} #<window 28 on windows.texi>
190 @result{} (0 15 80 50) ; @r{Bottom window;}
195 @result{} (0 0 80 15) ; @r{Top window}
199 The screen looks like this:
215 Next, split the top window horizontally:
219 (setq w3 (split-window w 35 t))
220 @result{} #<window 32 on windows.texi>
224 @result{} (35 0 80 15) ; @r{Left edge at column 35}
228 @result{} (0 0 35 15) ; @r{Right edge at column 35}
232 @result{} (0 15 80 50) ; @r{Bottom window unchanged}
237 Now the screen looks like this:
254 Normally, Emacs indicates the border between two side-by-side windows
255 with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
256 characters. The display table can specify alternative border
257 characters; see @ref{Display Tables}.
260 @deffn Command split-window-vertically &optional size
261 This function splits the selected window into two windows, one above the
262 other, leaving the upper of the two windows selected, with @var{size}
263 lines. (If @var{size} is negative, then the lower of the two windows
264 gets @minus{} @var{size} lines and the upper window gets the rest, but
265 the upper window is still the one selected.)
268 @deffn Command split-window-horizontally &optional size
269 This function splits the selected window into two windows
270 side-by-side, leaving the selected window with @var{size} columns.
272 This function is basically an interface to @code{split-window}.
273 You could define a simplified version of the function like this:
277 (defun split-window-horizontally (&optional arg)
278 "Split selected window into two windows, side by side..."
282 (let ((size (and arg (prefix-numeric-value arg))))
284 (setq size (+ (window-width) size)))
285 (split-window nil size t)))
290 @defun one-window-p &optional no-mini all-frames
291 This function returns non-@code{nil} if there is only one window. The
292 argument @var{no-mini}, if non-@code{nil}, means don't count the
293 minibuffer even if it is active; otherwise, the minibuffer window is
294 included, if active, in the total number of windows, which is compared
297 The argument @var{all-frames} specifies which frames to consider. Here
298 are the possible values and their meanings:
302 Count the windows in the selected frame, plus the minibuffer used
303 by that frame even if it lies in some other frame.
306 Count all windows in all existing frames.
309 Count all windows in all visible frames.
312 Count all windows in all visible or iconified frames.
315 Count precisely the windows in the selected frame, and no others.
319 @node Deleting Windows
320 @section Deleting Windows
321 @cindex deleting windows
323 A window remains visible on its frame unless you @dfn{delete} it by
324 calling certain functions that delete windows. A deleted window cannot
325 appear on the screen, but continues to exist as a Lisp object until
326 there are no references to it. There is no way to cancel the deletion
327 of a window aside from restoring a saved window configuration
328 (@pxref{Window Configurations}). Restoring a window configuration also
329 deletes any windows that aren't part of that configuration.
331 When you delete a window, the space it took up is given to one
335 @defun window-live-p window
336 This function returns @code{nil} if @var{window} is deleted, and
339 @strong{Warning:} Erroneous information or fatal errors may result from
340 using a deleted window as if it were live.
343 @deffn Command delete-window &optional window
344 This function removes @var{window} from display, and returns @code{nil}.
345 If @var{window} is omitted, then the selected window is deleted. An
346 error is signaled if there is only one window when @code{delete-window}
350 @deffn Command delete-other-windows &optional window
351 This function makes @var{window} the only window on its frame, by
352 deleting the other windows in that frame. If @var{window} is omitted or
353 @code{nil}, then the selected window is used by default.
355 The return value is @code{nil}.
358 @deffn Command delete-windows-on buffer &optional frame
359 This function deletes all windows showing @var{buffer}. If there are
360 no windows showing @var{buffer}, it does nothing.
362 @code{delete-windows-on} operates frame by frame. If a frame has
363 several windows showing different buffers, then those showing
364 @var{buffer} are removed, and the others expand to fill the space. If
365 all windows in some frame are showing @var{buffer} (including the case
366 where there is only one window), then the frame reverts to having a
367 single window showing another buffer chosen with @code{other-buffer}.
368 @xref{The Buffer List}.
370 The argument @var{frame} controls which frames to operate on. This
371 function does not use it in quite the same way as the other functions
372 which scan all windows; specifically, the values @code{t} and @code{nil}
373 have the opposite of their meanings in other functions. Here are the
378 If it is @code{nil}, operate on all frames.
380 If it is @code{t}, operate on the selected frame.
382 If it is @code{visible}, operate on all visible frames.
384 If it is 0, operate on all visible or iconified frames.
386 If it is a frame, operate on that frame.
389 This function always returns @code{nil}.
392 @node Selecting Windows
393 @section Selecting Windows
394 @cindex selecting windows
396 When a window is selected, the buffer in the window becomes the current
397 buffer, and the cursor will appear in it.
399 @defun selected-window
400 This function returns the selected window. This is the window in
401 which the cursor appears and to which many commands apply.
404 @defun select-window window &optional norecord
405 This function makes @var{window} the selected window. The cursor then
406 appears in @var{window} (on redisplay). The buffer being displayed in
407 @var{window} is immediately designated the current buffer.
409 Normally @var{window}'s selected buffer is moved to the front of the
410 buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
413 The return value is @var{window}.
417 (setq w (next-window))
419 @result{} #<window 65 on windows.texi>
424 @defmac save-selected-window forms@dots{}
425 This macro records the selected window of eac frame, executes
426 @var{forms} in sequence, then restores the earlier selected windows.
428 This macro does not save or restore anything about the sizes,
429 arrangement or contents of windows; therefore, if the @var{forms}
430 change them, the change persists. If the previously selected window
431 of some frame is no longer live at the time of exit from this form,
432 that frame's selected window is left alone.
435 @defmac with-selected-window window forms@dots{}
436 This macro selects @var{window} (without changing the buffer list),
437 executes @var{forms} in sequence, then restores the previously
438 selected window (unless that window is no longer alive). It is similar
439 to @code{save-selected-window} except that it explicitly selects
440 @var{window} and that it does not alter the buffer list sequence.
443 @cindex finding windows
444 The following functions choose one of the windows on the screen,
445 offering various criteria for the choice.
447 @defun get-lru-window &optional frame
448 This function returns the window least recently ``used'' (that is,
449 selected). The selected window is always the most recently used window.
451 The selected window can be the least recently used window if it is the
452 only window. A newly created window becomes the least recently used
453 window until it is selected. A minibuffer window is never a candidate.
455 The argument @var{frame} controls which windows are considered.
459 If it is @code{nil}, consider windows on the selected frame.
461 If it is @code{t}, consider windows on all frames.
463 If it is @code{visible}, consider windows on all visible frames.
465 If it is 0, consider windows on all visible or iconified frames.
467 If it is a frame, consider windows on that frame.
471 @defun get-largest-window &optional frame
472 This function returns the window with the largest area (height times
473 width). If there are no side-by-side windows, then this is the window
474 with the most lines. A minibuffer window is never a candidate.
476 If there are two windows of the same size, then the function returns
477 the window that is first in the cyclic ordering of windows (see
478 following section), starting from the selected window.
480 The argument @var{frame} controls which set of windows to
481 consider. See @code{get-lru-window}, above.
484 @cindex window that satisfies a predicate
485 @cindex conditional selection of windows
486 @defun get-window-with-predicate predicate &optional minibuf all-frames default
487 This function returns a window satisfying @var{predicate}. It cycles
488 through all visible windows using @code{walk-windows} (@pxref{Cyclic
489 Window Ordering}), calling @var{predicate} on each one of them
490 with that window as its argument. The function returns the first
491 window for which @var{predicate} returns a non-@code{nil} value; if
492 that never happens, it returns @var{default}.
494 The optional arguments @var{minibuf} and @var{all-frames} specify the
495 set of windows to include in the scan. See the description of
496 @code{next-window} in @ref{Cyclic Window Ordering}, for details.
499 @node Cyclic Window Ordering
500 @comment node-name, next, previous, up
501 @section Cyclic Ordering of Windows
502 @cindex cyclic ordering of windows
503 @cindex ordering of windows, cyclic
504 @cindex window ordering, cyclic
506 When you use the command @kbd{C-x o} (@code{other-window}) to select
507 the next window, it moves through all the windows on the screen in a
508 specific cyclic order. For any given configuration of windows, this
509 order never varies. It is called the @dfn{cyclic ordering of windows}.
511 This ordering generally goes from top to bottom, and from left to
512 right. But it may go down first or go right first, depending on the
513 order in which the windows were split.
515 If the first split was vertical (into windows one above each other),
516 and then the subwindows were split horizontally, then the ordering is
517 left to right in the top of the frame, and then left to right in the
518 next lower part of the frame, and so on. If the first split was
519 horizontal, the ordering is top to bottom in the left part, and so on.
520 In general, within each set of siblings at any level in the window tree,
521 the order is left to right, or top to bottom.
523 @defun next-window &optional window minibuf all-frames
524 @cindex minibuffer window
525 This function returns the window following @var{window} in the cyclic
526 ordering of windows. This is the window that @kbd{C-x o} would select
527 if typed when @var{window} is selected. If @var{window} is the only
528 window visible, then this function returns @var{window}. If omitted,
529 @var{window} defaults to the selected window.
531 The value of the argument @var{minibuf} determines whether the
532 minibuffer is included in the window order. Normally, when
533 @var{minibuf} is @code{nil}, the minibuffer is included if it is
534 currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
535 window is active while the minibuffer is in use. @xref{Minibuffers}.)
537 If @var{minibuf} is @code{t}, then the cyclic ordering includes the
538 minibuffer window even if it is not active.
540 If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
541 window is not included even if it is active.
543 The argument @var{all-frames} specifies which frames to consider. Here
544 are the possible values and their meanings:
548 Consider all the windows in @var{window}'s frame, plus the minibuffer
549 used by that frame even if it lies in some other frame.
552 Consider all windows in all existing frames.
555 Consider all windows in all visible frames. (To get useful results, you
556 must ensure @var{window} is in a visible frame.)
559 Consider all windows in all visible or iconified frames.
562 Consider precisely the windows in @var{window}'s frame, and no others.
565 This example assumes there are two windows, both displaying the
566 buffer @samp{windows.texi}:
571 @result{} #<window 56 on windows.texi>
574 (next-window (selected-window))
575 @result{} #<window 52 on windows.texi>
578 (next-window (next-window (selected-window)))
579 @result{} #<window 56 on windows.texi>
584 @defun previous-window &optional window minibuf all-frames
585 This function returns the window preceding @var{window} in the cyclic
586 ordering of windows. The other arguments specify which windows to
587 include in the cycle, as in @code{next-window}.
590 @deffn Command other-window count &optional all-frames
591 This function selects the @var{count}th following window in the cyclic
592 order. If count is negative, then it moves back @minus{}@var{count}
593 windows in the cycle, rather than forward. It returns @code{nil}.
595 The argument @var{all-frames} has the same meaning as in
596 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
597 is always effectively @code{nil}.
599 In an interactive call, @var{count} is the numeric prefix argument.
603 @defun walk-windows proc &optional minibuf all-frames
604 This function cycles through all windows, calling @code{proc}
605 once for each window with the window as its sole argument.
607 The optional arguments @var{minibuf} and @var{all-frames} specify the
608 set of windows to include in the scan. See @code{next-window}, above,
612 @defun window-list &optional frame minibuf window
613 This function returns a list of the windows on @var{frame}, starting
614 with @var{window}. If @var{frame} is @code{nil} or omitted, the
615 selected frame is used instead; if @var{window} is @code{nil} or
616 omitted, the selected window is used instead.
618 The value of @var{minibuf} determines if the minibuffer window will be
619 included in the result list. If @var{minibuf} is @code{t}, the
620 minibuffer window will be included, even if it isn't active. If
621 @var{minibuf} is @code{nil} or omitted, the minibuffer window will
622 only be included in the list if it is active. If @var{minibuf} is
623 neither @code{nil} nor @code{t}, the minibuffer window is not
624 included, whether or not it is active.
627 @node Buffers and Windows
628 @section Buffers and Windows
629 @cindex examining windows
630 @cindex windows, controlling precisely
631 @cindex buffers, controlled in windows
633 This section describes low-level functions to examine windows or to
634 display buffers in windows in a precisely controlled fashion.
636 See the following section for
639 @xref{Displaying Buffers}, for
641 related functions that find a window to use and specify a buffer for it.
642 The functions described there are easier to use than these, but they
643 employ heuristics in choosing or creating a window; use these functions
644 when you need complete control.
646 @defun set-window-buffer window buffer-or-name &optional keep-margins
647 This function makes @var{window} display @var{buffer-or-name} as its
648 contents. It returns @code{nil}. This is the fundamental primitive
649 for changing which buffer is displayed in a window, and all ways
650 of doing that call this function.
654 (set-window-buffer (selected-window) "foo")
659 Normally, displaying @var{buffer} in @var{window} resets the window's
660 fringe widths and position based on the local variables of @var{buffer}.
661 However, if @var{keep-margins} is non-@code{nil}, the fringe widths and
662 position of @var{window} remain unchanged. @xref{Fringes}.
665 @defun window-buffer &optional window
666 This function returns the buffer that @var{window} is displaying. If
667 @var{window} is omitted, this function returns the buffer for the
673 @result{} #<buffer windows.texi>
678 @defun get-buffer-window buffer-or-name &optional all-frames
679 This function returns a window currently displaying
680 @var{buffer-or-name}, or @code{nil} if there is none. If there are
681 several such windows, then the function returns the first one in the
682 cyclic ordering of windows, starting from the selected window.
683 @xref{Cyclic Window Ordering}.
685 The argument @var{all-frames} controls which windows to consider.
689 If it is @code{nil}, consider windows on the selected frame.
691 If it is @code{t}, consider windows on all frames.
693 If it is @code{visible}, consider windows on all visible frames.
695 If it is 0, consider windows on all visible or iconified frames.
697 If it is a frame, consider windows on that frame.
701 @defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
702 This function returns a list of all the windows currently displaying
703 @var{buffer-or-name}.
705 The two optional arguments work like the optional arguments of
706 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
707 like the single optional argument of @code{get-buffer-window}. Perhaps
708 we should change @code{get-buffer-window} in the future to make it
709 compatible with the other functions.
711 The argument @var{all-frames} controls which windows to consider.
715 If it is @code{nil}, consider windows on the selected frame.
717 If it is @code{t}, consider windows on all frames.
719 If it is @code{visible}, consider windows on all visible frames.
721 If it is 0, consider windows on all visible or iconified frames.
723 If it is a frame, consider windows on that frame.
727 @defvar buffer-display-time
728 This variable records the time at which a buffer was last made visible
729 in a window. It is always local in each buffer; each time
730 @code{set-window-buffer} is called, it sets this variable to
731 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
732 When a buffer is first created, @code{buffer-display-time} starts out
733 with the value @code{nil}.
736 @node Displaying Buffers
737 @section Displaying Buffers in Windows
738 @cindex switching to a buffer
739 @cindex displaying a buffer
741 In this section we describe convenient functions that choose a window
742 automatically and use it to display a specified buffer. These functions
743 can also split an existing window in certain circumstances. We also
744 describe variables that parameterize the heuristics used for choosing a
747 See the preceding section for
750 @xref{Buffers and Windows}, for
752 low-level functions that give you more precise control. All of these
753 functions work by calling @code{set-window-buffer}.
755 Do not use the functions in this section in order to make a buffer
756 current so that a Lisp program can access or modify it; they are too
757 drastic for that purpose, since they change the display of buffers in
758 windows, which would be gratuitous and surprise the user. Instead, use
759 @code{set-buffer} and @code{save-current-buffer} (@pxref{Current
760 Buffer}), which designate buffers as current for programmed access
761 without affecting the display of buffers in windows.
763 @deffn Command switch-to-buffer buffer-or-name &optional norecord
764 This function makes @var{buffer-or-name} the current buffer, and also
765 displays the buffer in the selected window. This means that a human can
766 see the buffer and subsequent keyboard commands will apply to it.
767 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
768 the current buffer but does not display it in the selected window.
769 @xref{Current Buffer}.
771 If @var{buffer-or-name} does not identify an existing buffer, then a new
772 buffer by that name is created. The major mode for the new buffer is
773 set according to the variable @code{default-major-mode}. @xref{Auto
776 Normally the specified buffer is put at the front of the buffer list
777 (both the selected frame's buffer list and the frame-independent buffer
778 list). This affects the operation of @code{other-buffer}. However, if
779 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
782 The @code{switch-to-buffer} function is often used interactively, as
783 the binding of @kbd{C-x b}. It is also used frequently in programs. It
784 returns the buffer that it switched to.
787 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
788 This function makes @var{buffer-or-name} the current buffer and
789 displays it in a window not currently selected. It then selects that
790 window. The handling of the buffer is the same as in
791 @code{switch-to-buffer}.
793 The currently selected window is absolutely never used to do the job.
794 If it is the only window, then it is split to make a distinct window for
795 this purpose. If the selected window is already displaying the buffer,
796 then it continues to do so, but another window is nonetheless found to
797 display it in as well.
799 This function updates the buffer list just like @code{switch-to-buffer}
800 unless @var{norecord} is non-@code{nil}.
803 @defun pop-to-buffer buffer-or-name &optional other-window norecord
804 This function makes @var{buffer-or-name} the current buffer and
805 switches to it in some window, preferably not the window previously
806 selected. The ``popped-to'' window becomes the selected window within
807 its frame. The return value is the buffer that was switched to.
809 If the variable @code{pop-up-frames} is non-@code{nil},
810 @code{pop-to-buffer} looks for a window in any visible frame already
811 displaying the buffer; if there is one, it returns that window and makes
812 it be selected within its frame. If there is none, it creates a new
813 frame and displays the buffer in it.
815 If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
816 operates entirely within the selected frame. (If the selected frame has
817 just a minibuffer, @code{pop-to-buffer} operates within the most
818 recently selected frame that was not just a minibuffer.)
820 If the variable @code{pop-up-windows} is non-@code{nil}, windows may
821 be split to create a new window that is different from the original
822 window. For details, see @ref{Choosing Window}.
824 If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
825 creates another window even if @var{buffer-or-name} is already visible
826 in the selected window. Thus @var{buffer-or-name} could end up
827 displayed in two windows. On the other hand, if @var{buffer-or-name} is
828 already displayed in the selected window and @var{other-window} is
829 @code{nil}, then the selected window is considered sufficient display
830 for @var{buffer-or-name}, so that nothing needs to be done.
832 All the variables that affect @code{display-buffer} affect
833 @code{pop-to-buffer} as well. @xref{Choosing Window}.
835 If @var{buffer-or-name} is a string that does not name an existing
836 buffer, a buffer by that name is created. The major mode for the new
837 buffer is set according to the variable @code{default-major-mode}.
838 @xref{Auto Major Mode}.
840 This function updates the buffer list just like @code{switch-to-buffer}
841 unless @var{norecord} is non-@code{nil}.
844 @deffn Command replace-buffer-in-windows buffer
845 This function replaces @var{buffer} with some other buffer in all
846 windows displaying it. The other buffer used is chosen with
847 @code{other-buffer}. In the usual applications of this function, you
848 don't care which other buffer is used; you just want to make sure that
849 @var{buffer} is no longer displayed.
851 This function returns @code{nil}.
854 @node Choosing Window
855 @section Choosing a Window for Display
857 This section describes the basic facility that chooses a window to
858 display a buffer in---@code{display-buffer}. All the higher-level
859 functions and commands use this subroutine. Here we describe how to use
860 @code{display-buffer} and how to customize it.
862 @deffn Command display-buffer buffer-or-name &optional not-this-window frame
863 This command makes @var{buffer-or-name} appear in some window, like
864 @code{pop-to-buffer}, but it does not select that window and does not
865 make the buffer current. The identity of the selected window is
866 unaltered by this function.
868 If @var{not-this-window} is non-@code{nil}, it means to display the
869 specified buffer in a window other than the selected one, even if it is
870 already on display in the selected window. This can cause the buffer to
871 appear in two windows at once. Otherwise, if @var{buffer-or-name} is
872 already being displayed in any window, that is good enough, so this
873 function does nothing.
875 @code{display-buffer} returns the window chosen to display
876 @var{buffer-or-name}.
878 If the argument @var{frame} is non-@code{nil}, it specifies which frames
879 to check when deciding whether the buffer is already displayed. If the
880 buffer is already displayed in some window on one of these frames,
881 @code{display-buffer} simply returns that window. Here are the possible
882 values of @var{frame}:
886 If it is @code{nil}, consider windows on the selected frame.
888 If it is @code{t}, consider windows on all frames.
890 If it is @code{visible}, consider windows on all visible frames.
892 If it is 0, consider windows on all visible or iconified frames.
894 If it is a frame, consider windows on that frame.
897 Precisely how @code{display-buffer} finds or creates a window depends on
898 the variables described below.
901 @defopt display-buffer-reuse-frames
902 If this variable is non-@code{nil}, @code{display-buffer} searches
903 existing frames for a window displaying the buffer. If the buffer is
904 already displayed in a window in some frame, @code{display-buffer} makes
905 the frame visible and raises it, to use that window. If the buffer is
906 not already displayed, or if @code{display-buffer-reuse-frames} is
907 @code{nil}, @code{display-buffer}'s behavior is determined by other
908 variables, described below.
911 @defopt pop-up-windows
912 This variable controls whether @code{display-buffer} makes new windows.
913 If it is non-@code{nil} and there is only one window, then that window
914 is split. If it is @code{nil}, then @code{display-buffer} does not
915 split the single window, but uses it whole.
918 @defopt split-height-threshold
919 This variable determines when @code{display-buffer} may split a window,
920 if there are multiple windows. @code{display-buffer} always splits the
921 largest window if it has at least this many lines. If the largest
922 window is not this tall, it is split only if it is the sole window and
923 @code{pop-up-windows} is non-@code{nil}.
926 @defopt even-window-heights
927 This variable determines if @code{display-buffer} should even out window
928 heights if the buffer gets displayed in an existing window, above or
929 beneath another existing window. If @code{even-window-heights} is
930 @code{t}, the default, window heights will be evened out. If
931 @code{even-window-heights} is @code{nil}, the original window heights
936 @defopt pop-up-frames
937 This variable controls whether @code{display-buffer} makes new frames.
938 If it is non-@code{nil}, @code{display-buffer} looks for an existing
939 window already displaying the desired buffer, on any visible frame. If
940 it finds one, it returns that window. Otherwise it makes a new frame.
941 The variables @code{pop-up-windows} and @code{split-height-threshold} do
942 not matter if @code{pop-up-frames} is non-@code{nil}.
944 If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
945 splits a window or reuses one.
947 @xref{Frames}, for more information.
951 @defvar pop-up-frame-function
952 This variable specifies how to make a new frame if @code{pop-up-frames}
955 Its value should be a function of no arguments. When
956 @code{display-buffer} makes a new frame, it does so by calling that
957 function, which should return a frame. The default value of the
958 variable is a function that creates a frame using parameters from
959 @code{pop-up-frame-alist}.
962 @defopt pop-up-frame-alist
963 This variable holds an alist specifying frame parameters used when
964 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
965 more information about frame parameters.
968 @defopt special-display-buffer-names
969 A list of buffer names for buffers that should be displayed specially.
970 If the buffer's name is in this list, @code{display-buffer} handles the
973 By default, special display means to give the buffer a dedicated frame.
975 If an element is a list, instead of a string, then the @sc{car} of the
976 list is the buffer name, and the rest of the list says how to create
977 the frame. There are two possibilities for the rest of the list (its
978 @sc{cdr}). It can be an alist, specifying frame parameters, or it can
979 contain a function and arguments to give to it. (The function's first
980 argument is always the buffer to be displayed; the arguments from the
981 list come after that.)
986 (("myfile" (minibuffer) (menu-bar-lines . 0)))
990 specifies to display a buffer named @samp{myfile} in a dedicated frame
991 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
994 @defopt special-display-regexps
995 A list of regular expressions that specify buffers that should be
996 displayed specially. If the buffer's name matches any of the regular
997 expressions in this list, @code{display-buffer} handles the buffer
1000 By default, special display means to give the buffer a dedicated frame.
1002 If an element is a list, instead of a string, then the @sc{car} of the
1003 list is the regular expression, and the rest of the list says how to
1004 create the frame. See above, under @code{special-display-buffer-names}.
1007 @defvar special-display-function
1008 This variable holds the function to call to display a buffer specially.
1009 It receives the buffer as an argument, and should return the window in
1010 which it is displayed.
1012 The default value of this variable is
1013 @code{special-display-popup-frame}.
1016 @defun special-display-popup-frame buffer &rest args
1017 This function makes @var{buffer} visible in a frame of its own. If
1018 @var{buffer} is already displayed in a window in some frame, it makes
1019 the frame visible and raises it, to use that window. Otherwise, it
1020 creates a frame that will be dedicated to @var{buffer}.
1022 If @var{args} is an alist, it specifies frame parameters for the new
1025 If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
1026 @var{args})} is called as a function to actually create and set up the
1027 frame; it is called with @var{buffer} as first argument, and @code{(cdr
1028 @var{args})} as additional arguments.
1030 This function always uses an existing window displaying @var{buffer},
1031 whether or not it is in a frame of its own; but if you set up the above
1032 variables in your init file, before @var{buffer} was created, then
1033 presumably the window was previously made by this function.
1036 @defopt special-display-frame-alist
1037 This variable holds frame parameters for
1038 @code{special-display-popup-frame} to use when it creates a frame.
1041 @defopt same-window-buffer-names
1042 A list of buffer names for buffers that should be displayed in the
1043 selected window. If the buffer's name is in this list,
1044 @code{display-buffer} handles the buffer by switching to it in the
1048 @defopt same-window-regexps
1049 A list of regular expressions that specify buffers that should be
1050 displayed in the selected window. If the buffer's name matches any of
1051 the regular expressions in this list, @code{display-buffer} handles the
1052 buffer by switching to it in the selected window.
1056 @defvar display-buffer-function
1057 This variable is the most flexible way to customize the behavior of
1058 @code{display-buffer}. If it is non-@code{nil}, it should be a function
1059 that @code{display-buffer} calls to do the work. The function should
1060 accept two arguments, the same two arguments that @code{display-buffer}
1061 received. It should choose or create a window, display the specified
1062 buffer, and then return the window.
1064 This hook takes precedence over all the other options and hooks
1069 @cindex dedicated window
1070 A window can be marked as ``dedicated'' to its buffer. Then
1071 @code{display-buffer} will not try to use that window to display any
1074 @defun window-dedicated-p window
1075 This function returns @code{t} if @var{window} is marked as dedicated;
1076 otherwise @code{nil}.
1079 @defun set-window-dedicated-p window flag
1080 This function marks @var{window} as dedicated if @var{flag} is
1081 non-@code{nil}, and nondedicated otherwise.
1085 @section Windows and Point
1086 @cindex window position
1087 @cindex window point
1088 @cindex position in window
1089 @cindex point in window
1091 Each window has its own value of point, independent of the value of
1092 point in other windows displaying the same buffer. This makes it useful
1093 to have multiple windows showing one buffer.
1097 The window point is established when a window is first created; it is
1098 initialized from the buffer's point, or from the window point of another
1099 window opened on the buffer if such a window exists.
1102 Selecting a window sets the value of point in its buffer from the
1103 window's value of point. Conversely, deselecting a window sets the
1104 window's value of point from that of the buffer. Thus, when you switch
1105 between windows that display a given buffer, the point value for the
1106 selected window is in effect in the buffer, while the point values for
1107 the other windows are stored in those windows.
1110 As long as the selected window displays the current buffer, the window's
1111 point and the buffer's point always move together; they remain equal.
1114 @xref{Positions}, for more details on buffer positions.
1117 As far as the user is concerned, point is where the cursor is, and
1118 when the user switches to another buffer, the cursor jumps to the
1119 position of point in that buffer.
1121 @defun window-point &optional window
1122 This function returns the current position of point in @var{window}.
1123 For a nonselected window, this is the value point would have (in that
1124 window's buffer) if that window were selected. If @var{window} is
1125 @code{nil}, the selected window is used.
1127 When @var{window} is the selected window and its buffer is also the
1128 current buffer, the value returned is the same as point in that buffer.
1130 Strictly speaking, it would be more correct to return the
1131 ``top-level'' value of point, outside of any @code{save-excursion}
1132 forms. But that value is hard to find.
1135 @defun set-window-point window position
1136 This function positions point in @var{window} at position
1137 @var{position} in @var{window}'s buffer.
1141 @section The Window Start Position
1143 Each window contains a marker used to keep track of a buffer position
1144 that specifies where in the buffer display should start. This position
1145 is called the @dfn{display-start} position of the window (or just the
1146 @dfn{start}). The character after this position is the one that appears
1147 at the upper left corner of the window. It is usually, but not
1148 inevitably, at the beginning of a text line.
1150 @defun window-start &optional window
1151 @cindex window top line
1152 This function returns the display-start position of window
1153 @var{window}. If @var{window} is @code{nil}, the selected window is
1163 When you create a window, or display a different buffer in it, the
1164 display-start position is set to a display-start position recently used
1165 for the same buffer, or 1 if the buffer doesn't have any.
1167 Redisplay updates the window-start position (if you have not specified
1168 it explicitly since the previous redisplay)---for example, to make sure
1169 point appears on the screen. Nothing except redisplay automatically
1170 changes the window-start position; if you move point, do not expect the
1171 window-start position to change in response until after the next
1174 For a realistic example of using @code{window-start}, see the
1175 description of @code{count-lines} in @ref{Text Lines}.
1178 @defun window-end &optional window update
1179 This function returns the position of the end of the display in window
1180 @var{window}. If @var{window} is @code{nil}, the selected window is
1183 Simply changing the buffer text or moving point does not update the
1184 value that @code{window-end} returns. The value is updated only when
1185 Emacs redisplays and redisplay completes without being preempted.
1187 If the last redisplay of @var{window} was preempted, and did not finish,
1188 Emacs does not know the position of the end of display in that window.
1189 In that case, this function returns @code{nil}.
1191 If @var{update} is non-@code{nil}, @code{window-end} always returns an
1192 up-to-date value for where the window ends, based on the current
1193 @code{window-start} value. If the saved value is valid,
1194 @code{window-end} returns that; otherwise it computes the correct
1195 value by scanning the buffer text.
1197 Even if @var{update} is non-@code{nil}, @code{window-end} does not
1198 attempt to scroll the display if point has moved off the screen, the
1199 way real redisplay would do. It does not alter the
1200 @code{window-start} value. In effect, it reports where the displayed
1201 text will end if scrolling is not required.
1204 @defun set-window-start window position &optional noforce
1205 This function sets the display-start position of @var{window} to
1206 @var{position} in @var{window}'s buffer. It returns @var{position}.
1208 The display routines insist that the position of point be visible when a
1209 buffer is displayed. Normally, they change the display-start position
1210 (that is, scroll the window) whenever necessary to make point visible.
1211 However, if you specify the start position with this function using
1212 @code{nil} for @var{noforce}, it means you want display to start at
1213 @var{position} even if that would put the location of point off the
1214 screen. If this does place point off screen, the display routines move
1215 point to the left margin on the middle line in the window.
1217 For example, if point @w{is 1} and you set the start of the window @w{to
1218 2}, then point would be ``above'' the top of the window. The display
1219 routines will automatically move point if it is still 1 when redisplay
1220 occurs. Here is an example:
1224 ;; @r{Here is what @samp{foo} looks like before executing}
1225 ;; @r{the @code{set-window-start} expression.}
1229 ---------- Buffer: foo ----------
1230 @point{}This is the contents of buffer foo.
1236 ---------- Buffer: foo ----------
1242 (1+ (window-start)))
1247 ;; @r{Here is what @samp{foo} looks like after executing}
1248 ;; @r{the @code{set-window-start} expression.}
1249 ---------- Buffer: foo ----------
1250 his is the contents of buffer foo.
1256 ---------- Buffer: foo ----------
1260 If @var{noforce} is non-@code{nil}, and @var{position} would place point
1261 off screen at the next redisplay, then redisplay computes a new window-start
1262 position that works well with point, and thus @var{position} is not used.
1265 @defun pos-visible-in-window-p &optional position window partially
1266 This function returns @code{t} if @var{position} is within the range of
1267 text currently visible on the screen in @var{window}. It returns
1268 @code{nil} if @var{position} is scrolled vertically or horizontally out
1269 of view. Locations that are partially obscured are not considered
1270 visible unless @var{partially} is non-@code{nil}. The argument
1271 @var{position} defaults to the current position of point in
1272 @var{window}; @var{window}, to the selected window.
1278 (or (pos-visible-in-window-p
1279 (point) (selected-window))
1285 @node Textual Scrolling
1286 @section Textual Scrolling
1287 @cindex textual scrolling
1288 @cindex scrolling textually
1290 @dfn{Textual scrolling} means moving the text up or down though a
1291 window. It works by changing the value of the window's display-start
1292 location. It may also change the value of @code{window-point} to keep
1293 point on the screen.
1295 Textual scrolling was formerly called ``vertical scrolling,'' but we
1296 changed its name to distinguish it from the new vertical fractional
1297 scrolling feature (@pxref{Vertical Scrolling}).
1299 In the commands @code{scroll-up} and @code{scroll-down}, the directions
1300 ``up'' and ``down'' refer to the motion of the text in the buffer at which
1301 you are looking through the window. Imagine that the text is
1302 written on a long roll of paper and that the scrolling commands move the
1303 paper up and down. Thus, if you are looking at text in the middle of a
1304 buffer and repeatedly call @code{scroll-down}, you will eventually see
1305 the beginning of the buffer.
1307 Some people have urged that the opposite convention be used: they
1308 imagine that the window moves over text that remains in place. Then
1309 ``down'' commands would take you to the end of the buffer. This view is
1310 more consistent with the actual relationship between windows and the
1311 text in the buffer, but it is less like what the user sees. The
1312 position of a window on the terminal does not move, and short scrolling
1313 commands clearly move the text up or down on the screen. We have chosen
1314 names that fit the user's point of view.
1316 The textual scrolling functions (aside from
1317 @code{scroll-other-window}) have unpredictable results if the current
1318 buffer is different from the buffer that is displayed in the selected
1319 window. @xref{Current Buffer}.
1321 @deffn Command scroll-up &optional count
1322 This function scrolls the text in the selected window upward
1323 @var{count} lines. If @var{count} is negative, scrolling is actually
1326 If @var{count} is @code{nil} (or omitted), then the length of scroll
1327 is @code{next-screen-context-lines} lines less than the usable height of
1328 the window (not counting its mode line).
1330 @code{scroll-up} returns @code{nil}.
1333 @deffn Command scroll-down &optional count
1334 This function scrolls the text in the selected window downward
1335 @var{count} lines. If @var{count} is negative, scrolling is actually
1338 If @var{count} is omitted or @code{nil}, then the length of the scroll
1339 is @code{next-screen-context-lines} lines less than the usable height of
1340 the window (not counting its mode line).
1342 @code{scroll-down} returns @code{nil}.
1345 @deffn Command scroll-other-window &optional count
1346 This function scrolls the text in another window upward @var{count}
1347 lines. Negative values of @var{count}, or @code{nil}, are handled
1348 as in @code{scroll-up}.
1350 You can specify which buffer to scroll by setting the variable
1351 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
1352 already displayed, @code{scroll-other-window} displays it in some
1355 When the selected window is the minibuffer, the next window is normally
1356 the one at the top left corner. You can specify a different window to
1357 scroll, when the minibuffer is selected, by setting the variable
1358 @code{minibuffer-scroll-window}. This variable has no effect when any
1359 other window is selected. @xref{Minibuffer Misc}.
1361 When the minibuffer is active, it is the next window if the selected
1362 window is the one at the bottom right corner. In this case,
1363 @code{scroll-other-window} attempts to scroll the minibuffer. If the
1364 minibuffer contains just one line, it has nowhere to scroll to, so the
1365 line reappears after the echo area momentarily displays the message
1366 ``Beginning of buffer''.
1370 @defvar other-window-scroll-buffer
1371 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
1372 which buffer to scroll.
1375 @defopt scroll-margin
1376 This option specifies the size of the scroll margin---a minimum number
1377 of lines between point and the top or bottom of a window. Whenever
1378 point gets within this many lines of the top or bottom of the window,
1379 redisplay scrolls the text automatically (if possible) to move point
1380 out of the margin, closer to the center of the window.
1383 @defopt scroll-conservatively
1384 This variable controls how scrolling is done automatically when point
1385 moves off the screen (or into the scroll margin). If the value is a
1386 positive integer @var{n}, then redisplay scrolls the text up to
1387 @var{n} lines in either direction, if that will bring point back into
1388 proper view. This action is called @dfn{conservative scrolling}.
1389 Otherwise, scrolling happens in the usual way, under the control of
1390 other variables such as @code{scroll-up-aggressively} and
1391 @code{scroll-down-aggressively}.
1393 The default value is zero, which means that conservative scrolling
1397 @defopt scroll-down-aggressively
1398 @tindex scroll-down-aggressively
1399 The value of this variable should be either @code{nil} or a fraction
1400 @var{f} between 0 and 1. If it is a fraction, that specifies where on
1401 the screen to put point when scrolling down. More precisely, when a
1402 window scrolls down because point is above the window start, the new
1403 start position is chosen to put point @var{f} part of the window
1404 height from the top. The larger @var{f}, the more aggressive the
1407 A value of @code{nil} is equivalent to .5, since its effect is to center
1408 point. This variable automatically becomes buffer-local when set in any
1412 @defopt scroll-up-aggressively
1413 @tindex scroll-up-aggressively
1414 Likewise, for scrolling up. The value, @var{f}, specifies how far
1415 point should be placed from the bottom of the window; thus, as with
1416 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
1420 This variable is an older variant of @code{scroll-conservatively}. The
1421 difference is that it if its value is @var{n}, that permits scrolling
1422 only by precisely @var{n} lines, not a smaller number. This feature
1423 does not work with @code{scroll-margin}. The default value is zero.
1426 @defopt scroll-preserve-screen-position
1427 If this option is non-@code{nil}, the scroll functions move point so
1428 that the vertical position of the cursor is unchanged, when that is
1432 @defopt next-screen-context-lines
1433 The value of this variable is the number of lines of continuity to
1434 retain when scrolling by full screens. For example, @code{scroll-up}
1435 with an argument of @code{nil} scrolls so that this many lines at the
1436 bottom of the window appear instead at the top. The default value is
1440 @deffn Command recenter &optional count
1441 @cindex centering point
1442 This function scrolls the text in the selected window so that point is
1443 displayed at a specified vertical position within the window. It does
1444 not ``move point'' with respect to the text.
1446 If @var{count} is a nonnegative number, that puts the line containing
1447 point @var{count} lines down from the top of the window. If
1448 @var{count} is a negative number, then it counts upward from the
1449 bottom of the window, so that @minus{}1 stands for the last usable
1450 line in the window. If @var{count} is a non-@code{nil} list, then it
1451 stands for the line in the middle of the window.
1453 If @var{count} is @code{nil}, @code{recenter} puts the line containing
1454 point in the middle of the window, then clears and redisplays the entire
1457 When @code{recenter} is called interactively, @var{count} is the raw
1458 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
1459 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
1460 @var{count} to 4, which positions the current line four lines from the
1463 With an argument of zero, @code{recenter} positions the current line at
1464 the top of the window. This action is so handy that some people make a
1465 separate key binding to do this. For example,
1469 (defun line-to-top-of-window ()
1470 "Scroll current line to top of window.
1471 Replaces three keystroke sequence C-u 0 C-l."
1475 (global-set-key [kp-multiply] 'line-to-top-of-window)
1480 @node Vertical Scrolling
1481 @section Vertical Fractional Scrolling
1482 @cindex Vertical Fractional Scrolling
1484 @dfn{Vertical fractional scrolling} means shifting the image in the
1485 window up or down by a specified multiple or fraction of a line.
1486 Starting in Emacs 21, each window has a @dfn{vertical scroll position},
1487 which is a number, never less than zero. It specifies how far to raise
1488 the contents of the window. Raising the window contents generally makes
1489 all or part of some lines disappear off the top, and all or part of some
1490 other lines appear at the bottom. The usual value is zero.
1492 The vertical scroll position is measured in units of the normal line
1493 height, which is the height of the default font. Thus, if the value is
1494 .5, that means the window contents are scrolled up half the normal line
1495 height. If it is 3.3, that means the window contents are scrolled up
1496 somewhat over three times the normal line height.
1498 What fraction of a line the vertical scrolling covers, or how many
1499 lines, depends on what the lines contain. A value of .5 could scroll a
1500 line whose height is very short off the screen, while a value of 3.3
1501 could scroll just part of the way through a tall line or an image.
1503 @defun window-vscroll &optional window
1504 This function returns the current vertical scroll position of
1505 @var{window}, If @var{window} is @code{nil}, the selected window is
1516 @defun set-window-vscroll window lines
1517 This function sets @var{window}'s vertical scroll position to
1518 @var{lines}. The argument @var{lines} should be zero or positive; if
1519 not, it is taken as zero.
1521 If @var{window} is @code{nil}, the selected window is used.
1523 The actual vertical scroll position must always correspond
1524 to an integral number of pixels, so the value you specify
1525 is rounded accordingly.
1527 The return value is the result of this rounding.
1531 (set-window-vscroll (selected-window) 1.2)
1537 @node Horizontal Scrolling
1538 @section Horizontal Scrolling
1539 @cindex horizontal scrolling
1541 @dfn{Horizontal scrolling} means shifting the image in the window left
1542 or right by a specified multiple of the normal character width. Each
1543 window has a @dfn{horizontal scroll position}, which is a number, never
1544 less than zero. It specifies how far to shift the contents left.
1545 Shifting the window contents left generally makes all or part of some
1546 characters disappear off the left, and all or part of some other
1547 characters appear at the right. The usual value is zero.
1549 The horizontal scroll position is measured in units of the normal
1550 character width, which is the width of space in the default font. Thus,
1551 if the value is 5, that means the window contents are scrolled left by 5
1552 times the normal character width. How many characters actually
1553 disappear off to the left depends on their width, and could vary from
1556 Because we read from side to side in the ``inner loop'', and from top
1557 to bottom in the ``outer loop'', the effect of horizontal scrolling is
1558 not like that of textual or vertical scrolling. Textual scrolling
1559 involves selection of a portion of text to display, and vertical
1560 scrolling moves the window contents contiguously; but horizontal
1561 scrolling causes part of @emph{each line} to go off screen.
1563 Usually, no horizontal scrolling is in effect; then the leftmost
1564 column is at the left edge of the window. In this state, scrolling to
1565 the right is meaningless, since there is no data to the left of the edge
1566 to be revealed by it; so this is not allowed. Scrolling to the left is
1567 allowed; it scrolls the first columns of text off the edge of the window
1568 and can reveal additional columns on the right that were truncated
1569 before. Once a window has a nonzero amount of leftward horizontal
1570 scrolling, you can scroll it back to the right, but only so far as to
1571 reduce the net horizontal scroll to zero. There is no limit to how far
1572 left you can scroll, but eventually all the text will disappear off the
1575 @vindex auto-hscroll-mode
1576 In Emacs 21, redisplay automatically alters the horizontal scrolling
1577 of a window as necessary to ensure that point is always visible, if
1578 @code{auto-hscroll-mode} is set. However, you can still set the
1579 horizontal scrolling value explicitly. The value you specify serves as
1580 a lower bound for automatic scrolling, i.e. automatic scrolling
1581 will not scroll a window to a column less than the specified one.
1583 @deffn Command scroll-left &optional count
1584 This function scrolls the selected window @var{count} columns to the
1585 left (or to the right if @var{count} is negative). The default
1586 for @var{count} is the window width, minus 2.
1588 The return value is the total amount of leftward horizontal scrolling in
1589 effect after the change---just like the value returned by
1590 @code{window-hscroll} (below).
1593 @deffn Command scroll-right &optional count
1594 This function scrolls the selected window @var{count} columns to the
1595 right (or to the left if @var{count} is negative). The default
1596 for @var{count} is the window width, minus 2.
1598 The return value is the total amount of leftward horizontal scrolling in
1599 effect after the change---just like the value returned by
1600 @code{window-hscroll} (below).
1602 Once you scroll a window as far right as it can go, back to its normal
1603 position where the total leftward scrolling is zero, attempts to scroll
1604 any farther right have no effect.
1607 @defun window-hscroll &optional window
1608 This function returns the total leftward horizontal scrolling of
1609 @var{window}---the number of columns by which the text in @var{window}
1610 is scrolled left past the left margin.
1612 The value is never negative. It is zero when no horizontal scrolling
1613 has been done in @var{window} (which is usually the case).
1615 If @var{window} is @code{nil}, the selected window is used.
1633 @defun set-window-hscroll window columns
1634 This function sets the number of columns from the left margin that
1635 @var{window} is scrolled from the value of @var{columns}. The argument
1636 @var{columns} should be zero or positive; if not, it is taken as zero.
1637 Fractional values of @var{columns} are not supported at present.
1639 Note that @code{set-window-hscroll} may appear not to work if you test
1640 it by evaluating a call with @kbd{M-:} in a simple way. What happens
1641 is that the function sets the horizontal scroll value and returns, but
1642 then redisplay adjusts the horizontal scrolling to make point visible,
1643 and this overrides what the function did. You can observe the
1644 function's effect if you call it while point is sufficiently far from
1645 the left margin that it will remain visible.
1647 The value returned is @var{columns}.
1651 (set-window-hscroll (selected-window) 10)
1657 Here is how you can determine whether a given position @var{position}
1658 is off the screen due to horizontal scrolling:
1662 (defun hscroll-on-screen (window position)
1664 (goto-char position)
1666 (>= (- (current-column) (window-hscroll window)) 0)
1667 (< (- (current-column) (window-hscroll window))
1668 (window-width window)))))
1672 @node Size of Window
1673 @section The Size of a Window
1675 @cindex size of window
1677 An Emacs window is rectangular, and its size information consists of
1678 the height (the number of lines) and the width (the number of character
1679 positions in each line). The mode line is included in the height. But
1680 the width does not count the scroll bar or the column of @samp{|}
1681 characters that separates side-by-side windows.
1683 The following three functions return size information about a window:
1685 @defun window-height &optional window
1686 This function returns the number of lines in @var{window}, including
1687 its mode line and header line, if any. If @var{window} fills its
1688 entire frame except for the echo area, and there is no tool bar, this
1689 is typically one less than the value of @code{frame-height} on that
1692 If @var{window} is @code{nil}, the function uses the selected window.
1700 (split-window-vertically)
1701 @result{} #<window 4 on windows.texi>
1710 @tindex window-body-height
1711 @defun window-body-height &optional window
1712 Like @code{window-height} but the value does not include the
1713 mode line (if any) or the header line (if any).
1716 @defun window-width &optional window
1717 This function returns the number of columns in @var{window}. If
1718 @var{window} fills its entire frame, this is the same as the value of
1719 @code{frame-width} on that frame. The width does not include the
1720 window's scroll bar or the column of @samp{|} characters that separates
1721 side-by-side windows.
1723 If @var{window} is @code{nil}, the function uses the selected window.
1733 @defun window-edges &optional window
1734 This function returns a list of the edge coordinates of @var{window}.
1735 If @var{window} is @code{nil}, the selected window is used.
1737 The order of the list is @code{(@var{left} @var{top} @var{right}
1738 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
1739 the frame. The element @var{right} of the value is one more than the
1740 rightmost column used by @var{window}, and @var{bottom} is one more than
1741 the bottommost row used by @var{window} and its mode-line.
1743 If a window has a scroll bar, the right edge value includes the width of
1744 the scroll bar. Otherwise, if the window has a neighbor on the right,
1745 its right edge value includes the width of the separator line between
1746 the window and that neighbor. Since the width of the window does not
1747 include this separator, the width does not usually equal the difference
1748 between the right and left edges.
1751 @defun window-inside-edges window
1752 This is similar to @code{window-edges}, but the edge values
1753 it returns include only the text area of the window. They
1754 do not include the header line, mode line, scroll bar or
1755 vertical separator, fringes, or display margins.
1758 Here are the results obtained on a typical 24-line terminal with just
1759 one window, with menu bar enabled:
1763 (window-edges (selected-window))
1764 @result{} (0 1 80 23)
1767 (window-inside-edges (selected-window))
1768 @result{} (0 1 80 22)
1773 The bottom edge is at line 23 because the last line is the echo area.
1774 The bottom inside edge is at line 22, which is the window's mode line.
1776 If @var{window} is at the upper left corner of its frame, and there is
1777 no menu bar, then @var{bottom} returned by @code{window-edges} is the
1778 same as the value of @code{(window-height)}, @var{right} is almost the
1779 same as the value of @code{(window-width)}, and @var{top} and
1780 @var{left} are zero. For example, the edges of the following window
1781 are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8
1782 columns, the last column of the window (column 7) holds a border
1783 rather than text. The last row (row 4) holds the mode line, shown
1784 here with @samp{xxxxxxxxx}.
1800 In the following example, let's suppose that the frame is 7
1801 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
1802 and the edges of the right window are @w{@samp{4 0 7 3}}.
1803 The inside edges of the left window are @w{@samp{0 0 3 2}},
1804 and the inside edges of the right window are @w{@samp{4 0 7 2}},
1817 @defun window-pixel-edges window
1818 This function is like @code{window-edges} except that, on a graphical
1819 display, the edge values are measured in pixels instead of in
1820 character lines and columns.
1823 @defun window-inside-pixel-edges window
1824 This function is like @code{window-inside-edges} except that, on a
1825 graphical display, the edge values are measured in pixels instead of
1826 in character lines and columns.
1829 @node Resizing Windows
1830 @section Changing the Size of a Window
1831 @cindex window resizing
1832 @cindex changing window size
1833 @cindex window size, changing
1835 The window size functions fall into two classes: high-level commands
1836 that change the size of windows and low-level functions that access
1837 window size. Emacs does not permit overlapping windows or gaps between
1838 windows, so resizing one window affects other windows.
1840 @deffn Command enlarge-window size &optional horizontal
1841 This function makes the selected window @var{size} lines taller,
1842 stealing lines from neighboring windows. It takes the lines from one
1843 window at a time until that window is used up, then takes from another.
1844 If a window from which lines are stolen shrinks below
1845 @code{window-min-height} lines, that window disappears.
1847 If @var{horizontal} is non-@code{nil}, this function makes
1848 @var{window} wider by @var{size} columns, stealing columns instead of
1849 lines. If a window from which columns are stolen shrinks below
1850 @code{window-min-width} columns, that window disappears.
1852 If the requested size would exceed that of the window's frame, then the
1853 function makes the window occupy the entire height (or width) of the
1856 If there are various other windows from which lines or columns can be
1857 stolen, and some of them specify fixed size (using
1858 @code{window-size-fixed}, see below), they are left untouched while
1859 other windows are ``robbed.'' If it would be necessary to alter the
1860 size of a fixed-size window, @code{enlarge-window} gets an error
1863 If @var{size} is negative, this function shrinks the window by
1864 @minus{}@var{size} lines or columns. If that makes the window smaller
1865 than the minimum size (@code{window-min-height} and
1866 @code{window-min-width}), @code{enlarge-window} deletes the window.
1868 @code{enlarge-window} returns @code{nil}.
1871 @deffn Command enlarge-window-horizontally columns
1872 This function makes the selected window @var{columns} wider.
1873 It could be defined as follows:
1877 (defun enlarge-window-horizontally (columns)
1878 (enlarge-window columns t))
1883 @deffn Command shrink-window size &optional horizontal
1884 This function is like @code{enlarge-window} but negates the argument
1885 @var{size}, making the selected window smaller by giving lines (or
1886 columns) to the other windows. If the window shrinks below
1887 @code{window-min-height} or @code{window-min-width}, then it disappears.
1889 If @var{size} is negative, the window is enlarged by @minus{}@var{size}
1893 @deffn Command shrink-window-horizontally columns
1894 This function makes the selected window @var{columns} narrower.
1895 It could be defined as follows:
1899 (defun shrink-window-horizontally (columns)
1900 (shrink-window columns t))
1905 @deffn Command shrink-window-if-larger-than-buffer &optional window
1906 This command shrinks @var{window} to be as small as possible while still
1907 showing the full contents of its buffer---but not less than
1908 @code{window-min-height} lines. If @var{window} is not given,
1909 it defaults to the selected window.
1911 However, the command does nothing if the window is already too small to
1912 display the whole text of the buffer, or if part of the contents are
1913 currently scrolled off screen, or if the window is not the full width of
1914 its frame, or if the window is the only window in its frame.
1917 @tindex window-size-fixed
1918 @defvar window-size-fixed
1919 If this variable is non-@code{nil}, in any given buffer,
1920 then the size of any window displaying the buffer remains fixed
1921 unless you explicitly change it or Emacs has no other choice.
1922 (This feature is new in Emacs 21.)
1924 If the value is @code{height}, then only the window's height is fixed;
1925 if the value is @code{width}, then only the window's width is fixed.
1926 Any other non-@code{nil} value fixes both the width and the height.
1928 The usual way to use this variable is to give it a buffer-local value in
1929 a particular buffer. That way, the windows (but usually there is only
1930 one) displaying that buffer have fixed size.
1932 Explicit size-change functions such as @code{enlarge-window}
1933 get an error if they would have to change a window size which is fixed.
1934 Therefore, when you want to change the size of such a window,
1935 you should bind @code{window-size-fixed} to @code{nil}, like this:
1938 (let ((window-size-fixed nil))
1939 (enlarge-window 10))
1942 Note that changing the frame size will change the size of a
1943 fixed-size window, if there is no other alternative.
1946 @cindex minimum window size
1947 The following two variables constrain the window-structure-changing
1948 functions to a minimum height and width.
1950 @defopt window-min-height
1951 The value of this variable determines how short a window may become
1952 before it is automatically deleted. Making a window smaller than
1953 @code{window-min-height} automatically deletes it, and no window may
1954 be created shorter than this. The default value is 4.
1956 The absolute minimum window height is one; actions that change window
1957 sizes reset this variable to one if it is less than one.
1960 @defopt window-min-width
1961 The value of this variable determines how narrow a window may become
1962 before it is automatically deleted. Making a window smaller than
1963 @code{window-min-width} automatically deletes it, and no window may be
1964 created narrower than this. The default value is 10.
1966 The absolute minimum window width is two; actions that change window
1967 sizes reset this variable to two if it is less than two.
1970 @node Coordinates and Windows
1971 @section Coordinates and Windows
1973 This section describes how to relate screen coordinates to windows.
1975 @defun window-at x y &optional frame
1976 This function returns the window containing the specified cursor
1977 position in the frame @var{frame}. The coordinates @var{x} and @var{y}
1978 are measured in characters and count from the top left corner of the
1979 frame. If they are out of range, @code{window-at} returns @code{nil}.
1981 If you omit @var{frame}, the selected frame is used.
1984 @defun coordinates-in-window-p coordinates window
1985 This function checks whether a particular frame position falls within
1986 the window @var{window}.
1988 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
1989 . @var{y})}. The coordinates @var{x} and @var{y} are measured in
1990 characters, and count from the top left corner of the screen or frame.
1992 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
1993 if the coordinates are inside @var{window}. The value also indicates
1994 what part of the window the position is in, as follows:
1997 @item (@var{relx} . @var{rely})
1998 The coordinates are inside @var{window}. The numbers @var{relx} and
1999 @var{rely} are the equivalent window-relative coordinates for the
2000 specified position, counting from 0 at the top left corner of the
2004 The coordinates are in the mode line of @var{window}.
2007 The coordinates are in the header line of @var{window}.
2010 The coordinates are in the vertical line between @var{window} and its
2011 neighbor to the right. This value occurs only if the window doesn't
2012 have a scroll bar; positions in a scroll bar are considered outside the
2013 window for these purposes.
2016 The coordinates are not in any part of @var{window}.
2019 The function @code{coordinates-in-window-p} does not require a frame as
2020 argument because it always uses the frame that @var{window} is on.
2023 @node Window Configurations
2024 @section Window Configurations
2025 @cindex window configurations
2026 @cindex saving window information
2028 A @dfn{window configuration} records the entire layout of one
2029 frame---all windows, their sizes, which buffers they contain, what
2030 part of each buffer is displayed, and the values of point and the
2031 mark. It also includes the values of @code{window-min-height},
2032 @code{window-min-width} and @code{minibuffer-scroll-window}. An
2033 exception is made for point in the selected window for the current
2034 buffer; its value is not saved in the window configuration.
2036 You can bring back an entire previous layout by restoring a window
2037 configuration previously saved. If you want to record all frames
2038 instead of just one, use a frame configuration instead of a window
2039 configuration. @xref{Frame Configurations}.
2041 @defun current-window-configuration &optional frame
2042 This function returns a new object representing @var{frame}'s current
2043 window configuration. If @var{frame} is omitted, the selected frame
2047 @defun set-window-configuration configuration
2048 This function restores the configuration of windows and buffers as
2049 specified by @var{configuration}, for the frame that @var{configuration}
2052 The argument @var{configuration} must be a value that was previously
2053 returned by @code{current-window-configuration}. This configuration is
2054 restored in the frame from which @var{configuration} was made, whether
2055 that frame is selected or not. This always counts as a window size
2056 change and triggers execution of the @code{window-size-change-functions}
2057 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
2058 know how to tell whether the new configuration actually differs from the
2061 If the frame which @var{configuration} was saved from is dead, all this
2062 function does is restore the three variables @code{window-min-height},
2063 @code{window-min-width} and @code{minibuffer-scroll-window}.
2065 Here is a way of using this function to get the same effect
2066 as @code{save-window-excursion}:
2070 (let ((config (current-window-configuration)))
2072 (progn (split-window-vertically nil)
2074 (set-window-configuration config)))
2079 @defspec save-window-excursion forms@dots{}
2080 This special form records the window configuration, executes @var{forms}
2081 in sequence, then restores the earlier window configuration. The window
2082 configuration includes the value of point and the portion of the buffer
2083 that is visible. It also includes the choice of selected window.
2084 However, it does not include the value of point in the current buffer;
2085 use @code{save-excursion} also, if you wish to preserve that.
2087 Don't use this construct when @code{save-selected-window} is sufficient.
2089 Exit from @code{save-window-excursion} always triggers execution of the
2090 @code{window-size-change-functions}. (It doesn't know how to tell
2091 whether the restored configuration actually differs from the one in
2092 effect at the end of the @var{forms}.)
2094 The return value is the value of the final form in @var{forms}.
2100 @result{} #<window 25 on control.texi>
2103 (setq w (selected-window))
2104 @result{} #<window 19 on control.texi>
2107 (save-window-excursion
2108 (delete-other-windows w)
2109 (switch-to-buffer "foo")
2111 @result{} do-something
2112 ;; @r{The screen is now split again.}
2117 @defun window-configuration-p object
2118 This function returns @code{t} if @var{object} is a window configuration.
2121 @defun compare-window-configurations config1 config2
2122 This function compares two window configurations as regards the
2123 structure of windows, but ignores the values of point and mark and the
2124 saved scrolling positions---it can return @code{t} even if those
2127 The function @code{equal} can also compare two window configurations; it
2128 regards configurations as unequal if they differ in any respect, even a
2129 saved point or mark.
2132 Primitives to look inside of window configurations would make sense,
2133 but none are implemented. It is not clear they are useful enough to
2134 be worth implementing. See the file @file{winner.el} for some more
2135 operations on windows configurations.
2138 @section Hooks for Window Scrolling and Changes
2140 This section describes how a Lisp program can take action whenever a
2141 window displays a different part of its buffer or a different buffer.
2142 There are three actions that can change this: scrolling the window,
2143 switching buffers in the window, and changing the size of the window.
2144 The first two actions run @code{window-scroll-functions}; the last runs
2145 @code{window-size-change-functions}. The paradigmatic use of these
2146 hooks is in the implementation of Lazy Lock mode; see @file{lazy-lock.el}.
2148 @defvar window-scroll-functions
2149 This variable holds a list of functions that Emacs should call before
2150 redisplaying a window with scrolling. It is not a normal hook, because
2151 each function is called with two arguments: the window, and its new
2152 display-start position.
2154 Displaying a different buffer in the window also runs these functions.
2156 These functions must be careful in using @code{window-end}
2157 (@pxref{Window Start}); if you need an up-to-date value, you must use
2158 the @var{update} argument to ensure you get it.
2161 @defvar window-size-change-functions
2162 This variable holds a list of functions to be called if the size of any
2163 window changes for any reason. The functions are called just once per
2164 redisplay, and just once for each frame on which size changes have
2167 Each function receives the frame as its sole argument. There is no
2168 direct way to find out which windows on that frame have changed size, or
2169 precisely how. However, if a size-change function records, at each
2170 call, the existing windows and their sizes, it can also compare the
2171 present sizes and the previous sizes.
2173 Creating or deleting windows counts as a size change, and therefore
2174 causes these functions to be called. Changing the frame size also
2175 counts, because it changes the sizes of the existing windows.
2177 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
2178 Configurations}) in these functions, because that always counts as a
2179 size change, and it would cause these functions to be called over and
2180 over. In most cases, @code{save-selected-window} (@pxref{Selecting
2181 Windows}) is what you need here.
2184 @defvar redisplay-end-trigger-functions
2185 This abnormal hook is run whenever redisplay in a window uses text that
2186 extends past a specified end trigger position. You set the end trigger
2187 position with the function @code{set-window-redisplay-end-trigger}. The
2188 functions are called with two arguments: the window, and the end trigger
2189 position. Storing @code{nil} for the end trigger position turns off the
2190 feature, and the trigger value is automatically reset to @code{nil} just
2191 after the hook is run.
2194 @defun set-window-redisplay-end-trigger window position
2195 This function sets @var{window}'s end trigger position at
2199 @defun window-redisplay-end-trigger &optional window
2200 This function returns @var{window}'s current end trigger position.
2203 @defvar window-configuration-change-hook
2204 A normal hook that is run every time you change the window configuration
2205 of an existing frame. This includes splitting or deleting windows,
2206 changing the sizes of windows, or displaying a different buffer in a
2207 window. The frame whose window configuration has changed is the
2208 selected frame when this hook runs.