2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/windows
6 @node Windows, Frames, Buffers, Top
9 This chapter describes most of the functions and variables related to
10 Emacs windows. See @ref{Display}, for information on how text is
14 * Basic Windows:: Basic information on using windows.
15 * Splitting Windows:: Splitting one window into two windows.
16 * Deleting Windows:: Deleting a window gives its space to other windows.
17 * Selecting Windows:: The selected window is the one that you edit in.
18 * Cyclic Window Ordering:: Moving around the existing windows.
19 * Buffers and Windows:: Each window displays the contents of a buffer.
20 * Displaying Buffers:: Higher-lever functions for displaying a buffer
21 and choosing a window for it.
22 * Choosing Window:: How to choose a window for displaying a buffer.
23 * Window Point:: Each window has its own location of point.
24 * Window Start:: The display-start position controls which text
25 is on-screen in the window.
26 * Vertical Scrolling:: Moving text up and down in the window.
27 * Horizontal Scrolling:: Moving text sideways on the window.
28 * Size of Window:: Accessing the size of a window.
29 * Resizing Windows:: Changing the size of a window.
30 * Coordinates and Windows:: Converting coordinates to windows.
31 * Window Configurations:: Saving and restoring the state of the screen.
32 * Window Hooks:: Hooks for scrolling, window size changes,
33 redisplay going past a certain point,
34 or window configuration changes.
38 @section Basic Concepts of Emacs Windows
40 @cindex selected window
42 A @dfn{window} in Emacs is the physical area of the screen in which a
43 buffer is displayed. The term is also used to refer to a Lisp object that
44 represents that screen area in Emacs Lisp. It should be
45 clear from the context which is meant.
47 Emacs groups windows into frames. A frame represents an area of
48 screen available for Emacs to use. Each frame always contains at least
49 one window, but you can subdivide it vertically or horizontally into
50 multiple nonoverlapping Emacs windows.
52 In each frame, at any time, one and only one window is designated as
53 @dfn{selected within the frame}. The frame's cursor appears in that
54 window. At any time, one frame is the selected frame; and the window
55 selected within that frame is @dfn{the selected window}. The selected
56 window's buffer is usually the current buffer (except when
57 @code{set-buffer} has been used). @xref{Current Buffer}.
59 For practical purposes, a window exists only while it is displayed in
60 a frame. Once removed from the frame, the window is effectively deleted
61 and should not be used, @emph{even though there may still be references
62 to it} from other Lisp objects. Restoring a saved window configuration
63 is the only way for a window no longer on the screen to come back to
64 life. (@xref{Deleting Windows}.)
66 Each window has the following attributes:
79 window edges with respect to the screen or frame
82 the buffer it displays
85 position within the buffer at the upper left of the window
88 amount of horizontal scrolling, in columns
97 how recently the window was selected
100 @cindex multiple windows
101 Users create multiple windows so they can look at several buffers at
102 once. Lisp libraries use multiple windows for a variety of reasons, but
103 most often to display related information. In Rmail, for example, you
104 can move through a summary buffer in one window while the other window
105 shows messages one at a time as they are reached.
107 The meaning of ``window'' in Emacs is similar to what it means in the
108 context of general-purpose window systems such as X, but not identical.
109 The X Window System places X windows on the screen; Emacs uses one or
110 more X windows as frames, and subdivides them into
111 Emacs windows. When you use Emacs on a character-only terminal, Emacs
112 treats the whole terminal screen as one frame.
114 @cindex terminal screen
115 @cindex screen of terminal
116 @cindex tiled windows
117 Most window systems support arbitrarily located overlapping windows.
118 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
119 together they fill the whole screen or frame. Because of the way in
120 which Emacs creates new windows and resizes them, not all conceivable
121 tilings of windows on an Emacs frame are actually possible.
122 @xref{Splitting Windows}, and @ref{Size of Window}.
124 @xref{Display}, for information on how the contents of the
125 window's buffer are displayed in the window.
127 @defun windowp object
128 This function returns @code{t} if @var{object} is a window.
131 @node Splitting Windows
132 @section Splitting Windows
133 @cindex splitting windows
134 @cindex window splitting
136 The functions described here are the primitives used to split a window
137 into two windows. Two higher level functions sometimes split a window,
138 but not always: @code{pop-to-buffer} and @code{display-buffer}
139 (@pxref{Displaying Buffers}).
141 The functions described here do not accept a buffer as an argument.
142 The two ``halves'' of the split window initially display the same buffer
143 previously visible in the window that was split.
145 @deffn Command split-window &optional window size horizontal
146 This function splits @var{window} into two windows. The original
147 window @var{window} remains the selected window, but occupies only
148 part of its former screen area. The rest is occupied by a newly created
149 window which is returned as the value of this function.
151 If @var{horizontal} is non-@code{nil}, then @var{window} splits into
152 two side by side windows. The original window @var{window} keeps the
153 leftmost @var{size} columns, and gives the rest of the columns to the
154 new window. Otherwise, it splits into windows one above the other, and
155 @var{window} keeps the upper @var{size} lines and gives the rest of the
156 lines to the new window. The original window is therefore the
157 left-hand or upper of the two, and the new window is the right-hand or
160 If @var{window} is omitted or @code{nil}, then the selected window is
161 split. If @var{size} is omitted or @code{nil}, then @var{window} is
162 divided evenly into two parts. (If there is an odd line, it is
163 allocated to the new window.) When @code{split-window} is called
164 interactively, all its arguments are @code{nil}.
166 The following example starts with one window on a screen that is 50
167 lines high by 80 columns wide; then the window is split.
171 (setq w (selected-window))
172 @result{} #<window 8 on windows.texi>
173 (window-edges) ; @r{Edges in order:}
174 @result{} (0 0 80 50) ; @r{left--top--right--bottom}
178 ;; @r{Returns window created}
179 (setq w2 (split-window w 15))
180 @result{} #<window 28 on windows.texi>
184 @result{} (0 15 80 50) ; @r{Bottom window;}
189 @result{} (0 0 80 15) ; @r{Top window}
193 The screen looks like this:
209 Next, the top window is split horizontally:
213 (setq w3 (split-window w 35 t))
214 @result{} #<window 32 on windows.texi>
218 @result{} (35 0 80 15) ; @r{Left edge at column 35}
222 @result{} (0 0 35 15) ; @r{Right edge at column 35}
226 @result{} (0 15 80 50) ; @r{Bottom window unchanged}
231 Now, the screen looks like this:
248 Normally, Emacs indicates the border between two side-by-side windows
249 with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
250 characters. The display table can specify alternative border
251 characters; see @ref{Display Tables}.
254 @deffn Command split-window-vertically size
255 This function splits the selected window into two windows, one above
256 the other, leaving the selected window with @var{size} lines.
258 This function is simply an interface to @code{split-windows}.
259 Here is the complete function definition for it:
263 (defun split-window-vertically (&optional arg)
264 "Split current window into two windows, @dots{}"
266 (split-window nil (and arg (prefix-numeric-value arg))))
271 @deffn Command split-window-horizontally size
272 This function splits the selected window into two windows
273 side-by-side, leaving the selected window with @var{size} columns.
275 This function is simply an interface to @code{split-windows}. Here is
276 the complete definition for @code{split-window-horizontally} (except for
277 part of the documentation string):
281 (defun split-window-horizontally (&optional arg)
282 "Split selected window into two windows, side by side..."
284 (split-window nil (and arg (prefix-numeric-value arg)) t))
289 @defun one-window-p &optional no-mini all-frames
290 This function returns non-@code{nil} if there is only one window. The
291 argument @var{no-mini}, if non-@code{nil}, means don't count the
292 minibuffer even if it is active; otherwise, the minibuffer window is
293 included, if active, in the total number of windows, which is compared
296 The argument @var{all-frames} specifies which frames to consider. Here
297 are the possible values and their meanings:
301 Count the windows in the selected frame, plus the minibuffer used
302 by that frame even if it lies in some other frame.
305 Count all windows in all existing frames.
308 Count all windows in all visible frames.
311 Count all windows in all visible or iconified frames.
314 Count precisely the windows in the selected frame, and no others.
318 @node Deleting Windows
319 @section Deleting Windows
320 @cindex deleting windows
322 A window remains visible on its frame unless you @dfn{delete} it by
323 calling certain functions that delete windows. A deleted window cannot
324 appear on the screen, but continues to exist as a Lisp object until
325 there are no references to it. There is no way to cancel the deletion
326 of a window aside from restoring a saved window configuration
327 (@pxref{Window Configurations}). Restoring a window configuration also
328 deletes any windows that aren't part of that configuration.
330 When you delete a window, the space it took up is given to one
334 @defun window-live-p window
335 This function returns @code{nil} if @var{window} is deleted, and
338 @strong{Warning:} Erroneous information or fatal errors may result from
339 using a deleted window as if it were live.
342 @deffn Command delete-window &optional window
343 This function removes @var{window} from display, and returns @code{nil}.
344 If @var{window} is omitted, then the selected window is deleted. An
345 error is signaled if there is only one window when @code{delete-window}
349 @deffn Command delete-other-windows &optional window
350 This function makes @var{window} the only window on its frame, by
351 deleting the other windows in that frame. If @var{window} is omitted or
352 @code{nil}, then the selected window is used by default.
354 The return value is @code{nil}.
357 @deffn Command delete-windows-on buffer &optional frame
358 This function deletes all windows showing @var{buffer}. If there are
359 no windows showing @var{buffer}, it does nothing.
361 @code{delete-windows-on} operates frame by frame. If a frame has
362 several windows showing different buffers, then those showing
363 @var{buffer} are removed, and the others expand to fill the space. If
364 all windows in some frame are showing @var{buffer} (including the case
365 where there is only one window), then the frame reverts to having a
366 single window showing another buffer chosen with @code{other-buffer}.
367 @xref{The Buffer List}.
369 The argument @var{frame} controls which frames to operate on:
373 If it is @code{nil}, operate on the selected frame.
375 If it is @code{t}, operate on all frames.
377 If it is @code{visible}, operate on all visible frames.
379 If it is 0, operate on all visible or iconified frames.
381 If it is a frame, operate on that frame.
384 This function always returns @code{nil}.
387 @node Selecting Windows
388 @section Selecting Windows
389 @cindex selecting windows
391 When a window is selected, the buffer in the window becomes the current
392 buffer, and the cursor will appear in it.
394 @defun selected-window
395 This function returns the selected window. This is the window in
396 which the cursor appears and to which many commands apply.
399 @defun select-window window
400 This function makes @var{window} the selected window. The cursor then
401 appears in @var{window} (on redisplay). The buffer being displayed in
402 @var{window} is immediately designated the current buffer.
404 The return value is @var{window}.
408 (setq w (next-window))
410 @result{} #<window 65 on windows.texi>
415 @defmac save-selected-window forms@dots{}
416 This macro records the selected window, executes @var{forms}
417 in sequence, then restores the earlier selected window.
419 This macro does not save or restore anything about the sizes, arrangement
420 or contents of windows; therefore, if the @var{forms} change them,
423 Each frame, at any time, has a window selected within the frame. This
424 macro saves only @emph{the} selected window; it does not save anything
425 about other frames. If the @var{forms} select some other frame and
426 alter the window selected within it, the change persists.
429 @cindex finding windows
430 The following functions choose one of the windows on the screen,
431 offering various criteria for the choice.
433 @defun get-lru-window &optional frame
434 This function returns the window least recently ``used'' (that is,
435 selected). The selected window is always the most recently used window.
437 The selected window can be the least recently used window if it is the
438 only window. A newly created window becomes the least recently used
439 window until it is selected. A minibuffer window is never a candidate.
441 The argument @var{frame} controls which windows are considered.
445 If it is @code{nil}, consider windows on the selected frame.
447 If it is @code{t}, consider windows on all frames.
449 If it is @code{visible}, consider windows on all visible frames.
451 If it is 0, consider windows on all visible or iconified frames.
453 If it is a frame, consider windows on that frame.
457 @defun get-largest-window &optional frame
458 This function returns the window with the largest area (height times
459 width). If there are no side-by-side windows, then this is the window
460 with the most lines. A minibuffer window is never a candidate.
462 If there are two windows of the same size, then the function returns
463 the window that is first in the cyclic ordering of windows (see
464 following section), starting from the selected window.
466 The argument @var{frame} controls which set of windows are
467 considered. See @code{get-lru-window}, above.
470 @node Cyclic Window Ordering
471 @comment node-name, next, previous, up
472 @section Cyclic Ordering of Windows
473 @cindex cyclic ordering of windows
474 @cindex ordering of windows, cyclic
475 @cindex window ordering, cyclic
477 When you use the command @kbd{C-x o} (@code{other-window}) to select
478 the next window, it moves through all the windows on the screen in a
479 specific cyclic order. For any given configuration of windows, this
480 order never varies. It is called the @dfn{cyclic ordering of windows}.
482 This ordering generally goes from top to bottom, and from left to
483 right. But it may go down first or go right first, depending on the
484 order in which the windows were split.
486 If the first split was vertical (into windows one above each other),
487 and then the subwindows were split horizontally, then the ordering is
488 left to right in the top of the frame, and then left to right in the
489 next lower part of the frame, and so on. If the first split was
490 horizontal, the ordering is top to bottom in the left part, and so on.
491 In general, within each set of siblings at any level in the window tree,
492 the order is left to right, or top to bottom.
494 @defun next-window &optional window minibuf all-frames
495 @cindex minibuffer window
496 This function returns the window following @var{window} in the cyclic
497 ordering of windows. This is the window that @kbd{C-x o} would select
498 if typed when @var{window} is selected. If @var{window} is the only
499 window visible, then this function returns @var{window}. If omitted,
500 @var{window} defaults to the selected window.
502 The value of the argument @var{minibuf} determines whether the
503 minibuffer is included in the window order. Normally, when
504 @var{minibuf} is @code{nil}, the minibuffer is included if it is
505 currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
506 window is active while the minibuffer is in use. @xref{Minibuffers}.)
508 If @var{minibuf} is @code{t}, then the cyclic ordering includes the
509 minibuffer window even if it is not active.
511 If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
512 window is not included even if it is active.
514 The argument @var{all-frames} specifies which frames to consider. Here
515 are the possible values and their meanings:
519 Consider all the windows in @var{window}'s frame, plus the minibuffer
520 used by that frame even if it lies in some other frame.
523 Consider all windows in all existing frames.
526 Consider all windows in all visible frames. (To get useful results, you
527 must ensure @var{window} is in a visible frame.)
530 Consider all windows in all visible or iconified frames.
533 Consider precisely the windows in @var{window}'s frame, and no others.
536 This example assumes there are two windows, both displaying the
537 buffer @samp{windows.texi}:
542 @result{} #<window 56 on windows.texi>
545 (next-window (selected-window))
546 @result{} #<window 52 on windows.texi>
549 (next-window (next-window (selected-window)))
550 @result{} #<window 56 on windows.texi>
555 @defun previous-window &optional window minibuf all-frames
556 This function returns the window preceding @var{window} in the cyclic
557 ordering of windows. The other arguments specify which windows to
558 include in the cycle, as in @code{next-window}.
561 @deffn Command other-window count
562 This function selects the @var{count}th following window in the cyclic
563 order. If count is negative, then it moves back @minus{}@var{count}
564 windows in the cycle, rather than forward. It returns @code{nil}.
566 In an interactive call, @var{count} is the numeric prefix argument.
570 @defun walk-windows proc &optional minibuf all-frames
571 This function cycles through all windows, calling @code{proc}
572 once for each window with the window as its sole argument.
574 The optional arguments @var{minibuf} and @var{all-frames} specify the
575 set of windows to include in the scan. See @code{next-window}, above,
579 @node Buffers and Windows
580 @section Buffers and Windows
581 @cindex examining windows
582 @cindex windows, controlling precisely
583 @cindex buffers, controlled in windows
585 This section describes low-level functions to examine windows or to
586 display buffers in windows in a precisely controlled fashion.
588 See the following section for
591 @xref{Displaying Buffers}, for
593 related functions that find a window to use and specify a buffer for it.
594 The functions described there are easier to use than these, but they
595 employ heuristics in choosing or creating a window; use these functions
596 when you need complete control.
598 @defun set-window-buffer window buffer-or-name
599 This function makes @var{window} display @var{buffer-or-name} as its
600 contents. It returns @code{nil}. This is the fundamental primitive
601 for changing which buffer is displayed in a window, and all ways
602 of doing that call this function.
606 (set-window-buffer (selected-window) "foo")
612 @defun window-buffer &optional window
613 This function returns the buffer that @var{window} is displaying. If
614 @var{window} is omitted, this function returns the buffer for the
620 @result{} #<buffer windows.texi>
625 @defun get-buffer-window buffer-or-name &optional all-frames
626 This function returns a window currently displaying
627 @var{buffer-or-name}, or @code{nil} if there is none. If there are
628 several such windows, then the function returns the first one in the
629 cyclic ordering of windows, starting from the selected window.
630 @xref{Cyclic Window Ordering}.
632 The argument @var{all-frames} controls which windows to consider.
636 If it is @code{nil}, consider windows on the selected frame.
638 If it is @code{t}, consider windows on all frames.
640 If it is @code{visible}, consider windows on all visible frames.
642 If it is 0, consider windows on all visible or iconified frames.
644 If it is a frame, consider windows on that frame.
648 @defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
649 This function returns a list of all the windows currently displaying
650 @var{buffer-or-name}.
652 The two optional arguments work like the optional arguments of
653 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
654 like the single optional argument of @code{get-buffer-window}. Perhaps
655 we should change @code{get-buffer-window} in the future to make it
656 compatible with the other functions.
658 The argument @var{all-frames} controls which windows to consider.
662 If it is @code{nil}, consider windows on the selected frame.
664 If it is @code{t}, consider windows on all frames.
666 If it is @code{visible}, consider windows on all visible frames.
668 If it is 0, consider windows on all visible or iconified frames.
670 If it is a frame, consider windows on that frame.
674 @defvar buffer-display-time
675 @tindex buffer-display-time
676 This variable records the time at which a buffer was last made visible
677 in a window. It is always local in each buffer; each time
678 @code{set-window-buffer} is called, it sets this variable to
679 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
680 When a buffer is first created, @code{buffer-display-count} starts out
681 with the value @code{nil}.
684 @node Displaying Buffers
685 @section Displaying Buffers in Windows
686 @cindex switching to a buffer
687 @cindex displaying a buffer
689 In this section we describe convenient functions that choose a window
690 automatically and use it to display a specified buffer. These functions
691 can also split an existing window in certain circumstances. We also
692 describe variables that parameterize the heuristics used for choosing a
695 See the preceding section for
698 @xref{Buffers and Windows}, for
700 low-level functions that give you more precise control. All of these
701 functions work by calling @code{set-window-buffer}.
703 Do not use the functions in this section in order to make a buffer
704 current so that a Lisp program can access or modify it; they are too
705 drastic for that purpose, since they change the display of buffers in
706 windows, which would be gratuitous and surprise the user. Instead, use
707 @code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion}
708 (@pxref{Excursions}), which designate buffers as current for programmed
709 access without affecting the display of buffers in windows.
711 @deffn Command switch-to-buffer buffer-or-name &optional norecord
712 This function makes @var{buffer-or-name} the current buffer, and also
713 displays the buffer in the selected window. This means that a human can
714 see the buffer and subsequent keyboard commands will apply to it.
715 Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
716 the current buffer but does not display it in the selected window.
717 @xref{Current Buffer}.
719 If @var{buffer-or-name} does not identify an existing buffer, then a new
720 buffer by that name is created. The major mode for the new buffer is
721 set according to the variable @code{default-major-mode}. @xref{Auto
724 Normally the specified buffer is put at the front of the buffer list
725 (both the selected frame's buffer list and the frame-independent buffer
726 list). This affects the operation of @code{other-buffer}. However, if
727 @var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
730 The @code{switch-to-buffer} function is often used interactively, as
731 the binding of @kbd{C-x b}. It is also used frequently in programs. It
732 always returns @code{nil}.
735 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
736 This function makes @var{buffer-or-name} the current buffer and
737 displays it in a window not currently selected. It then selects that
738 window. The handling of the buffer is the same as in
739 @code{switch-to-buffer}.
741 The currently selected window is absolutely never used to do the job.
742 If it is the only window, then it is split to make a distinct window for
743 this purpose. If the selected window is already displaying the buffer,
744 then it continues to do so, but another window is nonetheless found to
745 display it in as well.
747 This function updates the buffer list just like @code{switch-to-buffer}
748 unless @var{norecord} is non-@code{nil}.
751 @defun pop-to-buffer buffer-or-name &optional other-window norecord
752 This function makes @var{buffer-or-name} the current buffer and
753 switches to it in some window, preferably not the window previously
754 selected. The ``popped-to'' window becomes the selected window within
757 If the variable @code{pop-up-frames} is non-@code{nil},
758 @code{pop-to-buffer} looks for a window in any visible frame already
759 displaying the buffer; if there is one, it returns that window and makes
760 it be selected within its frame. If there is none, it creates a new
761 frame and displays the buffer in it.
763 If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
764 operates entirely within the selected frame. (If the selected frame has
765 just a minibuffer, @code{pop-to-buffer} operates within the most
766 recently selected frame that was not just a minibuffer.)
768 If the variable @code{pop-up-windows} is non-@code{nil}, windows may
769 be split to create a new window that is different from the original
770 window. For details, see @ref{Choosing Window}.
772 If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
773 creates another window even if @var{buffer-or-name} is already visible
774 in the selected window. Thus @var{buffer-or-name} could end up
775 displayed in two windows. On the other hand, if @var{buffer-or-name} is
776 already displayed in the selected window and @var{other-window} is
777 @code{nil}, then the selected window is considered sufficient display
778 for @var{buffer-or-name}, so that nothing needs to be done.
780 All the variables that affect @code{display-buffer} affect
781 @code{pop-to-buffer} as well. @xref{Choosing Window}.
783 If @var{buffer-or-name} is a string that does not name an existing
784 buffer, a buffer by that name is created. The major mode for the new
785 buffer is set according to the variable @code{default-major-mode}.
786 @xref{Auto Major Mode}.
788 This function updates the buffer list just like @code{switch-to-buffer}
789 unless @var{norecord} is non-@code{nil}.
792 @deffn Command replace-buffer-in-windows buffer
793 This function replaces @var{buffer} with some other buffer in all
794 windows displaying it. The other buffer used is chosen with
795 @code{other-buffer}. In the usual applications of this function, you
796 don't care which other buffer is used; you just want to make sure that
797 @var{buffer} is no longer displayed.
799 This function returns @code{nil}.
802 @node Choosing Window
803 @section Choosing a Window for Display
805 This section describes the basic facility that chooses a window to
806 display a buffer in---@code{display-buffer}. All the higher-level
807 functions and commands use this subroutine. Here we describe how to use
808 @code{display-buffer} and how to customize it.
810 @deffn Command display-buffer buffer-or-name &optional not-this-window frame
811 This command makes @var{buffer-or-name} appear in some window, like
812 @code{pop-to-buffer}, but it does not select that window and does not
813 make the buffer current. The identity of the selected window is
814 unaltered by this function.
816 If @var{not-this-window} is non-@code{nil}, it means to display the
817 specified buffer in a window other than the selected one, even if it is
818 already on display in the selected window. This can cause the buffer to
819 appear in two windows at once. Otherwise, if @var{buffer-or-name} is
820 already being displayed in any window, that is good enough, so this
821 function does nothing.
823 @code{display-buffer} returns the window chosen to display
824 @var{buffer-or-name}.
826 If the argument @var{frame} is non-@code{nil}, it specifies which frames
827 to check when deciding whether the buffer is already displayed. Its
828 value means the same thing as in functions @code{get-buffer-window}
829 (@pxref{Buffers and Windows}). If the buffer is already displayed
830 in some window on one of these frames, @code{display-buffer} simply
833 Precisely how @code{display-buffer} finds or creates a window depends on
834 the variables described below.
837 @defopt pop-up-windows
838 This variable controls whether @code{display-buffer} makes new windows.
839 If it is non-@code{nil} and there is only one window, then that window
840 is split. If it is @code{nil}, then @code{display-buffer} does not
841 split the single window, but uses it whole.
844 @defopt split-height-threshold
845 This variable determines when @code{display-buffer} may split a window,
846 if there are multiple windows. @code{display-buffer} always splits the
847 largest window if it has at least this many lines. If the largest
848 window is not this tall, it is split only if it is the sole window and
849 @code{pop-up-windows} is non-@code{nil}.
853 @defopt pop-up-frames
854 This variable controls whether @code{display-buffer} makes new frames.
855 If it is non-@code{nil}, @code{display-buffer} looks for an existing
856 window already displaying the desired buffer, on any visible frame. If
857 it finds one, it returns that window. Otherwise it makes a new frame.
858 The variables @code{pop-up-windows} and @code{split-height-threshold} do
859 not matter if @code{pop-up-frames} is non-@code{nil}.
861 If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
862 splits a window or reuses one.
864 @xref{Frames}, for more information.
868 @defvar pop-up-frame-function
869 This variable specifies how to make a new frame if @code{pop-up-frames}
872 Its value should be a function of no arguments. When
873 @code{display-buffer} makes a new frame, it does so by calling that
874 function, which should return a frame. The default value of the
875 variable is a function that creates a frame using parameters from
876 @code{pop-up-frame-alist}.
879 @defvar pop-up-frame-alist
880 This variable holds an alist specifying frame parameters used when
881 @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
882 more information about frame parameters.
885 @defvar special-display-buffer-names
886 A list of buffer names for buffers that should be displayed specially.
887 If the buffer's name is in this list, @code{display-buffer} handles the
890 By default, special display means to give the buffer a dedicated frame.
892 If an element is a list, instead of a string, then the @sc{car} of the
893 list is the buffer name, and the rest of the list says how to create the
894 frame. There are two possibilities for the rest of the list. It can be
895 an alist, specifying frame parameters, or it can contain a function and
896 arguments to give to it. (The function's first argument is always the
897 buffer to be displayed; the arguments from the list come after that.)
900 @defvar special-display-regexps
901 A list of regular expressions that specify buffers that should be
902 displayed specially. If the buffer's name matches any of the regular
903 expressions in this list, @code{display-buffer} handles the buffer
906 By default, special display means to give the buffer a dedicated frame.
908 If an element is a list, instead of a string, then the @sc{car} of the
909 list is the regular expression, and the rest of the list says how to
910 create the frame. See above, under @code{special-display-buffer-names}.
913 @defvar special-display-function
914 This variable holds the function to call to display a buffer specially.
915 It receives the buffer as an argument, and should return the window in
916 which it is displayed.
918 The default value of this variable is
919 @code{special-display-popup-frame}.
922 @defun special-display-popup-frame buffer
923 This function makes @var{buffer} visible in a frame of its own. If
924 @var{buffer} is already displayed in a window in some frame, it makes
925 the frame visible and raises it, to use that window. Otherwise, it
926 creates a frame that will be dedicated to @var{buffer}.
928 This function uses an existing window displaying @var{buffer} whether or
929 not it is in a frame of its own; but if you set up the above variables
930 in your init file, before @var{buffer} was created, then presumably the
931 window was previously made by this function.
934 @defopt special-display-frame-alist
935 This variable holds frame parameters for
936 @code{special-display-popup-frame} to use when it creates a frame.
939 @defopt same-window-buffer-names
940 A list of buffer names for buffers that should be displayed in the
941 selected window. If the buffer's name is in this list,
942 @code{display-buffer} handles the buffer by switching to it in the
946 @defopt same-window-regexps
947 A list of regular expressions that specify buffers that should be
948 displayed in the selected window. If the buffer's name matches any of
949 the regular expressions in this list, @code{display-buffer} handles the
950 buffer by switching to it in the selected window.
954 @defvar display-buffer-function
955 This variable is the most flexible way to customize the behavior of
956 @code{display-buffer}. If it is non-@code{nil}, it should be a function
957 that @code{display-buffer} calls to do the work. The function should
958 accept two arguments, the same two arguments that @code{display-buffer}
959 received. It should choose or create a window, display the specified
960 buffer, and then return the window.
962 This hook takes precedence over all the other options and hooks
967 @cindex dedicated window
968 A window can be marked as ``dedicated'' to its buffer. Then
969 @code{display-buffer} will not try to use that window to display any
972 @defun window-dedicated-p window
973 This function returns @code{t} if @var{window} is marked as dedicated;
974 otherwise @code{nil}.
977 @defun set-window-dedicated-p window flag
978 This function marks @var{window} as dedicated if @var{flag} is
979 non-@code{nil}, and nondedicated otherwise.
983 @section Windows and Point
984 @cindex window position
986 @cindex position in window
987 @cindex point in window
989 Each window has its own value of point, independent of the value of
990 point in other windows displaying the same buffer. This makes it useful
991 to have multiple windows showing one buffer.
995 The window point is established when a window is first created; it is
996 initialized from the buffer's point, or from the window point of another
997 window opened on the buffer if such a window exists.
1000 Selecting a window sets the value of point in its buffer from the
1001 window's value of point. Conversely, deselecting a window sets the
1002 window's value of point from that of the buffer. Thus, when you switch
1003 between windows that display a given buffer, the point value for the
1004 selected window is in effect in the buffer, while the point values for
1005 the other windows are stored in those windows.
1008 As long as the selected window displays the current buffer, the window's
1009 point and the buffer's point always move together; they remain equal.
1012 @xref{Positions}, for more details on buffer positions.
1015 As far as the user is concerned, point is where the cursor is, and
1016 when the user switches to another buffer, the cursor jumps to the
1017 position of point in that buffer.
1019 @defun window-point window
1020 This function returns the current position of point in @var{window}.
1021 For a nonselected window, this is the value point would have (in that
1022 window's buffer) if that window were selected.
1024 When @var{window} is the selected window and its buffer is also the
1025 current buffer, the value returned is the same as point in that buffer.
1027 Strictly speaking, it would be more correct to return the
1028 ``top-level'' value of point, outside of any @code{save-excursion}
1029 forms. But that value is hard to find.
1032 @defun set-window-point window position
1033 This function positions point in @var{window} at position
1034 @var{position} in @var{window}'s buffer.
1038 @section The Window Start Position
1040 Each window contains a marker used to keep track of a buffer position
1041 that specifies where in the buffer display should start. This position
1042 is called the @dfn{display-start} position of the window (or just the
1043 @dfn{start}). The character after this position is the one that appears
1044 at the upper left corner of the window. It is usually, but not
1045 inevitably, at the beginning of a text line.
1047 @defun window-start &optional window
1048 @cindex window top line
1049 This function returns the display-start position of window
1050 @var{window}. If @var{window} is @code{nil}, the selected window is
1060 When you create a window, or display a different buffer in it, the
1061 display-start position is set to a display-start position recently used
1062 for the same buffer, or 1 if the buffer doesn't have any.
1064 Redisplay updates the window-start position (if you have not specified
1065 it explicitly since the previous redisplay) so that point appears on the
1066 screen. Nothing except redisplay automatically changes the window-start
1067 position; if you move point, do not expect the window-start position to
1068 change in response until after the next redisplay.
1070 For a realistic example of using @code{window-start}, see the
1071 description of @code{count-lines} in @ref{Text Lines}.
1074 @defun window-end &optional window update
1075 This function returns the position of the end of the display in window
1076 @var{window}. If @var{window} is @code{nil}, the selected window is
1079 Simply changing the buffer text or moving point does not update the
1080 value that @code{window-end} returns. The value is updated only when
1081 Emacs redisplays and redisplay completes without being preempted.
1083 If the last redisplay of @var{window} was preempted, and did not finish,
1084 Emacs does not know the position of the end of display in that window.
1085 In that case, this function returns @code{nil}.
1087 If you @var{update} is non-@code{nil}, @code{window-end} always returns
1088 an up-to-date value for where the window ends. If the saved value is
1089 valid, @code{window-end} returns that; otherwise it computes the correct
1090 value by scanning the buffer text.
1093 @defun set-window-start window position &optional noforce
1094 This function sets the display-start position of @var{window} to
1095 @var{position} in @var{window}'s buffer. It returns @var{position}.
1097 The display routines insist that the position of point be visible when a
1098 buffer is displayed. Normally, they change the display-start position
1099 (that is, scroll the window) whenever necessary to make point visible.
1100 However, if you specify the start position with this function using
1101 @code{nil} for @var{noforce}, it means you want display to start at
1102 @var{position} even if that would put the location of point off the
1103 screen. If this does place point off screen, the display routines move
1104 point to the left margin on the middle line in the window.
1106 For example, if point @w{is 1} and you set the start of the window @w{to
1107 2}, then point would be ``above'' the top of the window. The display
1108 routines will automatically move point if it is still 1 when redisplay
1109 occurs. Here is an example:
1113 ;; @r{Here is what @samp{foo} looks like before executing}
1114 ;; @r{the @code{set-window-start} expression.}
1118 ---------- Buffer: foo ----------
1119 @point{}This is the contents of buffer foo.
1125 ---------- Buffer: foo ----------
1131 (1+ (window-start)))
1136 ;; @r{Here is what @samp{foo} looks like after executing}
1137 ;; @r{the @code{set-window-start} expression.}
1138 ---------- Buffer: foo ----------
1139 his is the contents of buffer foo.
1145 ---------- Buffer: foo ----------
1149 If @var{noforce} is non-@code{nil}, and @var{position} would place point
1150 off screen at the next redisplay, then redisplay computes a new window-start
1151 position that works well with point, and thus @var{position} is not used.
1154 @defun pos-visible-in-window-p &optional position window
1155 This function returns @code{t} if @var{position} is within the range
1156 of text currently visible on the screen in @var{window}. It returns
1157 @code{nil} if @var{position} is scrolled vertically out of view. The
1158 argument @var{position} defaults to the current position of point;
1159 @var{window}, to the selected window. Here is an example:
1163 (or (pos-visible-in-window-p
1164 (point) (selected-window))
1169 The @code{pos-visible-in-window-p} function considers only vertical
1170 scrolling. If @var{position} is out of view only because @var{window}
1171 has been scrolled horizontally, @code{pos-visible-in-window-p} returns
1172 @code{t}. @xref{Horizontal Scrolling}.
1175 @node Vertical Scrolling
1176 @section Vertical Scrolling
1177 @cindex vertical scrolling
1178 @cindex scrolling vertically
1180 Vertical scrolling means moving the text up or down in a window. It
1181 works by changing the value of the window's display-start location. It
1182 may also change the value of @code{window-point} to keep it on the
1185 In the commands @code{scroll-up} and @code{scroll-down}, the directions
1186 ``up'' and ``down'' refer to the motion of the text in the buffer at which
1187 you are looking through the window. Imagine that the text is
1188 written on a long roll of paper and that the scrolling commands move the
1189 paper up and down. Thus, if you are looking at text in the middle of a
1190 buffer and repeatedly call @code{scroll-down}, you will eventually see
1191 the beginning of the buffer.
1193 Some people have urged that the opposite convention be used: they
1194 imagine that the window moves over text that remains in place. Then
1195 ``down'' commands would take you to the end of the buffer. This view is
1196 more consistent with the actual relationship between windows and the
1197 text in the buffer, but it is less like what the user sees. The
1198 position of a window on the terminal does not move, and short scrolling
1199 commands clearly move the text up or down on the screen. We have chosen
1200 names that fit the user's point of view.
1202 The scrolling functions (aside from @code{scroll-other-window}) have
1203 unpredictable results if the current buffer is different from the buffer
1204 that is displayed in the selected window. @xref{Current Buffer}.
1206 @deffn Command scroll-up &optional count
1207 This function scrolls the text in the selected window upward
1208 @var{count} lines. If @var{count} is negative, scrolling is actually
1211 If @var{count} is @code{nil} (or omitted), then the length of scroll
1212 is @code{next-screen-context-lines} lines less than the usable height of
1213 the window (not counting its mode line).
1215 @code{scroll-up} returns @code{nil}.
1218 @deffn Command scroll-down &optional count
1219 This function scrolls the text in the selected window downward
1220 @var{count} lines. If @var{count} is negative, scrolling is actually
1223 If @var{count} is omitted or @code{nil}, then the length of the scroll
1224 is @code{next-screen-context-lines} lines less than the usable height of
1225 the window (not counting its mode line).
1227 @code{scroll-down} returns @code{nil}.
1230 @deffn Command scroll-other-window &optional count
1231 This function scrolls the text in another window upward @var{count}
1232 lines. Negative values of @var{count}, or @code{nil}, are handled
1233 as in @code{scroll-up}.
1235 You can specify a buffer to scroll with the variable
1236 @code{other-window-scroll-buffer}. When the selected window is the
1237 minibuffer, the next window is normally the one at the top left corner.
1238 You can specify a different window to scroll with the variable
1239 @code{minibuffer-scroll-window}. This variable has no effect when any
1240 other window is selected. @xref{Minibuffer Misc}.
1242 When the minibuffer is active, it is the next window if the selected
1243 window is the one at the bottom right corner. In this case,
1244 @code{scroll-other-window} attempts to scroll the minibuffer. If the
1245 minibuffer contains just one line, it has nowhere to scroll to, so the
1246 line reappears after the echo area momentarily displays the message
1247 ``Beginning of buffer''.
1251 @defvar other-window-scroll-buffer
1252 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
1253 which buffer to scroll.
1257 This variable controls how scrolling is done automatically when point
1258 moves off the screen. If the value is zero, then redisplay scrolls the
1259 text to center point vertically in the window. If the value is a
1260 positive integer @var{n}, then redisplay brings point back on screen by
1261 scrolling @var{n} lines in either direction, if possible; otherwise, it
1262 centers point. The default value is zero.
1265 @defopt next-screen-context-lines
1266 The value of this variable is the number of lines of continuity to
1267 retain when scrolling by full screens. For example, @code{scroll-up}
1268 with an argument of @code{nil} scrolls so that this many lines at the
1269 bottom of the window appear instead at the top. The default value is
1273 @deffn Command recenter &optional count
1274 @cindex centering point
1275 This function scrolls the selected window to put the text where point
1276 is located at a specified vertical position within the window.
1278 If @var{count} is a nonnegative number, it puts the line containing
1279 point @var{count} lines down from the top of the window. If @var{count}
1280 is a negative number, then it counts upward from the bottom of the
1281 window, so that @minus{}1 stands for the last usable line in the window.
1282 If @var{count} is a non-@code{nil} list, then it stands for the line in
1283 the middle of the window.
1285 If @var{count} is @code{nil}, @code{recenter} puts the line containing
1286 point in the middle of the window, then clears and redisplays the entire
1289 When @code{recenter} is called interactively, @var{count} is the raw
1290 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
1291 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
1292 @var{count} to 4, which positions the current line four lines from the
1295 With an argument of zero, @code{recenter} positions the current line at
1296 the top of the window. This action is so handy that some people make a
1297 separate key binding to do this. For example,
1301 (defun line-to-top-of-window ()
1302 "Scroll current line to top of window.
1303 Replaces three keystroke sequence C-u 0 C-l."
1307 (global-set-key [kp-multiply] 'line-to-top-of-window)
1312 @node Horizontal Scrolling
1313 @section Horizontal Scrolling
1314 @cindex horizontal scrolling
1316 Because we read English from left to right in the ``inner loop'', and
1317 from top to bottom in the ``outer loop'', horizontal scrolling is not
1318 like vertical scrolling. Vertical scrolling involves selection of a
1319 contiguous portion of text to display, but horizontal scrolling causes
1320 part of each line to go off screen. The amount of horizontal scrolling
1321 is therefore specified as a number of columns rather than as a position
1322 in the buffer. It has nothing to do with the display-start position
1323 returned by @code{window-start}.
1325 Usually, no horizontal scrolling is in effect; then the leftmost
1326 column is at the left edge of the window. In this state, scrolling to
1327 the right is meaningless, since there is no data to the left of the
1328 screen to be revealed by it; so this is not allowed. Scrolling to the
1329 left is allowed; it scrolls the first columns of text off the edge of
1330 the window and can reveal additional columns on the right that were
1331 truncated before. Once a window has a nonzero amount of leftward
1332 horizontal scrolling, you can scroll it back to the right, but only so
1333 far as to reduce the net horizontal scroll to zero. There is no limit
1334 to how far left you can scroll, but eventually all the text will
1335 disappear off the left edge.
1337 @deffn Command scroll-left count
1338 This function scrolls the selected window @var{count} columns to the
1339 left (or to the right if @var{count} is negative). The return value is
1340 the total amount of leftward horizontal scrolling in effect after the
1341 change---just like the value returned by @code{window-hscroll} (below).
1344 @deffn Command scroll-right count
1345 This function scrolls the selected window @var{count} columns to the
1346 right (or to the left if @var{count} is negative). The return value is
1347 the total amount of leftward horizontal scrolling in effect after the
1348 change---just like the value returned by @code{window-hscroll} (below).
1350 Once you scroll a window as far right as it can go, back to its normal
1351 position where the total leftward scrolling is zero, attempts to scroll
1352 any farther right have no effect.
1355 @defun window-hscroll &optional window
1356 This function returns the total leftward horizontal scrolling of
1357 @var{window}---the number of columns by which the text in @var{window}
1358 is scrolled left past the left margin.
1360 The value is never negative. It is zero when no horizontal scrolling
1361 has been done in @var{window} (which is usually the case).
1363 If @var{window} is @code{nil}, the selected window is used.
1381 @defun set-window-hscroll window columns
1382 This function sets the number of columns from the left margin that
1383 @var{window} is scrolled from the value of @var{columns}. The argument
1384 @var{columns} should be zero or positive; if not, it is taken as zero.
1386 The value returned is @var{columns}.
1390 (set-window-hscroll (selected-window) 10)
1396 Here is how you can determine whether a given position @var{position}
1397 is off the screen due to horizontal scrolling:
1401 (defun hscroll-on-screen (window position)
1403 (goto-char position)
1405 (>= (- (current-column) (window-hscroll window)) 0)
1406 (< (- (current-column) (window-hscroll window))
1407 (window-width window)))))
1411 @node Size of Window
1412 @section The Size of a Window
1414 @cindex size of window
1416 An Emacs window is rectangular, and its size information consists of
1417 the height (the number of lines) and the width (the number of character
1418 positions in each line). The mode line is included in the height. But
1419 the width does not count the scroll bar or the column of @samp{|}
1420 characters that separates side-by-side windows.
1422 The following three functions return size information about a window:
1424 @defun window-height &optional window
1425 This function returns the number of lines in @var{window}, including its
1426 mode line. If @var{window} fills its entire frame, this is typically
1427 one less than the value of @code{frame-height} on that frame (since the
1428 last line is always reserved for the minibuffer).
1430 If @var{window} is @code{nil}, the function uses the selected window.
1438 (split-window-vertically)
1439 @result{} #<window 4 on windows.texi>
1448 @defun window-width &optional window
1449 This function returns the number of columns in @var{window}. If
1450 @var{window} fills its entire frame, this is the same as the value of
1451 @code{frame-width} on that frame. The width does not include the
1452 window's scroll bar or the column of @samp{|} characters that separates
1453 side-by-side windows.
1455 If @var{window} is @code{nil}, the function uses the selected window.
1465 @defun window-edges &optional window
1466 This function returns a list of the edge coordinates of @var{window}.
1467 If @var{window} is @code{nil}, the selected window is used.
1469 The order of the list is @code{(@var{left} @var{top} @var{right}
1470 @var{bottom})}, all elements relative to 0, 0 at the top left corner of
1471 the frame. The element @var{right} of the value is one more than the
1472 rightmost column used by @var{window}, and @var{bottom} is one more than
1473 the bottommost row used by @var{window} and its mode-line.
1475 When you have side-by-side windows, the right edge value for a window
1476 with a neighbor on the right includes the width of the separator between
1477 the window and that neighbor. This separator may be a column of
1478 @samp{|} characters or it may be a scroll bar. Since the width of the
1479 window does not include this separator, the width does not equal the
1480 difference between the right and left edges in this case.
1482 Here is the result obtained on a typical 24-line terminal with just one
1487 (window-edges (selected-window))
1488 @result{} (0 0 80 23)
1493 The bottom edge is at line 23 because the last line is the echo area.
1495 If @var{window} is at the upper left corner of its frame, then
1496 @var{bottom} is the same as the value of @code{(window-height)},
1497 @var{right} is almost the same as the value of
1498 @code{(window-width)}@footnote{They are not exactly equal because
1499 @var{right} includes the vertical separator line or scroll bar, while
1500 @code{(window-width)} does not.}, and @var{top} and @var{left} are zero.
1501 For example, the edges of the following window are @w{@samp{0 0 5 8}}.
1502 Assuming that the frame has more than 8 columns, the last column of the
1503 window (column 7) holds a border rather than text. The last row (row 4)
1504 holds the mode line, shown here with @samp{xxxxxxxxx}.
1520 When there are side-by-side windows, any window not at the right edge of
1521 its frame has a separator in its last column or columns. The separator
1522 counts as one or two columns in the width of the window. A window never
1523 includes a separator on its left, since that belongs to the window to
1526 In the following example, let's suppose that the frame is 7
1527 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
1528 and the edges of the right window are @w{@samp{4 0 7 3}}.
1542 @node Resizing Windows
1543 @section Changing the Size of a Window
1544 @cindex window resizing
1545 @cindex changing window size
1546 @cindex window size, changing
1548 The window size functions fall into two classes: high-level commands
1549 that change the size of windows and low-level functions that access
1550 window size. Emacs does not permit overlapping windows or gaps between
1551 windows, so resizing one window affects other windows.
1553 @deffn Command enlarge-window size &optional horizontal
1554 This function makes the selected window @var{size} lines taller,
1555 stealing lines from neighboring windows. It takes the lines from one
1556 window at a time until that window is used up, then takes from another.
1557 If a window from which lines are stolen shrinks below
1558 @code{window-min-height} lines, that window disappears.
1560 If @var{horizontal} is non-@code{nil}, this function makes
1561 @var{window} wider by @var{size} columns, stealing columns instead of
1562 lines. If a window from which columns are stolen shrinks below
1563 @code{window-min-width} columns, that window disappears.
1565 If the requested size would exceed that of the window's frame, then the
1566 function makes the window occupy the entire height (or width) of the
1569 If @var{size} is negative, this function shrinks the window by
1570 @minus{}@var{size} lines or columns. If that makes the window smaller
1571 than the minimum size (@code{window-min-height} and
1572 @code{window-min-width}), @code{enlarge-window} deletes the window.
1574 @code{enlarge-window} returns @code{nil}.
1577 @deffn Command enlarge-window-horizontally columns
1578 This function makes the selected window @var{columns} wider.
1579 It could be defined as follows:
1583 (defun enlarge-window-horizontally (columns)
1584 (enlarge-window columns t))
1589 @deffn Command shrink-window size &optional horizontal
1590 This function is like @code{enlarge-window} but negates the argument
1591 @var{size}, making the selected window smaller by giving lines (or
1592 columns) to the other windows. If the window shrinks below
1593 @code{window-min-height} or @code{window-min-width}, then it disappears.
1595 If @var{size} is negative, the window is enlarged by @minus{}@var{size}
1599 @deffn Command shrink-window-horizontally columns
1600 This function makes the selected window @var{columns} narrower.
1601 It could be defined as follows:
1605 (defun shrink-window-horizontally (columns)
1606 (shrink-window columns t))
1611 @cindex minimum window size
1612 The following two variables constrain the window-size-changing
1613 functions to a minimum height and width.
1615 @defopt window-min-height
1616 The value of this variable determines how short a window may become
1617 before it is automatically deleted. Making a window smaller than
1618 @code{window-min-height} automatically deletes it, and no window may be
1619 created shorter than this. The absolute minimum height is two (allowing
1620 one line for the mode line, and one line for the buffer display).
1621 Actions that change window sizes reset this variable to two if it is
1622 less than two. The default value is 4.
1625 @defopt window-min-width
1626 The value of this variable determines how narrow a window may become
1627 before it automatically deleted. Making a window smaller than
1628 @code{window-min-width} automatically deletes it, and no window may be
1629 created narrower than this. The absolute minimum width is one; any
1630 value below that is ignored. The default value is 10.
1633 @node Coordinates and Windows
1634 @section Coordinates and Windows
1636 This section describes how to relate screen coordinates to windows.
1638 @defun window-at x y &optional frame
1639 This function returns the window containing the specified cursor
1640 position in the frame @var{frame}. The coordinates @var{x} and @var{y}
1641 are measured in characters and count from the top left corner of the
1642 frame. If they are out of range, @code{window-at} returns @code{nil}.
1644 If you omit @var{frame}, the selected frame is used.
1647 @defun coordinates-in-window-p coordinates window
1648 This function checks whether a particular frame position falls within
1649 the window @var{window}.
1651 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
1652 . @var{y})}. The coordinates @var{x} and @var{y} are measured in
1653 characters, and count from the top left corner of the screen or frame.
1655 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
1656 if the coordinates are inside @var{window}. The value also indicates
1657 what part of the window the position is in, as follows:
1660 @item (@var{relx} . @var{rely})
1661 The coordinates are inside @var{window}. The numbers @var{relx} and
1662 @var{rely} are the equivalent window-relative coordinates for the
1663 specified position, counting from 0 at the top left corner of the
1667 The coordinates are in the mode line of @var{window}.
1669 @item vertical-split
1670 The coordinates are in the vertical line between @var{window} and its
1671 neighbor to the right. This value occurs only if the window doesn't
1672 have a scroll bar; positions in a scroll bar are considered outside the
1676 The coordinates are not in any part of @var{window}.
1679 The function @code{coordinates-in-window-p} does not require a frame as
1680 argument because it always uses the frame that @var{window} is on.
1683 @node Window Configurations
1684 @section Window Configurations
1685 @cindex window configurations
1686 @cindex saving window information
1688 A @dfn{window configuration} records the entire layout of one
1689 frame---all windows, their sizes, which buffers they contain, what part
1690 of each buffer is displayed, and the values of point and the mark. You
1691 can bring back an entire previous layout by restoring a window
1692 configuration previously saved.
1694 If you want to record all frames instead of just one, use a frame
1695 configuration instead of a window configuration. @xref{Frame
1698 @defun current-window-configuration
1699 This function returns a new object representing the selected frame's
1700 current window configuration, including the number of windows, their
1701 sizes and current buffers, which window is the selected window, and for
1702 each window the displayed buffer, the display-start position, and the
1703 positions of point and the mark. It also includes the values of
1704 @code{window-min-height}, @code{window-min-width} and
1705 @code{minibuffer-scroll-window}. An exception is made for point in the
1706 current buffer, whose value is not saved.
1709 @defun set-window-configuration configuration
1710 This function restores the configuration of windows and buffers as
1711 specified by @var{configuration}. The argument @var{configuration} must
1712 be a value that was previously returned by
1713 @code{current-window-configuration}. This configuration is restored in
1714 the frame from which @var{configuration} was made, whether that frame is
1715 selected or not. This always counts as a window size change and
1716 triggers execution of the @code{window-size-change-functions}
1717 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
1718 know how to tell whether the new configuration actually differs from the
1721 If the frame which @var{configuration} was saved from is dead, all this
1722 function does is restore the three variables @code{window-min-height},
1723 @code{window-min-width} and @code{minibuffer-scroll-window}.
1725 Here is a way of using this function to get the same effect
1726 as @code{save-window-excursion}:
1730 (let ((config (current-window-configuration)))
1732 (progn (split-window-vertically nil)
1734 (set-window-configuration config)))
1739 @defspec save-window-excursion forms@dots{}
1740 This special form records the window configuration, executes @var{forms}
1741 in sequence, then restores the earlier window configuration. The window
1742 configuration includes the value of point and the portion of the buffer
1743 that is visible. It also includes the choice of selected window.
1744 However, it does not include the value of point in the current buffer;
1745 use @code{save-excursion} also, if you wish to preserve that.
1747 Don't use this construct when @code{save-selected-window} is all you need.
1749 Exit from @code{save-window-excursion} always triggers execution of the
1750 @code{window-size-change-functions}. (It doesn't know how to tell
1751 whether the restored configuration actually differs from the one in
1752 effect at the end of the @var{forms}.)
1754 The return value is the value of the final form in @var{forms}.
1760 @result{} #<window 25 on control.texi>
1763 (setq w (selected-window))
1764 @result{} #<window 19 on control.texi>
1767 (save-window-excursion
1768 (delete-other-windows w)
1769 (switch-to-buffer "foo")
1771 @result{} do-something
1772 ;; @r{The screen is now split again.}
1777 @defun window-configuration-p object
1778 This function returns @code{t} if @var{object} is a window configuration.
1781 @defun compare-window-configurations config1 config2
1782 This function compares two window configurations as regards the
1783 structure of windows, but ignores the values of point and mark and the
1784 saved scrolling positions---it can return @code{t} even if those
1787 The function @code{equal} can also compare two window configurations; it
1788 regards configurations as unequal if they differ in any respect, even a
1789 saved point or mark.
1792 Primitives to look inside of window configurations would make sense,
1793 but none are implemented. It is not clear they are useful enough to be
1797 @section Hooks for Window Scrolling and Changes
1799 This section describes how a Lisp program can take action whenever a
1800 window displays a different part of its buffer or a different buffer.
1801 There are three actions that can change this: scrolling the window,
1802 switching buffers in the window, and changing the size of the window.
1803 The first two actions run @code{window-scroll-functions}; the last runs
1804 @code{window-size-change-functions}. The paradigmatic use of these
1805 hooks is in the implementation of Lazy Lock mode; see @ref{Support
1806 Modes, Lazy Lock, Font Lock Support Modes, emacs, The GNU Emacs Manual}.
1808 @defvar window-scroll-functions
1809 This variable holds a list of functions that Emacs should call before
1810 redisplaying a window with scrolling. It is not a normal hook, because
1811 each function is called with two arguments: the window, and its new
1812 display-start position.
1814 Displaying a different buffer in the window also runs these functions.
1816 These functions cannot expect @code{window-end} (@pxref{Window Start})
1817 to return a meaningful value, because that value is updated only by
1818 redisplaying the buffer. So if one of these functions needs to know the
1819 last character that will fit in the window with its current
1820 display-start position, it has to find that character using
1821 @code{vertical-motion} (@pxref{Screen Lines}).
1824 @defvar window-size-change-functions
1825 This variable holds a list of functions to be called if the size of any
1826 window changes for any reason. The functions are called just once per
1827 redisplay, and just once for each frame on which size changes have
1830 Each function receives the frame as its sole argument. There is no
1831 direct way to find out which windows on that frame have changed size, or
1832 precisely how. However, if a size-change function records, at each
1833 call, the existing windows and their sizes, it can also compare the
1834 present sizes and the previous sizes.
1836 Creating or deleting windows counts as a size change, and therefore
1837 causes these functions to be called. Changing the frame size also
1838 counts, because it changes the sizes of the existing windows.
1840 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
1841 Configurations}) in these functions, because that always counts as a
1842 size change, and it would cause these functions to be called over and
1843 over. In most cases, @code{save-selected-window} (@pxref{Selecting
1844 Windows}) is what you need here.
1847 @defvar redisplay-end-trigger-functions
1848 @tindex redisplay-end-trigger-functions
1849 This abnormal hook is run whenever redisplay in window uses text that
1850 extends past a specified end trigger position. You set the end trigger
1851 position with the function @code{set-window-redisplay-end-trigger}. The
1852 functions are called with two arguments: the window, and the end trigger
1853 position. Storing @code{nil} for the end trigger position turns off the
1854 feature, and the trigger value is automatically reset to @code{nil} just
1855 after the hook is run.
1858 @defun set-window-redisplay-end-trigger window position
1859 @tindex set-window-redisplay-end-trigger
1860 This function sets @var{window}'s end trigger position at
1864 @defun window-redisplay-end-trigger window
1865 @tindex window-redisplay-end-trigger
1866 This function returns @var{window}'s current end trigger position.
1869 @defvar window-configuration-change-hook
1870 @tindex window-configuration-change-hook
1871 A normal hook that is run every time you change the window configuration
1872 of an existing frame. This includes splitting or deleting windows,
1873 changing the sizes of windows, or displaying a different buffer in a
1874 window. The frame whose window configuration has changed is the
1875 selected frame when this hook runs.