2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2011
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 the functions and variables related to Emacs
11 windows. @xref{Frames}, for how windows are assigned an area of screen
12 available for Emacs to use. @xref{Display}, for information on how text
13 is displayed in windows.
16 * Basic Windows:: Basic information on using windows.
17 * Windows and Frames:: Relating windows to the frame they appear on.
18 * Window Sizes:: Accessing a window's size.
19 * Resizing Windows:: Changing the sizes of windows.
20 * Splitting Windows:: Splitting one window into two windows.
21 * Deleting Windows:: Deleting a window gives its space to other windows.
22 * Selecting Windows:: The selected window is the one that you edit in.
23 * Cyclic Window Ordering:: Moving around the existing windows.
24 * Buffers and Windows:: Each window displays the contents of a buffer.
25 * Switching Buffers:: Higher-level functions for switching to a buffer.
26 * Choosing Window:: How to choose a window for displaying a buffer.
27 * Window History:: Each window remembers the buffers displayed in it.
28 * Dedicated Windows:: How to avoid displaying another buffer in
30 * Window Point:: Each window has its own location of point.
31 * Window Start and End:: Buffer positions indicating which text is
32 on-screen in a window.
33 * Textual Scrolling:: Moving text up and down through the window.
34 * Vertical Scrolling:: Moving the contents up and down on the window.
35 * Horizontal Scrolling:: Moving the contents sideways on the window.
36 * Coordinates and Windows:: Converting coordinates to windows.
37 * Window Configurations:: Saving and restoring the state of the screen.
38 * Window Parameters:: Associating additional information with windows.
39 * Window Hooks:: Hooks for scrolling, window size changes,
40 redisplay going past a certain point,
41 or window configuration changes.
46 @section Basic Concepts of Emacs Windows
49 A @dfn{window} in Emacs is the physical area of the screen in which a
50 buffer is displayed, see @ref{Buffers}. The term is also used to refer
51 to a Lisp object that represents that screen area in Emacs Lisp. It
52 should be clear from the context which is meant.
54 @cindex multiple windows
55 Emacs groups windows into frames; see @ref{Frames}. Each frame always
56 contains at least one window, but you can subdivide it into multiple,
57 non-overlapping Emacs windows. Users create multiple windows so they
58 can look at several buffers at once. Lisp libraries use multiple
59 windows for a variety of reasons, but most often to display related
60 information. In Rmail, for example, you can move through a summary
61 buffer in one window while the other window shows messages one at a time
64 @cindex terminal screen
65 @cindex screen of terminal
66 The meaning of ``window'' in Emacs is similar to what it means in the
67 context of general-purpose window systems such as X, but not identical.
68 The X Window System places X windows on the screen; Emacs uses one or
69 more X windows as frames, and subdivides them into Emacs windows. When
70 you use Emacs on a character-only terminal, Emacs treats the whole
71 terminal screen as one frame.
74 Most window systems support arbitrarily located overlapping windows.
75 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
76 together they fill the whole screen or frame. Because of the way in
77 which Emacs creates new windows (@pxref{Splitting Windows}) and resizes
78 them (@pxref{Resizing Windows}), not all conceivable tilings of windows
79 on an Emacs frame are actually possible.
81 For practical purposes, a window exists only while it is displayed in
82 a frame. Once removed from the frame, the window is effectively deleted
83 and should not be used, even though the Lisp object representing it
84 might be still referenced from other Lisp objects; see @ref{Deleting
85 Windows}. Restoring a saved window configuration is the only way for a
86 window no longer on the screen to come back to life; see @ref{Window
90 This function returns @code{t} if @var{object} is a window, @code{nil}
91 otherwise. It can return @code{t} if @var{object} denotes a window that
96 @cindex internal windows
97 For historical reasons a window is considered @dfn{live} if and only
98 if it currently displays a buffer; see @ref{Buffers and Windows}. In
99 order to show multiple windows within one and the same frame, Emacs
100 organizes them in form of a tree called window tree; see @ref{Windows
101 and Frames}. The internal nodes of a window tree are called internal
102 windows and are not considered live. The leaf nodes of a window tree
103 constitute the windows displaying buffers and only they will be called
106 @defun window-live-p object
107 This function returns @code{t} if @var{object} is a live window and
108 @code{nil} otherwise. A live window is a window that displays a buffer.
111 @defun window-any-p object
112 This function returns @code{t} if @var{object} denotes a live or an
113 internal window and @code{nil} otherwise. In particular, this function
114 returns @code{nil} if @var{object} is a window that has been
118 @cindex selected window
119 In each frame, at any time, one and only one window is designated as
120 @dfn{selected within the frame}. Also, at any time, one frame is the
121 selected frame (@pxref{Input Focus}). The window selected within the
122 selected frame is the @dfn{selected window}.
124 The selected window is always a live window. Its buffer is usually
125 the current buffer (except when @code{set-buffer} has been used); see
126 @ref{Current Buffer}.
128 @defun selected-window
129 This function returns the selected window. This is the window in which
130 the cursor for selected windows (@pxref{Cursor Parameters}) appears and
131 to which many commands apply.
134 The window handling functions can be roughly grouped into functions
135 operating on live windows only and functions that accept any window as
136 argument. Many of these functions accept as argument the value
137 @code{nil} to specify the selected window. The two functions below can
138 be used to ``normalize'' arguments specifying windows in a uniform
141 @defun window-normalize-any-window window
142 This function returns the normalized value for @var{window} which can be
143 any window that has not been deleted. More precisely, if @var{window}
144 is @code{nil}, it returns the selected window. If @var{window} denotes
145 a live or internal window, it returns that window. Otherwise, this
146 function signals an error.
149 @defun window-normalize-live-window window
150 This functions returns the normalized value for a live window
151 @var{window}. More precisely, if @var{window} is @code{nil}, it returns
152 the selected window. If @var{window} is a live window, it returns that
153 window. Otherwise, this function signals an error.
157 @node Windows and Frames
158 @section Windows and Frames
160 Each window is part of one and only one frame (@pxref{Frames}); you can
161 get that frame with the function described next.
163 @defun window-frame window
164 This function returns the frame that @var{window} is on. The argument
165 @var{window} can be any window and defaults to the selected one.
168 The following function returns a list of all live windows on a specific
171 @defun window-list &optional frame minibuf window
172 This function returns a list of @var{frame}'s live windows, starting
173 with @var{window}. The optional argument @var{frame} has to denote a
174 live frame and defaults to the selected frame. The optional argument
175 @var{window} has to denote a live window on the frame specified by
176 @var{frame} and defaults to the selected one.
178 The argument @var{minibuf} specifies if the minibuffer window shall be
179 included in the return value. If @var{minibuf} is @code{t}, the result
180 always includes the minibuffer window. If @var{minibuf} is @code{nil}
181 or omitted, that includes the minibuffer window only if it is active.
182 If @var{minibuf} is neither @code{nil} nor @code{t}, the result never
183 includes the minibuffer window.
187 Windows within one and the same frame are organized in form of a tree
188 called @dfn{window tree}. The leaf nodes of a window tree constitute
189 the windows visible to the user. These are the windows associated with
190 buffers and are usually called live windows. The internal nodes of a
191 window tree are needed for finding, traversing and displaying the live
194 A minibuffer window (@pxref{Minibuffer Windows}) is not considered
195 part of its frame's window tree unless the frame is a minibuffer-only
196 frame. Most functions covered in this section accept, however, the
197 minibuffer window as argument. Also, the minibuffer window is listed by
198 the function @code{window-tree} described at the end of this section.
200 A window tree is rooted at the root window of its frame.
202 @defun frame-root-window &optional frame-or-window
203 This function returns the root window of @var{frame-or-window}. The
204 argument @var{frame-or-window} has to denote either a window or a frame
205 and defaults to the selected frame. If @var{frame-or-window} denotes a
206 window, the return value is the root window of that window's frame.
207 This function always returns a window; a live window if the frame
208 specified by @var{frame-or-window} contains no other live windows and an
209 internal window otherwise.
213 All other windows of a frame with the exception of the minibuffer window
214 are subwindows of the frame's root window. A window is considered a
215 @dfn{subwindow} of another window if it occupies a part of that other
216 window's screen area.
218 The functions described next allow to access the members of a window
219 tree and take an arbitrary window as argument.
221 @cindex parent window
222 @defun window-parent &optional window
223 Return @var{window}'s parent in the window tree. The optional argument
224 @var{window} can denote an arbitrary window and defaults to the selected
225 one. The return value is @code{nil} if @var{window} is a minibuffer
226 window or the root window of its frame and an internal window otherwise.
230 Parent windows do not appear on the screen. The screen area of a
231 parent window is the rectangular part of the window's frame occupied by
232 the window's @dfn{child windows}, that is, the set of windows having
233 that window as their parent. Each parent window has at least two child
234 windows, so there are no ``Matryoshka'' windows. Minibuffer windows do
235 not have child windows.
237 @cindex window combination
238 @cindex vertical combination
239 @cindex horizontal combination
240 The children of any parent window form either a vertical or a horizontal
241 combination of windows. A @dfn{vertical combination} is a set of
242 windows arranged one above each other. A @dfn{horizontal combination}
243 is a set of windows arranged side by side. Consider the frame shown
244 below (for simplicity we assume that the frame does not contain a
249 ______________________________________
250 | ______ ____________________________ |
251 || || __________________________ ||
252 || ||| ___________ ___________ |||
255 || ||||_____W6____||_____W7____||||
256 || |||____________W4____________|||
257 || || __________________________ ||
259 || |||____________W5____________|||
260 ||__W2__||_____________W3_____________ |
261 |__________________W1__________________|
266 The root window of the frame is @code{W1}---a horizontal combination of
267 the live window @code{W2} and the internal window @code{W3}. Hence
268 @code{(window-parent W1)} is @code{nil} while @code{(window-parent W2)}
269 and @code{(window-parent W3)} are both @code{W1}.
271 The internal window @code{W3} is a vertical combination of @code{W4}
272 and the live window @code{W5}. The internal window @code{W4} is a
273 horizontal combination of the live windows @code{W6} and @code{W7}. The
274 windows you can actually see on the screen are @code{W2}, @code{W5},
275 @code{W6} and @code{W7}.
277 For any parent window, the first child window can be retrieved by the
278 functions given next.
280 @defun window-top-child &optional window
281 This function returns @var{window}'s first vertical child window. The
282 optional argument @var{window} can be an arbitrary window and defaults
283 to the selected one. The return value is @code{nil} if @var{window} is
284 a live window or its children form a horizontal combination. In the
285 example above @code{(window-top-child W3)} is @code{W4} while
286 @code{(window-top-child W4)} is @code{nil}.
289 @defun window-left-child &optional window
290 This function returns @var{window}'s first horizontal child window. The
291 optional argument @var{window} can be an arbitrary window and defaults
292 to the selected one. The return value is @code{nil} if @var{window} is
293 a live window or its children form a vertical combination. In the
294 example above @code{(window-left-child W4)} is @code{W6} while
295 @code{(window-top-child W3)} is @code{nil}.
298 @defun window-child window
299 This function return @var{window}'s first child window. The return
300 value is @code{nil} if @var{window} is a live window. In the example
301 above @code{(window-child W3)} is @code{W4} while @code{(window-child
305 The following function is useful to determine whether a window is part
306 of a vertical or horizontal combination.
308 @defun window-iso-combined-p &optional window horizontal
309 This function returns non-@code{nil} if and only if @var{window} is
310 vertically combined. The argument @var{window} can specify any window
311 and defaults to the selected one. The actual return value is the first
312 vertical child of window.
314 If the optional argument @var{horizontal} is non-@code{nil}, this means
315 to return non-@code{nil} if and only if @var{window} is horizontally
316 combined. In this case, the return value is the first horizontal child
320 @cindex sibling window
321 For any window that is part of a combination, the other windows in that
322 combination are called the window's @dfn{siblings}. The only windows
323 that do not have siblings are root windows of frames and minibuffer
324 windows. A window's siblings can be retrieved with the following two
327 @defun window-next-sibling &optional window
328 This function returns @var{window}'s next sibling. The optional
329 argument @var{window} can be an arbitrary window and defaults to the
330 selected window. It returns @code{nil} if @var{window} is the last
331 child of its parent. In our example @code{(window-next-sibling W2)} is
332 @code{W3} while @code{(window-next-sibling W3)} is @code{nil}.
335 @defun window-prev-sibling &optional window
336 This function returns @var{window}'s previous sibling. The optional
337 argument @var{window} can be an arbitrary window and defaults to the
338 selected window. It returns @code{nil} if @var{window} is the first
339 child of its parent. In our example @code{(window-prev-sibling W3)} is
340 @code{W2} and @code{(window-prev-sibling W2)} is @code{nil}.
343 The functions @code{window-next-sibling} and @code{window-prev-sibling}
344 should not be confused with the functions @code{next-window} and
345 @code{previous-window} which respectively return the next and previous
346 window in the cyclic ordering of windows, see @ref{Cyclic Window
349 In order to find the first live window on a frame, the following
350 function can be used.
352 @defun frame-first-window &optional frame-or-window
353 This function returns the live window at the upper left corner of the
354 frame specified by @var{frame-or-window}. The argument
355 @var{frame-or-window} must denote a window or a live frame and defaults
356 to the selected frame. If @var{frame-or-window} specifies a window,
357 this function returns the first window on that window's frame. Under
358 the assumption that the frame from our canonical example is selected
359 @code{(frame-first-window)} returns @code{W2}.
362 You can get the window tree of a frame with the following function.
365 @defun window-tree &optional frame
366 This function returns the window tree for frame @var{frame}. The
367 optional argument @var{frame} must be a live frame and defaults to the
370 The return value is a list of the form @code{(@var{root} @var{mini})},
371 where @var{root} represents the window tree of the frame's
372 root window, and @var{mini} is the frame's minibuffer window.
374 If the root window is live, @var{root} specifies the root window and
375 nothing else. Otherwise, @var{root} is a list @code{(@var{dir}
376 @var{edges} @var{w1} @var{w2} ...)} where @var{dir} is @code{nil} for a
377 horizontal combination, and @code{t} for a vertical combination,
378 @var{edges} gives the size and position of the combination, and the
379 remaining elements are the child windows. Each child window may again
380 be a live window or a list representing a window combination, and so on.
381 The @var{edges} element is a list @code{(@var{left}@var{ top}@var{
382 right}@var{ bottom})} similar to the value returned by
383 @code{window-edges}, see @ref{Coordinates and Windows}.
388 @section Window Sizes
390 @cindex size of window
392 Emacs windows are rectangular. The structure of a live window can be
393 roughly sketched as follows:
397 _________________________________________
398 ^ |______________ Header Line_______________|
399 | |LS|LF|LM| |RM|RF|RS| ^
401 Window | | | | Text Area | | | | Window
402 Total | | | | (Window Body) | | | | Body
403 Height | | | | | | | | Height
404 | | | | |<- Window Body Width ->| | | | |
405 | |__|__|__|_______________________|__|__|__| v
406 v |_______________ Mode Line _______________|
408 <----------- Window Total Width -------->
414 @cindex body of a window
415 The text area constitutes the body of the window. In its most simple
416 form, a window consists of its body alone. LS and RS stand for the left
417 and right scroll bar (@pxref{Scroll Bars}) respectively. Only one of
418 them can be present at any time. LF and RF denote the left and right
419 fringe, see @ref{Fringes}. LM and RM, finally, stand for the left and
420 right display margin, see @ref{Display Margins}. The header line, if
421 present, is located above theses areas, the mode line below, see
422 @ref{Mode Line Format}.
424 @cindex window height
425 @cindex total window height
426 @cindex height of a window
427 @cindex total height of a window
428 The @dfn{total height of a window} is specified as the total number of
429 lines occupied by the window. Any mode or header line is included in a
430 window's total height. For an internal window, the total height is
431 calculated recursively from the total heights of its child windows.
434 @cindex total window width
435 @cindex width of a window
436 @cindex total width of a window
437 The @dfn{total width of a window} denotes the total number of columns of
438 the window. Any scroll bar and the column of @samp{|} characters that
439 separate the window from its right sibling are included in a window's
440 total width. On a window-system, fringes and display margins are
441 included in a window's total width too. For an internal window, the
442 total width is calculated recursively from the total widths of its child
445 @cindex total size of a window
446 @cindex total window size
447 The following function is the standard interface for getting the total
450 @defun window-total-size &optional window &optional horizontal
451 This function returns the total number of lines of @var{window}. The
452 argument @var{window} can denote any window and defaults to the selected
453 one. If @var{window} is live, the return value includes any header or
454 mode lines of @var{window}. If @var{window} is internal, the return
455 value is the sum of the total heights of @var{window}'s child windows
456 provided these are vertically combined and the height of @var{window}'s
457 first child if they are horizontally combined.
459 If the optional argument @var{horizontal} is non-@code{nil}, this
460 function returns the total number of columns of @var{window}. If
461 @var{window} is live, the return value includes any vertical divider
462 column or scroll bars of @var{window}. On a window-system, the return
463 value includes the space occupied by any margins and fringes of
464 @var{window} too. If @var{window} is internal, the return value is the
465 sum of the total widths of @var{window}'s child windows provided these
466 are horizontally combined and the width of @var{window}'s first child
470 Alternatively, the following two functions can be used to retrieve
471 either the total height or the total width of a window:
473 @defun window-total-height &optional window
474 This function returns the total number of lines of @var{window}.
475 @var{window} can be any window and defaults to the selected one. The
476 return value includes @var{window}'s mode line and header line, if any.
477 If @var{window} is internal the return value is the sum of heights of
478 @var{window}'s child windows for a vertical combination and the height
479 of @var{window}'s first child otherwise.
482 @defun window-total-width &optional window
483 This function returns the total number of columns of @var{window}.
484 @var{window} can be any window and defaults to the selected one. The
485 return value includes any vertical dividers or scrollbars of
486 @var{window}. On a window-system the return value also includes the
487 space occupied by any margins and fringes of @var{window}. If
488 @var{window} is internal, the return value is the sum of the widths of
489 @var{window}'s child windows for a horizontal combination and the width
490 of @var{window}'s first child otherwise.
493 The total height of any window is usually less than the height of the
494 window's frame, because the latter may also include the minibuffer
495 window. Depending on the toolkit in use, the frame height can also
496 include the menu bar and the tool bar (@pxref{Size and Position}).
497 Therefore, in general it is not straightforward to compare window and
498 frame heights. The following function is useful to determine whether
499 there are no other windows above or below a specified window.
501 @cindex full-height window
502 @defun window-full-height-p &optional window
503 This function returns non-@code{nil} if there is no other window above
504 or below @var{window} on the containing frame. More precisely, this
505 function returns @code{t} if and only if the total height of
506 @var{window} equals the total height of the root window (@pxref{Windows
507 and Frames}) of @var{window}'s frame. The @var{window} argument may
508 denote any window and defaults to the selected one.
511 @cindex full-width window
512 The following function can be used to determine whether there are no
513 other windows on the left or right of a specified window.
515 @defun window-full-width-p &optional window
516 This function returns non-@code{nil} if there are no other windows on
517 the left or right of @var{window}; @code{nil} otherwise. More
518 precisely, this function returns @code{t} if and only if the total width
519 of @var{window} equals the total width of the root window
520 (@pxref{Windows and Frames}) of @var{window}'s frame. The @var{window}
521 argument may denote any window and defaults to the selected one.
524 @cindex top line of window
525 @cindex left column of window
526 The windows of a frame are unambiguously characterized by the
527 combination of their top line and left column within that frame.
529 @defun window-top-line &optional window
530 This function returns the top line of @var{window}. The argument
531 @var{window} can denote any window and defaults to the selected one.
534 @defun window-left-column &optional window
535 This function returns the left column of @var{window}. The argument
536 @var{window} can denote any window and defaults to the selected one.
539 For a frame displaying one window only, that window's top line and left
540 column are both zero. When a frame displays a window @var{WB} below a
541 window @var{WA}, the top line of @var{WB} can be calculated by adding
542 the total height of @var{WA} to the top line of @var{WA}. When a frame
543 displays a window @var{WR} on the right of a window @var{WL}, the left
544 column of @var{WR} can be calculated by adding the total width of
545 @var{WL} to the left column of @var{WL}.
547 @cindex window body height
548 @cindex body height of a window
549 The @dfn{body height of a window} is specified as the total number of
550 lines occupied by the window's text area. Mode or header lines are not
551 included in a window's body height.
553 @cindex window body width
554 @cindex body width of a window
555 The @dfn{body width of a window} denotes the total number of columns
556 occupied by the window's text area. Scroll bars or columns of @samp{|}
557 characters that separate side-by-side windows are not included in a
560 @cindex body size of a window
561 @cindex window body size
562 The following functions retrieve height and width of the body of a live
565 @defun window-body-size &optional window horizontal
566 This function returns the number of lines of @var{window}'s text area.
567 @var{window} must be a live window and defaults to the selected one.
568 The return value does not count any mode or header line of @var{window}.
570 Optional argument @var{horizontal} non-@code{nil} means to return the
571 number of columns of @var{window}'s text area. In this case the return
572 value does not include any vertical divider or scroll bar owned by
573 @var{window}. On a window-system the return value does not include the
574 number of columns used for @var{window}'s fringes or display margins
578 @defun window-body-height &optional window
579 This function returns the number of lines of @var{window}'s body.
580 @var{window} must be a live window and defaults to the selected one.
582 The return value does not include @var{window}'s mode line and header
583 line, if any. If a line at the bottom of the window is only partially
584 visible, that line is included in the return value. If you do not
585 want to include a partially visible bottom line in the return value,
586 use @code{window-text-height} instead.
589 @defun window-body-width &optional window
590 This function returns the number of columns of @var{window}'s body.
591 @var{window} must be a live window and defaults to the selected one.
593 The return value does not include any vertical dividers or scroll bars
594 owned by @var{window}. On a window-system the return value does not
595 include the number of columns used for @var{window}'s fringes or
596 display margins either.
599 The following functions have been used in earlier versions of Emacs.
600 They are still supported but due to the confusing nomenclature they
601 should not be used any more in future code.
603 @defun window-height &optional window
604 This function is an alias for `window-total-height', see above.
607 @defun window-width &optional window
608 This function is an alias for `window-body-width', see above.
611 @cindex minimum window size
612 The following two options constrain the sizes of windows to a minimum
613 height and width. Their values are honored when windows are split
614 (@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}). Any
615 request to make a window smaller than specified here will usually result
618 @defopt window-min-height
619 The value of this variable specifies how short a window may be. The
620 value is measured in line units and has to account for any header or
621 mode line. The default value for this option is @code{4}. Values less
622 than @code{1} are ignored.
625 @defopt window-min-width
626 The value of this variable specifies how narrow a window may be. The
627 value is measured in characters and includes any margins, fringes,
628 scroll bar and vertical divider column. The default value for this
629 option is @code{10}. A value less than @code{2} is ignored.
632 Applications should not rebind these variables. To shrink a specific
633 window to a height or width less than the one specified here, they
634 should rather invoke @code{window-resize} (@pxref{Resizing Windows})
635 with a non-@code{nil} @var{ignore} argument. The function
636 @code{split-window} (@pxref{Splitting Windows}) can make a window
637 smaller than specified here by calling it with a non-@code{nil}
638 @var{size} argument. Interactively, the values specified here cannot be
641 Earlier versions of Emacs could delete a window when its size dropped
642 below @code{window-min-height} or @code{window-min-width}. As a rule,
643 the current version of Emacs does no more delete windows by side-effect.
644 The only exception to this rule are requests to resize a frame which may
645 implicitly delete windows when they do not fit on the frame any more,
646 see @ref{Size and Position}.
648 The size of a window can be fixed which means that it cannot be split
649 (@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}).
651 @cindex fixed-size window
652 @defvar window-size-fixed
653 If this variable is non-@code{nil}, in a given buffer, then the size of
654 any window displaying that buffer remains fixed unless you either
655 explicitly change it or Emacs has no other choice.
657 If the value is @code{height}, then only the window's height is fixed;
658 if the value is @code{width}, then only the window's width is fixed.
659 Any other non-@code{nil} value fixes both the width and the height.
661 This variable automatically becomes buffer-local when set.
664 Commands supposed to explicitly change the size of windows such as
665 @code{enlarge-window} (@pxref{Resizing Windows}) get an error if they
666 had to change a window size which is fixed. Other functions like
667 @code{window-resize} (@pxref{Resizing Windows}) have an optional
668 @var{ignore} argument which allows to change the size of fixed-size
671 Deleting a window or changing a frame's size may change the size of a
672 fixed-size window, if there is no other alternative.
674 The height of a vertical combination of windows cannot be changed
675 when the height of all these windows is fixed. Its width cannot be
676 changed if the width of at least one of these windows is fixed.
677 Similarly, the width of a horizontal combination of windows cannot be
678 changed when the width of all these windows is fixed. Its height cannot
679 be changed if the height of at least one of these windows is fixed.
681 The next function allows to check whether the size of an arbitrary
684 @defun window-size-fixed-p &optional window horizontal
685 This function returns non-@code{nil} if @var{window}'s height is fixed.
686 The argument @var{window} can be an arbitrary window and defaults to the
687 selected one. Optional argument @var{horizontal} non-@code{nil} means
688 return non-@code{nil} if @var{window}'s width is fixed.
690 If this function returns @code{nil}, this does not necessarily mean that
691 @var{window} can be resized in the desired direction. The function
692 @code{window-resizable} (@pxref{Resizing Windows}) can tell that.
696 @node Resizing Windows
697 @section Resizing Windows
698 @cindex window resizing
699 @cindex resize window
700 @cindex changing window size
701 @cindex window size, changing
703 Emacs does not permit overlapping windows or gaps between windows, so
704 changing the size of a window always affects at least one other window.
705 When a frame contains just one window, that window can be resized only
706 by resizing the window's frame. The functions described below are
707 therefore meaningful only in the context of a frame containing at least
708 two windows. The size of the corresponding frame never changes when
709 invoking a function described in this section.
711 The routines changing window sizes always operate in one dimension at
712 a time. This means that windows can be resized only either vertically
713 or horizontally. If a window shall be resized in both dimensions, it
714 must be resized in one dimension first and in the other dimension
715 afterwards. If the second resize operation fails, the frame might end
716 up in an unsatisfactory state. To avoid such states, it might be useful
717 to save the current window configuration (@pxref{Window Configurations})
718 before attempting the first resize operation and restore the saved
719 configuration in case the second resize operation fails.
721 Functions that resize windows are supposed to obey restrictions
722 imposed by window minimum sizes and fixed-size windows, see @ref{Window
723 Sizes}. In order to determine whether resizing a specific window is
724 possible in the first place, the following function can be used:
726 @defun window-resizable window delta &optional horizontal ignore side noup nodown
727 This function returns @var{delta} if the size of @var{window} can be
728 changed vertically by @var{delta} lines. Optional argument
729 @var{horizontal} non-@code{nil} means to return @var{delta} if
730 @var{window} can be resized horizontally by @var{delta} columns. A
731 return value of zero means that @var{window} is not resizable.
733 If @var{delta} is a positive number, this means that @var{window} shall
734 be enlarged by @var{delta} lines or columns. If @var{window} cannot be
735 enlarged by @var{delta} lines or columns, this function returns the
736 maximum value in the range from 0 to @var{delta} by which @var{window}
739 If @var{delta} is a negative number, this means that @var{window} shall
740 be shrunk by -@var{delta} lines or columns. If @var{window} cannot be
741 shrunk by -@var{delta} lines or columns, this function returns the
742 minimum value in the range from @var{delta} to 0 that can be used for
743 shrinking @var{window}.
745 Optional argument @var{ignore} non-@code{nil} means ignore any
746 restrictions imposed by the variables @code{window-min-height} or
747 @code{window-min-width} and @code{window-size-fixed}. In this case the
748 minimum height of a window is specified as the minimum number of lines
749 that allow viewing any header or mode line and at least one line of the
750 text area of window. The minimum width of a window includes any
751 fringes, margins and the scroll bar as well as two text columns.
753 If @var{ignore} denotes a window, this means to ignore restrictions for
754 that window only. If @var{ignore} equals the constant @code{safe}, this
755 means a live window may get as small as one line or two columns.
757 Optional argument @var{noup} non-@code{nil} means don't go up in the
758 window tree but try to steal or distribute the space needed for the
759 resize operation among the other windows within @var{window}'s
760 combination. Optional argument @var{nodown} non-@code{nil} means don't
761 check whether @var{window} itself and its subwindows can be resized.
764 The function @code{window-resizable} does not change any window sizes.
765 The following function does:
767 @defun window-resize window delta &optional horizontal ignore
768 This function resizes @var{window} vertically by @var{delta} lines. The
769 argument @var{window} can denote an arbitrary window and defaults to the
770 selected one. An attempt to resize the root window of a frame will
773 Second argument @var{delta} a positive number means @var{window} shall
774 be enlarged by @var{delta} lines. If @var{delta} is negative, that
775 means @var{window} shall be shrunk by -@var{delta} lines.
777 Optional argument @var{horizontal} non-@code{nil} means to resize
778 @var{window} horizontally by @var{delta} columns. In this case a
779 positive @var{delta} means enlarge @var{window} by @var{delta} columns.
780 A negative @var{delta} means @var{window} shall be shrunk by
781 -@var{delta} columns.
783 Optional argument @var{ignore} has the same meaning as for the function
784 @code{window-resizable} above.
786 This function can simultaneously move two edges of WINDOW. Exactly
787 which edges of @var{window} are moved and which other windows are
788 resized along with @var{window} is determined by the splits and nest
789 status of the involved windows (@pxref{Splitting Windows}). If only the
790 low (right) edge of @var{window} shall be moved, the function
791 @code{adjust-window-trailing-edge} described below should be used.
794 The next four commands are simple interfaces to @code{window-resize}.
795 They always operate on the selected window, never delete any window, and
796 always raise an error when resizing would violate a restriction imposed
797 by @code{window-min-height}, @code{window-min-width}, or
798 @code{window-size-fixed}.
800 @deffn Command enlarge-window delta &optional horizontal
801 This function makes the selected window @var{delta} lines taller.
802 Interactively, if no argument is given, it makes the selected window one
803 line taller. If optional argument @var{horizontal} is non-@code{nil},
804 it makes the selected window wider by @var{delta} columns. If
805 @var{delta} is negative, it shrinks the selected window by -@var{delta}
806 lines or columns. The return value is @code{nil}.
809 @deffn Command enlarge-window-horizontally delta
810 This function makes the selected window @var{delta} columns wider.
811 Interactively, if no argument is given, it makes the selected window one
815 @deffn Command shrink-window delta &optional horizontal
816 This function makes the selected window @var{delta} lines smaller.
817 Interactively, if no argument is given, it makes the selected window one
818 line smaller. If optional argument @var{horizontal} is non-@code{nil},
819 it makes the selected window narrower by @var{delta} columns. If
820 @var{delta} is negative, it enlarges the selected window by -@var{delta}
821 lines or columns. The return value is @code{nil}.
824 @deffn Command shrink-window-horizontally delta
825 This function makes the selected window @var{delta} columns narrower.
826 Interactively, if no argument is given, it makes the selected window one
830 The following function is useful for moving the line dividing two
833 @defun adjust-window-trailing-edge window delta &optional horizontal
834 This function moves @var{window}'s bottom edge by @var{delta} lines.
835 Optional argument @var{horizontal} non-@code{nil} means to move
836 @var{window}'s right edge by @var{delta} columns. The argument
837 @var{window} defaults to the selected window.
839 If @var{delta} is greater zero, this moves the edge downwards or to the
840 right. If @var{delta} is less than zero, this moves the edge upwards or
841 to the left. If the edge can't be moved by @var{delta} lines or columns,
842 it is moved as far as possible in the desired direction but no error is
845 This function tries to resize windows adjacent to the edge that is
846 moved. Only if this is insufficient, it will also resize windows not
847 adjacent to that edge. As a consequence, if you move an edge in one
848 direction and back in the other direction by the same amount, the
849 resulting window configuration will not be necessarily identical to the
850 one before the first move. So if your intend to just resize
851 @var{window}, you should not use this function but call
852 @code{window-resize} (see above) instead.
855 @deffn Command fit-window-to-buffer &optional window max-height min-height override
856 This command makes @var{window} the right height to display its
857 contents exactly. The default for @var{window} is the selected window.
859 The optional argument @var{max-height} specifies the maximum total
860 height the window is allowed to be; @code{nil} means use the maximum
861 permissible height of a window on @var{window}'s frame. The optional
862 argument @var{min-height} specifies the minimum toatl height for the
863 window; @code{nil} means use @code{window-min-height}. All these height
864 values include the mode line and/or header line.
866 If the optional argument @var{override} is non-@code{nil}, this means to
867 ignore any restrictions imposed by @code{window-min-height} and
868 @code{window-min-width} on the size of @var{window}.
870 This function returns non-@code{nil} if it orderly resized @var{window},
871 and @code{nil} otherwise.
874 @deffn Command shrink-window-if-larger-than-buffer &optional window
875 This command shrinks @var{window} vertically to be as small as possible
876 while still showing the full contents of its buffer---but not less than
877 @code{window-min-height} lines. The argument @var{window} must denote
878 a live window and defaults to the selected one.
880 However, this command does nothing if the window is already too small to
881 display the whole text of the buffer, or if part of the contents are
882 currently scrolled off screen, or if the window is not the full width of
883 its frame, or if the window is the only window in its frame.
885 This command returns non-@code{nil} if it actually shrank the window
886 and @code{nil} otherwise.
889 @cindex balancing window sizes
890 Emacs provides two functions to balance windows, that is, to even out
891 the sizes of all windows on the same frame. The minibuffer window and
892 fixed-size windows are not resized by these functions.
894 @deffn Command balance-windows &optional window-or-frame
895 This function balances windows in a way that gives more space to
896 full-width and/or full-height windows. If @var{window-or-frame}
897 specifies a frame, it balances all windows on that frame. If
898 @var{window-or-frame} specifies a window, it balances that window and
899 its siblings (@pxref{Windows and Frames}) only.
902 @deffn Command balance-windows-area
903 This function attempts to give all windows on the selected frame
904 approximately the same share of the screen area. This means that
905 full-width or full-height windows are not given more space than other
909 @cindex maximizing windows
910 The following function can be used to give a window the maximum possible
911 size without deleting other ones.
913 @deffn Command maximize-window &optional window
914 This function maximizes @var{window}. More precisely, this makes
915 @var{window} as large as possible without resizing its frame or deleting
916 other windows. @var{window} can be any window and defaults to the
920 @cindex minimizing windows
921 To make a window as small as possible without deleting it the
922 following function can be used.
924 @deffn Command minimize-window &optional window
925 This function minimizes @var{window}. More precisely, this makes
926 @var{window} as small as possible without deleting it or resizing its
927 frame. @var{window} can be any window and defaults to the selected one.
931 @node Splitting Windows
932 @section Splitting Windows
933 @cindex splitting windows
934 @cindex window splitting
936 The functions described below are the primitives needed for creating a
937 new window. They do not accept a buffer as an argument. Rather, they
938 ``split'' an existing window into two halves, both displaying the buffer
939 previously visible in the window that was split.
941 @deffn Command split-window &optional window size side
942 This function creates a new window adjacent to @var{window}. It returns
943 the new window which is always a live window. The argument @var{window}
944 can denote any window and defaults to the selected one. This function
945 does not change the selected window.
947 Optional second argument @var{size} a positive number means make
948 @var{window} @var{size} lines (or columns) tall. If @var{size} is
949 negative, make the new window @minus{}@var{size} lines (or columns)
950 tall. If @var{size} is omitted or @code{nil}, then @var{window} is
951 divided evenly into two parts. (If there is an odd line, it is
952 allocated to the new window.)
954 If splitting would result in making a window smaller than
955 @code{window-min-height} or @code{window-min-width} (@pxref{Window
956 Sizes}), this function usually signals an error. However, if @var{size}
957 is non-@code{nil} and valid, a new window of the requested size is
958 created. (A size value would be invalid if it assigned less than one
959 line or less than two columns to the new window.)
961 Optional third argument @var{side} @code{nil} (or @code{below})
962 specifies that the new window shall be located below @var{window}. The
963 value @code{above} means the new window will be located above
964 @var{window}. In both cases @var{size} specifies the new number of
965 lines for @var{window} (or the new window if @var{size} is negative)
966 including space reserved for the mode and/or header line.
968 If @var{side} is @code{t} or @code{right} the new window will be
969 positioned on the right side of @var{window}. The value @code{left}
970 means the new window will be located on the left side of @var{window}.
971 In both cases @var{size} specifies the new number of columns for
972 @var{window} (or the new window provided @var{size} is negative)
973 including space reserved for margins, fringes and the scroll bar or a
976 Any other non-@code{nil} value for @var{side} is currently handled like
977 @code{t} (or @code{right}). Since this might change in the future,
978 application programs should refrain from using other values.
980 If @var{window} is live, properties of the new window like margins and
981 scroll bars are inherited from @var{window}. If @var{window} is an
982 internal window, these properties, as well as the buffer shown in the
983 new window, are inherited from the window selected on @var{window}'s
986 If @code{ignore-window-parameters} is non-@code{nil}, this function
987 ignores window parameters (@pxref{Window Parameters}). Otherwise, if
988 the @code{split-window} parameter of @var{window} is @code{t}, it splits
989 the window disregarding any other window parameters. If the
990 @code{split-window} parameter specifies a function, that function is
991 called with the arguments @var{window}, @var{size}, and @var{side} to
992 split @var{window}. If that function is @code{ignore}, nothing is done.
995 The following example starts with one window on a screen that is 50
996 lines high by 80 columns wide; then it splits the window.
1000 (setq W1 (selected-window))
1001 @result{} #<window 8 on windows.texi>
1002 (setq W2 (split-window W1 15))
1003 @result{} #<window 28 on windows.texi>
1006 (window-top-line W1)
1008 (window-total-size W1)
1010 (window-top-line W2)
1015 The screen looks like this:
1031 Next, split the top window into two side-by-side windows:
1035 (setq W3 (split-window W1 35 t))
1036 @result{} #<window 32 on windows.texi>
1039 (window-left-column W1)
1041 (window-total-size W1 t)
1043 (window-left-column W3)
1049 Now the screen looks like this:
1066 Normally, Emacs indicates the border between two side-by-side windows
1067 with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The
1068 display table can specify alternative border characters; see @ref{Display
1071 Below we describe how @code{split-window} can be used to create the
1072 window configuration from our earlier example (@pxref{Windows and
1073 Frames}) and how internal windows are created for this purpose. We
1074 start with a frame containing one live window @code{W2} (in the
1075 following scenarios window names are assigned in an arbitrary manner in
1076 order to match the names of the example). Evaluating the form
1077 @code{(split-window W2 8 t)} creates a new internal window @code{W1}
1078 with two children---@code{W2} (the window we've split) and a new leaf
1082 ______________________________________
1083 | ______ ____________________________ |
1094 ||__W2__||_____________W6_____________ |
1095 |__________________W1__________________|
1100 Evaluating now @code{(split-window W6 -3)} creates another internal
1101 window @code{W3} with two children---@code{W6} and a new live window
1102 @code{W5}. This leaves us with a vertically combined window @code{W3}
1103 embedded in the horizontally combined window @code{W1}:
1106 ______________________________________
1107 | ______ ____________________________ |
1108 || || __________________________ ||
1114 || |||____________W6____________|||
1115 || || __________________________ ||
1117 || |||____________W5____________|||
1118 ||__W2__||_____________W3_____________ |
1119 |__________________W1__________________|
1124 Finally, evaluating @code{(split-window W6 nil t)} should get us the
1125 desired configuration as depicted below.
1128 ______________________________________
1129 | ______ ____________________________ |
1130 || || __________________________ ||
1131 || ||| ___________ ___________ |||
1134 || ||||_____W6____||_____W7____||||
1135 || |||____________W4____________|||
1136 || || __________________________ ||
1138 || |||____________W5____________|||
1139 ||__W2__||_____________W3_____________ |
1140 |__________________W1__________________|
1145 The scenario sketched above is the standard way to obtain the desired
1146 configuration. In Emacs 23 it was also the only way to do that since
1147 Emacs 23 did't allow splitting internal windows.
1149 With Emacs 24 you can also proceed as follows: Split an initial window
1150 @code{W6} by evaluating @code{(split-window W6 -3)} to produce the
1151 following vertical combination:
1154 ______________________________________
1155 | ____________________________________ |
1163 ||_________________W6_________________||
1164 | ____________________________________ |
1166 ||_________________W5_________________||
1167 |__________________W3__________________|
1172 Evaluating now @code{(split-window (window-parent W6) -8 'left)} or,
1173 equivalently, @code{(split-window W3 -8 'left)} should now produce the
1174 penultimate configuration from the previous scenario from where we can
1175 continue as described before.
1177 Another strategy starts with splitting an inital window @code{W6} by
1178 evaluating @code{(split-window W6 nil nil t)} with the following result:
1181 ______________________________________
1182 | _________________ _________________ |
1193 ||________W6_______||________W7_______||
1194 |__________________W4__________________|
1199 Evaluating now @code{(split-window W4 -3)} or @code{(split-window
1200 (window-parent W6) -3)} should get us a configuration as shown next.
1203 ______________________________________
1204 | ____________________________________ |
1205 || ________________ ________________ ||
1211 |||_______W6_______||________W7______|||
1212 ||_________________W4_________________||
1213 | ____________________________________ |
1215 ||_________________W5_________________||
1216 |__________________W3__________________|
1221 The desired configuration can be now obtained by evaluating
1222 @code{(split-window W3 -8 'left)} or, equivalently, @code{(split-window
1223 (window-parent W5) -8 'left)}.
1225 For a final approach let's start with the configuration of two live
1226 windows @code{W6} and @code{W7} shown above. If we now evaluate
1227 @code{(split-window W4 -8 'left)} or @code{(split-window (window-parent
1228 W6) -8 'left)} we get the following configuration.
1231 ______________________________________
1232 | ______ ____________________________ |
1233 || || ____________ ____________ ||
1241 || |||______W6____||______W7____|||
1242 ||__W2__||_____________W4_____________||
1243 |__________________W1__________________|
1248 Evaluating now @code{(split-window W4 -3)} or, for example,
1249 @code{(split-window (window-parent W6) -3)} should produce the desired
1252 The two options described next can be used to tune the operation of
1253 @code{split-window}.
1255 @defopt window-splits
1256 If this variable is nil, the function @code{split-window} can split a
1257 window if and only if that window's screen estate is sufficiently large
1258 to accomodate both--itself and the new window.
1260 If this variable is non-@code{nil}, @code{split-window} tries to resize
1261 all windows that are part of the same combination as the old window to
1262 accomodate the new window. Hence, the new window can be also created if
1263 the old window is of fixed size or too small to split (@pxref{Window
1266 In any case, the value of this variable is assigned to the splits status
1267 of the new window and, provided old and new window form a new
1268 combination, of the old window as well. The splits status of a window
1269 can be retrieved by invoking the function @code{window-splits} and
1270 altered by the function @code{set-window-splits} described next.
1272 If @code{window-nest} (see below) is non-@code{nil}, the space for the
1273 new window is exclusively taken from the old window, but the splits
1274 status of the involved windows is nevertheless set as described here.
1277 @defun window-splits &optional window
1278 This function returns the splits status of @var{window}. The argument
1279 @var{window} can be any window and defaults to the selected one.
1281 @cindex splits status
1282 The @dfn{splits status} of a window specifies how resizing and deleting
1283 that window may affect the size of other windows in the same window
1284 combination. More precisely, if @var{window}'s splits status is
1285 @code{nil} and @var{window} is resized, the corresponding space is
1286 preferably taken from (or given to) @var{window}'s right sibling. When
1287 @var{window} is deleted, its space is given to its left sibling. If
1288 @var{window}'s splits status is non-@code{nil}, resizing and deleting
1289 @var{window} may resize @emph{all} windows in @var{window}'s
1292 The splits status is initially set by @code{split-window}
1293 from the current value of the variable @code{window-splits} (see above)
1294 and can be reset by the function @code{set-window-splits} (see below).
1297 @defun set-window-splits window &optional status
1298 This function sets the splits status (see above) of @var{window} to
1299 @var{status}. The argument @var{window} can be any window and defaults
1300 to the selected one. The return value is @var{status}.
1303 To illustrate the use of @code{window-splits} consider the following
1304 window configuration:
1307 ______________________________________
1308 | ____________________________________ |
1313 ||_________________W2_________________||
1314 | ____________________________________ |
1319 ||_________________W3_________________||
1320 |__________________W1__________________|
1325 Splitting window @code{W3} with @code{window-splits} @code{nil}
1326 produces a configuration where the size of @code{W2} remains unchanged:
1329 ______________________________________
1330 | ____________________________________ |
1335 ||_________________W2_________________||
1336 | ____________________________________ |
1338 ||_________________W3_________________||
1339 | ____________________________________ |
1341 ||_________________W4_________________||
1342 |__________________W1__________________|
1347 Splitting @code{W3} with @code{window-splits} non-@code{nil} instead
1348 produces a configuration where all windows have approximately the same
1353 ______________________________________
1354 | ____________________________________ |
1357 ||_________________W2_________________||
1358 | ____________________________________ |
1361 ||_________________W3_________________||
1362 | ____________________________________ |
1365 ||_________________W4_________________||
1366 |__________________W1__________________|
1372 If this variable is @code{nil}, @code{split-window} creates a new parent
1373 window if and only if the old window has no parent window or shall be
1374 split orthogonally to the combination it is part of. If this variable
1375 is non-@code{nil}, @code{split-window} always creates a new parent
1376 window. If this variable is always non-@code{nil}, a frame's window
1377 tree is a binary tree so every window but the frame's root window has
1378 exactly one sibling.
1380 The value of this variable is also assigned to the nest status of the
1381 new parent window. The nest status of any window can be retrieved via
1382 the function @code{window-nest} and altered by the function
1383 @code{set-window-nest}, see below.
1386 @defun window-nest &optional window
1387 This function returns the nest status of @var{window}. The argument
1388 @var{window} can be any window and defaults to the selected one. Note,
1389 however, that the nest status is currently meaningful for internal
1393 The @dfn{nest status} of a window specifies whether that window may be
1394 removed and its subwindows recombined with that window's siblings when
1395 such a sibling's subwindow is deleted. The nest status is initially
1396 assigned by @code{split-window} from the current value of the variable
1397 @code{window-nest} (see above) and can be reset by the function
1398 @code{set-window-nest} (see below).
1400 If the return value is @code{nil}, subwindows of @var{window} may be
1401 recombined with @var{window}'s siblings when a window gets deleted. A
1402 return value of @code{nil} means that subwindows of @var{window} are
1403 never (re-)combined with @var{window}'s siblings in such a case.
1406 @defun set-window-nest window &optional status
1407 This functions sets the nest status (see above) of @var{window} to
1408 @var{status}. The argument @var{window} can be any window and defaults
1409 to the selected one. Note that setting the nest status is meaningful
1410 for internal windows only. The return value is @var{status}.
1413 To illustrate the use of @code{window-nest} consider the following
1414 configuration (throughout the following examples we shall assume that
1415 @code{window-splits} invariantly is @code{nil}).
1418 ______________________________________
1419 | ____________________________________ |
1426 ||_________________W2_________________||
1427 | ____________________________________ |
1430 ||_________________W3_________________||
1431 |__________________W1__________________|
1436 Splitting @code{W2} into two windows above each other with
1437 @code{window-nest} equal @code{nil} will get you a configuration like:
1440 ______________________________________
1441 | ____________________________________ |
1444 ||_________________W2_________________||
1445 | ____________________________________ |
1448 ||_________________W4_________________||
1449 | ____________________________________ |
1452 ||_________________W3_________________||
1453 |__________________W1__________________|
1458 If you now enlarge window @code{W4}, Emacs steals the necessary space
1459 from window @code{W3} resulting in a configuration like:
1462 ______________________________________
1463 | ____________________________________ |
1466 ||_________________W2_________________||
1467 | ____________________________________ |
1471 ||_________________W4_________________||
1472 | ____________________________________ |
1474 ||_________________W3_________________||
1475 |__________________W1__________________|
1480 Deleting window @code{W4}, will return its space to @code{W2} as
1484 ______________________________________
1485 | ____________________________________ |
1493 ||_________________W2_________________||
1494 | ____________________________________ |
1496 ||_________________W3_________________||
1497 |__________________W1__________________|
1502 Hence, with respect to the initial configuration, window @code{W2} has
1503 grown at the expense of window @code{W3}. If, however, in the initial
1504 configuration you had split @code{W2} with @code{window-nest} bound to
1505 @code{t}, a new internal window @code{W5} would have been created as
1509 ______________________________________
1510 | ____________________________________ |
1511 || __________________________________ ||
1513 |||________________W2________________|||
1514 || __________________________________ ||
1516 |||________________W4________________|||
1517 ||_________________W5_________________||
1518 | ____________________________________ |
1521 ||_________________W3_________________||
1522 |__________________W1__________________|
1527 Enlarging @code{W4} would now have stolen the necessary space from
1528 @code{W2} instead of @code{W3} as
1531 ______________________________________
1532 | ____________________________________ |
1533 || __________________________________ ||
1534 |||________________W2________________|||
1535 || __________________________________ ||
1538 |||________________W4________________|||
1539 ||_________________W5_________________||
1540 | ____________________________________ |
1543 ||_________________W3_________________||
1544 |__________________W1__________________|
1549 and the subsequent deletion of @code{W4} would have restored the initial
1552 For interactive use, Emacs provides two commands which always split the
1555 @deffn Command split-window-above-each-other &optional size
1556 This function splits the selected window into two windows, one above the
1557 other, leaving the upper of the two windows selected, with @var{size}
1558 lines. (If @var{size} is negative, then the lower of the two windows
1559 gets @minus{}@var{size} lines and the upper window gets the rest, but
1560 the upper window is still the one selected.) However, if
1561 @code{split-window-keep-point} (see below) is @code{nil}, then either
1562 window can be selected.
1564 In other respects, this function is similar to @code{split-window}.
1565 In particular, the upper window is the original one and the return value
1566 is the new, lower window.
1569 @defopt split-window-keep-point
1570 If this variable is non-@code{nil} (the default), then
1571 @code{split-window-above-each-other} behaves as described above.
1573 If it is @code{nil}, then @code{split-window-above-each-other}
1574 adjusts point in each of the two windows to avoid scrolling. (This is
1575 useful on slow terminals.) It selects whichever window contains the
1576 screen line that point was previously on. Other functions are not
1577 affected by this variable.
1580 @deffn Command split-window-side-by-side &optional size
1581 This function splits the selected window into two windows
1582 side-by-side, leaving the selected window on the left with @var{size}
1583 columns. If @var{size} is negative, the rightmost window gets
1584 @minus{}@var{size} columns, but the leftmost window still remains
1589 @node Deleting Windows
1590 @section Deleting Windows
1591 @cindex deleting windows
1593 A window remains visible on its frame unless you @dfn{delete} it by
1594 calling certain functions that delete windows. A deleted window cannot
1595 appear on the screen, but continues to exist as a Lisp object until
1596 there are no references to it. There is no way to cancel the deletion
1597 of a window aside from restoring a saved window configuration
1598 (@pxref{Window Configurations}). Restoring a window configuration also
1599 deletes any windows that aren't part of that configuration. Erroneous
1600 information may result from using a deleted window as if it were live.
1602 @deffn Command delete-window &optional window
1603 This function removes @var{window} from display and returns @code{nil}.
1604 The argument @var{window} can denote any window and defaults to the
1605 selected one. An error is signaled if @var{window} is the only window
1606 on its frame. Hence @var{window} must have at least one sibling window
1607 (@pxref{Windows and Frames}) in order to get deleted.
1609 If the variable @code{ignore-window-parameters} (@pxref{Window
1610 Parameters}) is non-@code{nil}, this function ignores all parameters of
1611 @var{window}. Otherwise, if the @code{delete-window} parameter of
1612 @var{window} is @code{t}, it deletes the window disregarding other
1613 window parameters. If the @code{delete-window} parameter specifies a
1614 function, that function is called with @var{window} as its sole
1617 If the splits status of @var{window} (@pxref{Splitting Windows}) is
1618 @code{nil}, the space @var{window} took up is given to its left sibling
1619 if such a window exists and to its right sibling otherwise. If the
1620 splits status of @var{window} is non-@code{nil}, its space is
1621 proportionally distributed among the remaining windows in the same
1625 @deffn Command delete-other-windows &optional window
1626 This function makes @var{window} fill its frame and returns @code{nil}.
1627 The argument @var{window} can denote an arbitrary window and defaults to
1630 If the variable @code{ignore-window-parameters} (@pxref{Window
1631 Parameters}) is non-@code{nil}, this function ignores all parameters of
1632 @var{window}. Otherwise, if the @code{delete-other-windows} parameter
1633 of @var{window} equals @code{t}, it deletes all other windows
1634 disregarding any remaining window parameters. If the
1635 @code{delete-other-windows} parameter of @var{window} specifies a
1636 function, it calls that function with @var{window} as its sole argument.
1639 @deffn Command delete-windows-on &optional buffer-or-name frame
1640 This function deletes all windows showing @var{buffer-or-name} and
1641 returns nil. If there are no windows showing @var{buffer-or-name}, it
1642 does nothing. The optional argument @var{buffer-or-name} may be a
1643 buffer or the name of an existing buffer and defaults to the current
1644 buffer. Invoking this command on a minibuffer signals an error.
1646 The function @code{delete-windows-on} operates by calling
1647 @code{delete-window} for each window showing @var{buffer-or-name}. If a
1648 frame has several windows showing different buffers, then those showing
1649 @var{buffer-or-name} are removed, and the other windows expand to fill
1652 If all windows in some frame are showing @var{buffer-or-name} (including
1653 the case where there is only one window), then that frame is deleted
1654 provided there are other frames left.
1656 The optional argument @var{frame} specifies which frames to operate on.
1657 This function does not use it in quite the same way as the other
1658 functions which scan all live windows (@pxref{Cyclic Window Ordering});
1659 specifically, the values @code{t} and @code{nil} have the opposite of
1660 their meanings in the other functions. Here are the full details:
1664 means operate on all frames.
1666 means operate on the selected frame.
1667 @item @code{visible}
1668 means operate on all visible frames.
1670 means operate on all visible or iconified frames.
1672 means operate on that frame.
1677 @node Selecting Windows
1678 @section Selecting Windows
1679 @cindex selecting a window
1681 @defun select-window window &optional norecord
1682 This function makes @var{window} the selected window, see @ref{Basic
1683 Windows}. Unless @var{window} already is the selected window, this also
1684 makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current
1685 buffer. Moreover, the cursor for selected windows will be displayed in
1686 @var{window} after the next redisplay. This function returns
1689 Normally, @var{window}'s selected buffer is moved to the front of the
1690 buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
1691 recently selected window. But if the optional argument @var{norecord}
1692 is non-@code{nil}, the buffer list remains unchanged and @var{window}
1693 does not become the most recently selected one.
1696 @cindex most recently selected windows
1697 The sequence of calls to @code{select-window} with a non-@code{nil}
1698 @var{norecord} argument determines an ordering of windows by their
1699 selection time. The function @code{get-lru-window} can be used to
1700 retrieve the least recently selected live window in this ordering, see
1701 @ref{Cyclic Window Ordering}.
1703 @defmac save-selected-window forms@dots{}
1704 This macro records the selected frame, as well as the selected window
1705 of each frame, executes @var{forms} in sequence, then restores the
1706 earlier selected frame and windows. It also saves and restores the
1707 current buffer. It returns the value of the last form in @var{forms}.
1709 This macro does not save or restore anything about the sizes,
1710 arrangement or contents of windows; therefore, if @var{forms} change
1711 them, the change persists. If the previously selected window of some
1712 frame is no longer live at the time of exit from @var{forms}, that
1713 frame's selected window is left alone. If the previously selected
1714 window is no longer live, then whatever window is selected at the end of
1715 @var{forms} remains selected. The current buffer is restored if and
1716 only if it is still live when exiting @var{forms}.
1718 This macro changes neither the ordering of recently selected windows nor
1722 @defmac with-selected-window window forms@dots{}
1723 This macro selects @var{window}, executes @var{forms} in sequence, then
1724 restores the previously selected window and current buffer. The ordering
1725 of recently selected windows and the buffer list remain unchanged unless
1726 you deliberately change them within @var{forms}, for example, by calling
1727 @code{select-window} with argument @var{norecord} @code{nil}.
1729 The order of recently selected windows and the buffer list are not
1730 changed by this macro.
1733 @cindex frame selected window
1734 @cindex window selected within frame
1735 Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly
1736 one window on any frame is selected within the frame. The significance
1737 of this designation is that selecting the frame also selects this
1738 window. Conversely, selecting a window for Emacs with
1739 @code{select-window} also makes that window selected within its frame.
1741 @defun frame-selected-window &optional frame
1742 This function returns the window on @var{frame} that is selected within
1743 @var{frame}. The optional argument @var{frame} must denote a live frame
1744 and defaults to the selected one.
1747 @defun set-frame-selected-window frame window &optional norecord
1748 This function sets the selected window of frame @var{frame} to
1749 @var{window}. The argument @var{frame} must denote a live frame and
1750 defaults to the selected one. If @var{frame} is the selected frame,
1751 this also makes @var{window} the selected window. The argument
1752 @var{window} must denote a live window. This function returns
1755 Optional argument @var{norecord} non-@code{nil} means to neither change
1756 the list of most recently selected windows (@pxref{Selecting Windows})
1757 nor the buffer list (@pxref{The Buffer List}).
1761 @node Cyclic Window Ordering
1762 @section Cyclic Ordering of Windows
1763 @cindex cyclic ordering of windows
1764 @cindex ordering of windows, cyclic
1765 @cindex window ordering, cyclic
1767 When you use the command @kbd{C-x o} (@code{other-window}) to select
1768 some other window, it moves through live windows in a specific order.
1769 For any given configuration of windows, this order never varies. It is
1770 called the @dfn{cyclic ordering of windows}.
1772 For a particular frame, this ordering is determined by the window
1773 tree of that frame, see @ref{Windows and Frames}. More precisely, the
1774 ordering is obtained by a depth-first traversal of the frame's window
1775 tree supplemented, if requested, by the frame's minibuffer window.
1777 If there's just one live frame, the cyclic ordering is the ordering
1778 for that frame. Otherwise, the cyclic ordering is obtained by appending
1779 the orderings for individual frames in order of the list of all live
1780 frames, @ref{Finding All Frames}. In any case, the ordering is made
1781 ``cyclic'' by having the last window precede the first window in the
1784 @defun next-window &optional window minibuf all-frames
1785 @cindex minibuffer window, and @code{next-window}
1786 This function returns the window following @var{window} in the cyclic
1787 ordering of windows. The argument @var{window} must specify a live
1788 window and defaults to the selected one.
1790 The optional argument @var{minibuf} specifies whether minibuffer windows
1791 shall be included in the cyclic ordering. Normally, when @var{minibuf}
1792 is @code{nil}, a minibuffer window is included only if it is currently
1793 ``active''; this matches the behavior of @kbd{C-x o}. (Note that a
1794 minibuffer window is active as long as its minibuffer is in use; see
1797 If @var{minibuf} is @code{t}, the cyclic ordering includes all
1798 minibuffer windows. If @var{minibuf} is neither @code{t} nor
1799 @code{nil}, minibuffer windows are not included even if they are active.
1801 The optional argument @var{all-frames} specifies which frames to
1802 consider. Here are the possible values and their meanings:
1806 means consider all windows on @var{window}'s frame, plus the minibuffer
1807 window used by that frame even if it lies in some other frame. If the
1808 minibuffer counts (as determined by @var{minibuf}), then all windows on
1809 all frames that share that minibuffer count too.
1812 means consider all windows on all existing frames.
1814 @item @code{visible}
1815 means consider all windows on all visible frames. (To get useful
1816 results, ensure that @var{window} is on a visible frame.)
1819 means consider all windows on all visible or iconified frames.
1822 means consider all windows on that frame.
1825 means consider the windows on @var{window}'s frame, and no others.
1828 This example assumes there are two windows, both displaying the
1829 buffer @samp{windows.texi}:
1834 @result{} #<window 56 on windows.texi>
1837 (next-window (selected-window))
1838 @result{} #<window 52 on windows.texi>
1841 (next-window (next-window (selected-window)))
1842 @result{} #<window 56 on windows.texi>
1847 @defun previous-window &optional window minibuf all-frames
1848 This function returns the window preceding @var{window} in the cyclic
1849 ordering of windows. The other arguments specify which windows to
1850 consider as in @code{next-window}.
1853 @deffn Command other-window count &optional all-frames
1854 This function selects another window in the cyclic ordering of windows.
1855 @var{count} specifies the number of windows to skip in the ordering,
1856 starting with the selected window, before making the selection. If
1857 @var{count} is a positive number, it skips @var{count} windows forwards.
1858 @var{count} negative means skip @minus{}@var{count} windows backwards.
1859 If @var{count} is zero, it does not skip any window, thus re-selecting
1860 the selected window. In an interactive call, @var{count} is the numeric
1863 The optional argument @var{all-frames} has the same meaning as in
1864 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
1865 is always effectively @code{nil}. This function returns @code{nil}.
1867 This function does not select a window that has a non-@code{nil}
1868 @code{no-other-window} window parameter (@pxref{Window Parameters}).
1871 The following function returns a copy of the list of windows in the
1874 @defun window-list-1 &optional window &optional minibuf &optional all_frames
1875 This function returns a list of live windows. The optional arguments
1876 @var{minibuf} and @var{all-frames} specify the set of windows to include
1877 in the list. See the description of @code{next-window} for details.
1879 The optional argument @var{window} specifies the first window to list
1880 and defaults to the selected window. If @var{window} is not on the list
1881 of windows returned, some other window will be listed first but no error
1885 The functions described below use @code{window-list-1} for generating a
1886 copy of the list of all relevant windows. Hence, any change of the
1887 window configuration that occurs while one of these functions is
1888 executed is @emph{not} reflected in the list of windows investigated.
1890 @defun walk-windows proc &optional minibuf all-frames
1891 This function cycles through live windows. It calls the function
1892 @var{proc} once for each window, with the window as its sole argument.
1894 The optional arguments @var{minibuf} and @var{all-frames} specify the
1895 set of windows to include in the walk, see @code{next-window} above. If
1896 @var{all-frames} specifies a frame, the first window walked is the first
1897 window on that frame as returned by @code{frame-first-window} and not
1898 necessarily the selected window.
1900 If @var{proc} changes the window configuration by splitting or deleting
1901 windows, that change is not reflected in the set of windows walked.
1902 That set is determined entirely by the set of live windows at the time
1903 this function was invoked.
1906 The following function allows to determine whether a specific window is
1907 the only live window.
1909 @defun one-window-p &optional no-mini all-frames
1910 This function returns non-@code{nil} if the selected window is the only
1913 The optional argument @var{no-mini}, if non-@code{nil}, means don't
1914 count the minibuffer even if it is active; otherwise, the minibuffer
1915 window is counted when it is active. The optional argument
1916 @var{all-frames} has the same meaning as for @code{next-window}, see
1920 @cindex finding windows
1921 The following functions choose (but do not select) one of the windows
1922 on the screen, offering various criteria for the choice.
1924 @cindex least recently used window
1925 @defun get-lru-window &optional all-frames dedicated
1926 This function returns the window least recently ``used'' (that is,
1927 selected). If any full-width windows are present, it only considers
1928 these. The optional argument @var{all-frames} has the same meaning as
1929 in @code{next-window}.
1931 The selected window is returned if it is the only candidate. A
1932 minibuffer window is never a candidate. A dedicated window
1933 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1934 argument @var{dedicated} is non-@code{nil}.
1937 @cindex largest window
1938 @defun get-largest-window &optional all-frames dedicated
1939 This function returns the window with the largest area (height times
1940 width). A minibuffer window is never a candidate. A dedicated window
1941 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1942 argument @var{dedicated} is non-@code{nil}.
1944 If there are two candidate windows of the same size, this function
1945 prefers the one that comes first in the cyclic ordering of windows,
1946 starting from the selected window.
1948 The optional argument @var{all-frames} specifies which set of windows to
1949 consider as with @code{next-window}, see above.
1952 @cindex window that satisfies a predicate
1953 @cindex conditional selection of windows
1954 @defun get-window-with-predicate predicate &optional minibuf all-frames default
1955 This function returns a window satisfying @var{predicate}. It cycles
1956 through all visible windows calling @var{predicate} on each one of them
1957 with that window as its argument. The function returns the first window
1958 for which @var{predicate} returns a non-@code{nil} value; if that never
1959 happens, it returns @var{default} (which defaults to @code{nil}).
1961 The optional arguments @var{minibuf} and @var{all-frames} specify the
1962 set of windows to investigate. See the description of
1963 @code{next-window} for details.
1966 @node Buffers and Windows
1967 @section Buffers and Windows
1968 @cindex examining windows
1969 @cindex windows, controlling precisely
1970 @cindex buffers, controlled in windows
1972 To find out which buffer is displayed in a given window the following
1975 @defun window-buffer &optional window
1976 This function returns the buffer that @var{window} is displaying. The
1977 argument @var{window} can be any window and defaults to the selected
1978 one. If @var{window} is an internal window, this function returns
1982 The basic, low-level function to associate a window with a buffer is
1983 @code{set-window-buffer}. Higher-level functions like
1984 @code{switch-to-buffer} and @code{display-buffer} try to obey a number
1985 of user customizations regulating which windows are supposed to
1986 display which buffers. @xref{Switching Buffers}. When writing an
1987 application, you should avoid using @code{set-window-buffer} unless
1988 you are sure you need it.
1990 @defun set-window-buffer window buffer-or-name &optional keep-margins
1991 This function makes @var{window} display @var{buffer-or-name} and
1992 returns @code{nil}. The argument @var{window} has to denote a live
1993 window and defaults to the selected one. The argument
1994 @var{buffer-or-name} must specify a buffer or the name of an existing
1995 buffer. An error is signalled when @var{window} is @dfn{strongly}
1996 dedicated to its buffer (@pxref{Dedicated Windows}) and does not already
1997 display @var{buffer-or-name}.
1999 Normally, displaying @var{buffer-or-name} in @var{window} resets the
2000 window's position, display margins, fringe widths, and scroll bar
2001 settings based on the local variables of the specified buffer. However,
2002 if the optional argument @var{keep-margins} is non-@code{nil}, display
2003 margins and fringe widths of @var{window} remain unchanged.
2006 This function is the fundamental primitive for changing which buffer is
2007 displayed in a window, and all ways of doing that call this function.
2008 Neither the selected window nor the current buffer are changed by this
2011 This function runs @code{window-scroll-functions} before running
2012 @code{window-configuration-change-hook}, see @ref{Window Hooks}.
2015 @defvar buffer-display-count
2016 This buffer-local variable records the number of times a buffer has been
2017 displayed in a window. It is incremented each time
2018 @code{set-window-buffer} is called for the buffer.
2021 @defvar buffer-display-time
2022 This variable records the time at which a buffer was last made visible
2023 in a window. It is always local in each buffer; each time
2024 @code{set-window-buffer} is called, it sets this variable to
2025 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
2026 When a buffer is first created, @code{buffer-display-time} starts out
2027 with the value @code{nil}.
2030 @defun get-buffer-window &optional buffer-or-name all-frames
2031 This function returns a window displaying @var{buffer-or-name}, or
2032 @code{nil} if there is none. If there are several such windows, then
2033 the function returns the first one in the cyclic ordering of windows,
2034 starting from the selected window, @xref{Cyclic Window Ordering}.
2036 The argument @var{buffer-or-name} may be a buffer or a buffer name and
2037 defaults to the current buffer. The optional argument @var{all-frames}
2038 specifies which windows to consider:
2042 @code{nil} means consider windows on the selected frame.
2044 @code{t} means consider windows on all existing frames.
2046 @code{visible} means consider windows on all visible frames.
2048 0 means consider windows on all visible or iconified frames.
2050 A frame means consider windows on that frame only.
2053 Observe that the behavior of @code{get-buffer-window} may differ from
2054 that of @code{next-window} (@pxref{Cyclic Window Ordering}) when
2055 @var{all-frames} equals @code{nil} or any value not listed here.
2056 Perhaps we will change @code{get-buffer-window} in the future to make it
2057 compatible with the other functions.
2060 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
2061 This function returns a list of all windows currently displaying
2062 @var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer
2063 or the name of an existing buffer and defaults to the current buffer.
2065 The two remaining arguments work like the same-named arguments of
2066 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
2067 like the optional arguments of @code{get-buffer-window}.
2070 @deffn Command replace-buffer-in-windows &optional buffer-or-name
2071 This command replaces @var{buffer-or-name} with some other buffer, in
2072 all windows displaying it. For each such window, it choose another
2073 buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
2075 @var{buffer-or-name} may be a buffer, or the name of an existing
2076 buffer; it defaults to the current buffer.
2078 If a window displaying @var{buffer-or-name} is dedicated
2079 (@pxref{Dedicated Windows}) has never displayed any other buffers and
2080 is not the only window on its frame, that window is deleted. If that
2081 window is the only window on its frame and there are other frames on
2082 the frame's terminal, that frame is deleted too; otherwise, some other
2083 buffer is displayed in that window, as explained above. A user can
2084 prevent the deletion of windows and/or frames by customizing the
2085 option @code{window-auto-delete}.
2088 @node Switching Buffers
2089 @section Switching to a Buffer in a Window
2090 @cindex switching to a buffer
2091 @cindex displaying a buffer
2093 This section describes high-level functions for switching to a
2094 specified buffer in some window.
2096 Do @emph{not} use these functions to make a buffer temporarily
2097 current so that a Lisp program can access or modify it; they have
2098 side-effects that may surprise the user, such as changing window
2099 histories (@pxref{Window History}). Instead, use
2100 @code{with-current-buffer}, @code{save-current-buffer}, or
2101 @code{set-buffer} (@pxref{Current Buffer}).
2103 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
2104 This function displays @var{buffer-or-name} in the selected window,
2105 and makes it the current buffer. (In contrast, @code{set-buffer}
2106 makes the buffer current but does not display it; @pxref{Current
2107 Buffer}). It is often used interactively (as the binding of @kbd{C-x
2108 b}), as well as in Lisp programs. The return value is the buffer
2111 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2112 returned by @code{other-buffer} (@pxref{The Buffer List}). If
2113 @var{buffer-or-name} is a string that is not the name of any existing
2114 buffer, this function creates a new buffer with that name; the new
2115 buffer's major mode is determined by the variable @code{major-mode}
2116 (@pxref{Major Modes}).
2118 Normally the specified buffer is put at the front of the buffer
2119 list---both the global buffer list and the selected frame's buffer
2120 list (@pxref{The Buffer List}). However, this is not done if the
2121 optional argument @var{norecord} is non-@code{nil}.
2123 If this function is unable to display in the seleted window---usually
2124 because the selected window is a minibuffer window or is strongly
2125 dedicated to its buffer (@pxref{Dedicated Windows})---then it normally
2126 tries to display in some other window, in the manner of
2127 @code{pop-to-buffer} (see below). However, if the optional argument
2128 @var{force-same-window} is non-@code{nil}, it signals an error
2132 The next two functions are similar to @code{switch-to-buffer}, except
2133 for the described features.
2135 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
2136 This function makes the buffer specified by @var{buffer-or-name}
2137 current and displays it in some window other than the selected window.
2138 It uses the function @code{pop-to-buffer} internally (see below).
2140 If the selected window already displays the specified buffer, it
2141 continues to do so, but another window is nonetheless found to display
2144 The @var{buffer-or-name} and @var{norecord} arguments have the same
2145 meanings as in @code{switch-to-buffer}.
2148 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
2149 This function makes the buffer specified by @var{buffer-or-name}
2150 current and displays it, usually in a new frame. It uses the function
2151 @code{pop-to-buffer} (see below).
2153 If the specified buffer is already displayed in another window, in any
2154 frame on the current terminal, this switches to that window instead of
2155 creating a new frame. However, the selected window is never used for
2158 The @var{buffer-or-name} and @var{norecord} arguments have the same
2159 meanings as in @code{switch-to-buffer}.
2162 The above commands use @code{pop-to-buffer}, which is the function
2163 used by Lisp programs to flexibly display a buffer in some window and
2164 select that window for editing:
2166 @defun pop-to-buffer buffer-or-name &optional action norecord
2167 This function makes @var{buffer-or-name} the current buffer and
2168 displays it in some window, preferably not the window previously
2169 selected. It then selects the displaying window. If that window is
2170 on a different graphical frame, that frame is given input focus if
2171 possible (@pxref{Input Focus}). The return value is the buffer that
2174 This function uses @code{display-buffer} to display the buffer, so all
2175 the variables affecting @code{display-buffer} will affect it as well.
2176 @xref{Choosing Window}.
2178 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2179 returned by @code{other-buffer} (@pxref{The Buffer List}). If
2180 @var{buffer-or-name} is a string that is not the name of any existing
2181 buffer, this function creates a new buffer with that name; the new
2182 buffer's major mode is determined by the variable @code{major-mode}
2183 (@pxref{Major Modes}).
2185 If @var{action} is non-@code{nil}, it should be a display action to
2186 pass to @code{display-buffer} (@pxref{Choosing Window}).
2187 Alternatively, a non-@code{nil}, non-list value means to pop to a
2188 window other than the selected one---even if the buffer is already
2189 displayed in the selected window.
2191 Like @code{switch-to-buffer}, this function updates the buffer list
2192 unless @var{norecord} is non-@code{nil}.
2195 @node Choosing Window
2196 @section Choosing a Window for Display
2198 The command @code{display-buffer} flexibly chooses a window for
2199 display, and displays a specified buffer in that window. It can be
2200 called interactively, via the key binding @kbd{C-x 4 o}. It is also
2201 used as a subroutine by many functions and commands, including
2202 @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
2205 @cindex display action
2206 This command performs several complex steps to find a window to
2207 display in. These steps are described by means of @dfn{display
2208 actions}, which have the form @code{(@var{function} . @var{alist})}.
2209 Here, @var{function} is either a function or a list of functions,
2210 while @var{alist} is an association list. In this section, we will
2211 refer to such functions as @dfn{action functions}, and such alists as
2212 @dfn{action alists}.
2214 An action function should accept two arguments: the buffer to
2215 display and an action alist. It should attempt to display the buffer
2216 in some window, picking or creating a window based on some internal
2217 criteria (as well as, optionally, the action alist). If successful,
2218 it should return the window; otherwise, it should return @code{nil}.
2220 @code{display-buffer} works by combining display actions from
2221 several sources (including some user-customizable options), and
2222 calling the action functions in turn, until one of the action
2223 functions manages to display the buffer and returns a non-@code{nil}
2226 @deffn Command display-buffer buffer-or-name &optional action frame
2227 This command makes @var{buffer-or-name} appear in some window, without
2228 selecting the window or making the buffer current. The argument
2229 @var{buffer-or-name} must be a buffer or the name of an existing
2230 buffer. The return value is the window chosen to display the buffer.
2232 The optional argument @var{action}, if non-@code{nil}, should normally
2233 be a display action (described above). @code{display-buffer} builds a
2234 list of action functions and an action alist, by consolidating display
2235 actions from the following sources (in order):
2239 The variable @code{display-buffer-overriding-action}.
2242 The user option @code{display-buffer-alist}.
2245 The @var{action} argument.
2248 The user option @code{display-buffer-base-action}.
2251 The variable @code{display-buffer-fallback-action}. This is
2252 non-@code{nil} by default, and specifies the fallback behavior if no
2253 other display actions are given.
2257 Each action function is called in turn, passing the buffer as the
2258 first argument and the combined action alist as the second argument,
2259 until one of the functions returns non-nil.
2261 The argument @var{action} can also have a non-@code{nil}, non-list
2262 value. This has the special meaning that the buffer should be
2263 displayed in a window other than the selected one, even if the
2264 selected window is already displaying it. If called interactively
2265 with a prefix argument, @var{action} is @code{t}.
2267 The optional argument @var{frame}, if non-@code{nil}, specifies which
2268 frames to check when deciding whether the buffer is already displayed.
2269 If the buffer is already displayed in some window on one of these
2270 frames, @code{display-buffer} simply returns that window. Here are
2271 the possible values of @var{frame}:
2275 @code{nil} means consider windows on the selected frame.
2276 (Actually, the last non-minibuffer frame.)
2278 @code{t} means consider windows on all frames.
2280 @code{visible} means consider windows on all visible frames.
2282 0 means consider windows on all visible or iconified frames.
2284 A frame means consider windows on that frame only.
2287 Precisely how @code{display-buffer} finds or creates a window depends on
2288 the variables described below.
2291 @defopt display-buffer-reuse-frames
2292 If this variable is non-@code{nil}, @code{display-buffer} searches
2293 visible and iconified frames for a window displaying
2294 @var{buffer-or-name}. If there is such a window, @code{display-buffer}
2295 makes that window's frame visible and raises it if necessary, and
2296 returns the window. If there is no such window or
2297 @code{display-buffer-reuse-frames} is @code{nil}, the behavior of
2298 @code{display-buffer} is determined by the variables described next.
2301 @defopt pop-up-windows
2302 This variable specifies whether @code{display-buffer} is allowed to
2303 split (@pxref{Splitting Windows}) an existing window. If this variable
2304 is non-@code{nil}, @code{display-buffer} tries to split the largest or
2305 least recently used window on the selected frame. (If the selected
2306 frame is a minibuffer-only frame, @code{display-buffer} tries to split a
2307 window on another frame instead.) If this variable is @code{nil} or the
2308 variable @code{pop-up-frames} (see below) is non-@code{nil},
2309 @code{display-buffer} does not split any window.
2312 @defopt split-window-preferred-function
2313 This variable must specify a function with one argument, which is a
2314 window. The @code{display-buffer} routines will call this function with
2315 one or more candidate windows when they look for a window to split. The
2316 function is expected to split that window and return the new window. If
2317 the function returns @code{nil}, this means that the argument window
2318 cannot (or shall not) be split.
2320 The default value of @code{split-window-preferred-function} is the
2321 function @code{split-window-sensibly} described below. If you
2322 customize this option, bear in mind that the @code{display-buffer}
2323 routines may call your function up to two times when trying to split a
2324 window. The argument of the first call is the largest window on the
2325 chosen frame (as returned by @code{get-largest-window}). If that call
2326 fails to return a live window, your function is called a second time
2327 with the least recently used window on that frame (as returned by
2328 @code{get-lru-window}).
2330 The function specified by this option may try to split any other window
2331 instead of the argument window. Note that the window selected at the
2332 time @code{display-buffer} was invoked is still selected when your
2333 function is called. Hence, you can split the selected window (instead
2334 of the largest or least recently used one) by simply ignoring the window
2335 argument in the body of your function. You can even choose to not split
2336 any window as long as the return value of your function specifies a live
2337 window or @code{nil}, but you are not encouraged to do so
2338 unconditionally. If you want @code{display-buffer} to never split any
2339 windows, set @code{pop-up-windows} to @code{nil}.
2342 @defun split-window-sensibly window
2343 This function takes a window as argument and tries to split that window
2344 in a suitable way. The two variables described next are useful for
2345 tuning the behavior of this function.
2348 @defopt split-height-threshold
2349 This variable specifies whether @code{split-window-sensibly} may split
2350 windows vertically. If it is an integer, @code{split-window-sensibly}
2351 tries to vertically split a window only if it has at least this many
2352 lines. If the window has less lines, splitting fails, or the value of
2353 this variable is @code{nil}, @code{split-window-sensibly} will try to
2354 split the window horizontally, subject to restrictions of
2355 @code{split-width-threshold} (see below). If splitting horizontally
2356 fails too and the window is the only window on its frame,
2357 @code{split-window-sensibly} will try to split the window vertically
2358 disregarding the value of @code{split-height-threshold}. If this fails
2359 as well, @code{split-window-sensibly} returns @code{nil}.
2361 @code{split-window-sensibly} does not split vertically a window whose
2362 height is fixed (@pxref{Resizing Windows}). Also, it vertically splits
2363 a window only if the space taken up by that window can accommodate two
2364 windows one above the other that are both at least
2365 @code{window-min-height} lines tall. Moreover, if the window that shall
2366 be split has a mode line, @code{split-window-sensibly} does not split
2367 the window unless the new window can accommodate a mode line too.
2370 @defopt split-width-threshold
2371 This variable specifies whether @code{split-window-sensibly} may split
2372 windows horizontally. If it is an integer, @code{split-window-sensibly}
2373 tries to horizontally split a window only if it has at least this many
2374 columns. If it is @code{nil}, @code{split-window-sensibly} will not
2375 split the window horizontally. (It still might split the window
2376 vertically, though, see above.)
2378 @code{split-window-sensibly} does not split horizontally a window if
2379 that window's width is fixed (@pxref{Resizing Windows}). Also, it
2380 horizontally splits a window only if the space that window takes up can
2381 accommodate two windows side by side that are both at least
2382 @code{window-min-width} columns wide.
2385 @defopt even-window-heights
2386 This variable specifies whether @code{display-buffer} should even out
2387 window heights if the buffer gets displayed in an existing window, above
2388 or beneath another window. If @code{even-window-heights} is
2389 non-@code{nil}, the default, window heights will be evened out. If
2390 either of the involved window has fixed height (@pxref{Resizing
2391 Windows}) or @code{even-window-heights} is @code{nil}, the original
2392 window heights will be left alone.
2396 @defopt pop-up-frames
2397 This variable specifies whether @code{display-buffer} should make new
2398 frames. If it is non-@code{nil}, @code{display-buffer} looks for a
2399 window already displaying @var{buffer-or-name} on any visible or
2400 iconified frame. If it finds such a window, it makes that window's
2401 frame visible and raises it if necessary, and returns the window.
2402 Otherwise it makes a new frame, unless the variable's value is
2403 @code{graphic-only} and the selected frame is not on a graphic display.
2404 @xref{Frames}, for more information.
2406 Note that the value of @code{pop-up-windows} does not matter if
2407 @code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is
2408 @code{nil}, then @code{display-buffer} either splits a window or reuses
2413 @defopt pop-up-frame-function
2414 This variable specifies how to make a new frame if @code{pop-up-frames}
2417 The value of this variable must be a function of no arguments. When
2418 @code{display-buffer} makes a new frame, it does so by calling that
2419 function, which should return a frame. The default value of this
2420 variable is a function that creates a frame using the parameters
2421 specified by @code{pop-up-frame-alist} described next.
2424 @defopt pop-up-frame-alist
2425 This variable holds an alist specifying frame parameters used by the
2426 default value of @code{pop-up-frame-function} for making new frames.
2427 @xref{Frame Parameters}, for more information about frame parameters.
2430 @defopt special-display-buffer-names
2431 A list of buffer names identifying buffers that should be displayed
2432 specially. If the name of @var{buffer-or-name} is in this list,
2433 @code{display-buffer} handles the buffer specially. By default, special
2434 display means to give the buffer a dedicated frame.
2436 If an element is a list, instead of a string, then the @sc{car} of that
2437 list is the buffer name, and the rest of that list says how to create
2438 the frame. There are two possibilities for the rest of that list (its
2439 @sc{cdr}): It can be an alist, specifying frame parameters, or it can
2440 contain a function and arguments to give to it. (The function's first
2441 argument is always the buffer to be displayed; the arguments from the
2442 list come after that.)
2447 (("myfile" (minibuffer) (menu-bar-lines . 0)))
2451 specifies to display a buffer named @samp{myfile} in a dedicated frame
2452 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
2454 The list of frame parameters can also use the phony frame parameters
2455 @code{same-frame} and @code{same-window}. If the specified frame
2456 parameters include @code{(same-window . @var{value})} and @var{value}
2457 is non-@code{nil}, that means to display the buffer in the current
2458 selected window. Otherwise, if they include @code{(same-frame .
2459 @var{value})} and @var{value} is non-@code{nil}, that means to display
2460 the buffer in a new window in the currently selected frame.
2463 @defopt special-display-regexps
2464 A list of regular expressions specifying buffers that should be
2465 displayed specially. If the buffer's name matches any of the regular
2466 expressions in this list, @code{display-buffer} handles the buffer
2467 specially. By default, special display means to give the buffer a
2470 If an element is a list, instead of a string, then the @sc{car} of the
2471 list is the regular expression, and the rest of the list says how to
2472 create the frame. See @code{special-display-buffer-names} above.
2475 @defun special-display-p buffer-name
2476 This function returns non-@code{nil} if displaying a buffer
2477 named @var{buffer-name} with @code{display-buffer} would
2478 create a special frame. The value is @code{t} if it would
2479 use the default frame parameters, or else the specified list
2480 of frame parameters.
2483 @defopt special-display-function
2484 This variable holds the function to call to display a buffer specially.
2485 It receives the buffer as an argument, and should return the window in
2486 which it is displayed. The default value of this variable is
2487 @code{special-display-popup-frame}, see below.
2490 @defun special-display-popup-frame buffer &optional args
2491 This function tries to make @var{buffer} visible in a frame of its own.
2492 If @var{buffer} is already displayed in some window, it makes that
2493 window's frame visible and raises it. Otherwise, it creates a frame
2494 that is dedicated to @var{buffer}. The return value is the window used
2495 to display @var{buffer}.
2497 If @var{args} is an alist, it specifies frame parameters for the new
2498 frame. If @var{args} is a list whose @sc{car} is a symbol, then
2499 @code{(car @var{args})} is called as a function to actually create and
2500 set up the frame; it is called with @var{buffer} as first argument, and
2501 @code{(cdr @var{args})} as additional arguments.
2503 This function always uses an existing window displaying @var{buffer},
2504 whether or not it is in a frame of its own; but if you set up the above
2505 variables in your init file, before @var{buffer} was created, then
2506 presumably the window was previously made by this function.
2509 @defopt special-display-frame-alist
2510 @anchor{Definition of special-display-frame-alist}
2511 This variable holds frame parameters for
2512 @code{special-display-popup-frame} to use when it creates a frame.
2515 @defopt same-window-buffer-names
2516 A list of buffer names for buffers that should be displayed in the
2517 selected window. If the buffer's name is in this list,
2518 @code{display-buffer} handles the buffer by switching to it in the
2522 @defopt same-window-regexps
2523 A list of regular expressions that specify buffers that should be
2524 displayed in the selected window. If the buffer's name matches any of
2525 the regular expressions in this list, @code{display-buffer} handles the
2526 buffer by switching to it in the selected window.
2529 @defun same-window-p buffer-name
2530 This function returns @code{t} if displaying a buffer
2531 named @var{buffer-name} with @code{display-buffer} would
2532 put it in the selected window.
2536 @defopt display-buffer-function
2537 This variable is the most flexible way to customize the behavior of
2538 @code{display-buffer}. If it is non-@code{nil}, it should be a function
2539 that @code{display-buffer} calls to do the work. The function should
2540 accept two arguments, the first two arguments that @code{display-buffer}
2541 received. It should choose or create a window, display the specified
2542 buffer in it, and then return the window.
2544 This variable takes precedence over all the other options described
2548 If all options described above fail to produce a suitable window,
2549 @code{display-buffer} tries to reuse an existing window. As a last
2550 resort, it will try to display @var{buffer-or-name} on a separate frame.
2551 In that case, the value of @code{pop-up-frames} is disregarded.
2553 @node Window History
2554 @section Window History
2555 @cindex window history
2557 Each window remembers the buffers it has displayed earlier and the
2558 order in which these buffers have been removed from it. This history
2559 is used, for example, by @code{replace-buffer-in-windows}
2560 (@pxref{Buffers and Windows}). This list is set automatically
2561 maintained by Emacs, but you can use the following functions to
2562 explicitly inspect or alter it:
2564 @defun window-prev-buffers &optional window
2565 This function returns a list specifying the previous contents of
2566 @var{window}, which should be a live window and defaults to the
2569 Each list element has the form @code{(@var{buffer} @var{window-start}
2570 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
2571 the window, @var{window-start} is the window start position when that
2572 buffer was last shown, and @var{window-pos} is the point position when
2573 that buffer was last shown.
2575 The list is ordered so that earlier elements correspond to more
2576 recently-shown buffers, and the first element corresponds to the
2577 buffer most recently removed from the window.
2580 @defun set-window-prev-buffers window prev-buffers
2581 This function sets @var{window}'s previous buffers to the value of
2582 @var{prev-buffers}. The argument @var{window} must be a live window
2583 and defaults to the selected one. The argument @var{prev-buffers}
2584 should be a list of the same form as that returned by
2585 @code{window-prev-buffers}.
2588 In addition, each buffer maintains a list of @dfn{next buffers}, which
2589 is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
2590 below). This list is mainly used by @code{switch-to-prev-buffer} and
2591 @code{switch-to-next-buffer} for choosing buffers to switch to.
2593 @defun window-next-buffers &optional window
2594 This function returns the list of buffers recently re-shown in
2595 @var{window} via @code{switch-to-prev-buffer}. @var{window} should be
2596 a live window or @code{nil} (meaning the selected window).
2599 @defun set-window-next-buffers window next-buffers
2600 This function sets the next buffer list of @var{window} to
2601 @var{next-buffers}. The @var{window} argument should be a live window
2602 or @code{nil} (meaning the selected window). The argument
2603 @var{next-buffers} should be a list of buffers.
2606 The following commands can be used to cycle through the global buffer
2607 list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
2608 they cycle according to the specified window's history list, rather
2609 than the global buffer list. In addition, they restore
2610 window-specific window start and point positions, and may show a
2611 buffer even if it is already shown in another window. The
2612 @code{switch-to-prev-buffer} command, in particular, is used by
2613 @code{replace-buffer-in-windows}, @code{bury-buffer} and
2614 @code{quit-window} to find a replacement buffer for a window.
2616 @deffn Command switch-to-prev-buffer &optional window bury-or-kill
2617 This command displays the previous buffer in @var{window}. The
2618 argument @var{window} should be a live window or @code{nil} (meaning
2619 the selected window). If the optional argument @var{bury-or-kill} is
2620 non-@code{nil}, this means that the buffer currently shown in
2621 @var{window} is about to be buried or killed and consequently shall
2622 not be switched to in future invocations of this command.
2624 The previous buffer is usually the buffer shown before the buffer
2625 currently shown in @var{window}. However, a buffer that has been buried
2626 or killed or has been already shown by a recent invocation of
2627 @code{switch-to-prev-buffer} does not qualify as previous buffer.
2629 If repeated invocations of this command have already shown all buffers
2630 previously shown in @var{window}, further invocations will show buffers
2631 from the global buffer list starting with the buffer returned by
2632 @code{last-buffer} (@pxref{The Buffer List}).
2635 @deffn Command switch-to-next-buffer &optional window
2636 This command switches to the next buffer in @var{window} thus undoing
2637 the effect of the last @code{switch-to-prev-buffer} command in
2638 @var{window}. The argument @var{window} must be a live window and
2639 defaults to the selected one.
2641 If there is no recent invocation of a @code{switch-to-prev-buffer}
2642 that can be undone, this function tries to show the first buffer from
2643 the global buffer list as returned by @code{other-buffer} (@pxref{The
2647 @node Dedicated Windows
2648 @section Dedicated Windows
2649 @cindex dedicated window
2651 Functions for displaying a buffer can be told to not use specific
2652 windows by marking these windows as @dfn{dedicated} to their buffers.
2653 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
2654 window for displaying another buffer in it. @code{get-lru-window} and
2655 @code{get-largest-window} (@pxref{Selecting Windows}) do not consider
2656 dedicated windows as candidates when their @var{dedicated} argument is
2657 non-@code{nil}. The behavior of @code{set-window-buffer}
2658 (@pxref{Buffers and Windows}) with respect to dedicated windows is
2659 slightly different, see below.
2661 When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
2662 delete a dedicated window and that window is the only window on its
2663 frame, it deletes the window's frame too, provided there are other
2664 frames left. @code{replace-buffer-in-windows} (@pxref{Switching
2665 Buffers}) tries to delete all dedicated windows showing its buffer
2666 argument. When such a window is the only window on its frame, that
2667 frame is deleted, provided there are other frames left. If there are
2668 no more frames left, some other buffer is displayed in the window, and
2669 the window is marked as non-dedicated.
2671 When you kill a buffer (@pxref{Killing Buffers}) displayed in a
2672 dedicated window, any such window usually gets deleted too, since
2673 @code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
2674 up windows. Burying a buffer (@pxref{The Buffer List}) deletes the
2675 selected window if it is dedicated to that buffer. If, however, that
2676 window is the only window on its frame, @code{bury-buffer} displays
2677 another buffer in it and iconifies the frame.
2679 @defun window-dedicated-p &optional window
2680 This function returns non-@code{nil} if @var{window} is dedicated to its
2681 buffer and @code{nil} otherwise. More precisely, the return value is
2682 the value assigned by the last call of @code{set-window-dedicated-p} for
2683 @var{window} or @code{nil} if that function was never called with
2684 @var{window} as its argument. The default for @var{window} is the
2688 @defun set-window-dedicated-p window flag
2689 This function marks @var{window} as dedicated to its buffer if
2690 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
2692 As a special case, if @var{flag} is @code{t}, @var{window} becomes
2693 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
2694 signals an error when the window it acts upon is strongly dedicated to
2695 its buffer and does not already display the buffer it is asked to
2696 display. Other functions do not treat @code{t} differently from any
2697 non-@code{nil} value.
2701 @section Windows and Point
2702 @cindex window position
2703 @cindex window point
2704 @cindex position in window
2705 @cindex point in window
2707 Each window has its own value of point (@pxref{Point}), independent of
2708 the value of point in other windows displaying the same buffer. This
2709 makes it useful to have multiple windows showing one buffer.
2713 The window point is established when a window is first created; it is
2714 initialized from the buffer's point, or from the window point of another
2715 window opened on the buffer if such a window exists.
2718 Selecting a window sets the value of point in its buffer from the
2719 window's value of point. Conversely, deselecting a window sets the
2720 window's value of point from that of the buffer. Thus, when you switch
2721 between windows that display a given buffer, the point value for the
2722 selected window is in effect in the buffer, while the point values for
2723 the other windows are stored in those windows.
2726 As long as the selected window displays the current buffer, the window's
2727 point and the buffer's point always move together; they remain equal.
2731 As far as the user is concerned, point is where the cursor is, and
2732 when the user switches to another buffer, the cursor jumps to the
2733 position of point in that buffer.
2735 @defun window-point &optional window
2736 This function returns the current position of point in @var{window}.
2737 For a nonselected window, this is the value point would have (in that
2738 window's buffer) if that window were selected. The default for
2739 @var{window} is the selected window.
2741 When @var{window} is the selected window and its buffer is also the
2742 current buffer, the value returned is the same as point in that buffer.
2743 Strictly speaking, it would be more correct to return the ``top-level''
2744 value of point, outside of any @code{save-excursion} forms. But that
2745 value is hard to find.
2748 @defun set-window-point window position
2749 This function positions point in @var{window} at position
2750 @var{position} in @var{window}'s buffer. It returns @var{position}.
2752 If @var{window} is selected, and its buffer is current,
2753 this simply does @code{goto-char}.
2756 @defvar window-point-insertion-type
2757 This variable specifies the marker insertion type (@pxref{Marker
2758 Insertion Types}) of @code{window-point}. The default is @code{nil},
2759 so @code{window-point} will stay behind text inserted there.
2762 @node Window Start and End
2763 @section The Window Start and End Positions
2764 @cindex window start position
2766 Each window maintains a marker used to keep track of a buffer position
2767 that specifies where in the buffer display should start. This position
2768 is called the @dfn{display-start} position of the window (or just the
2769 @dfn{start}). The character after this position is the one that appears
2770 at the upper left corner of the window. It is usually, but not
2771 inevitably, at the beginning of a text line.
2773 After switching windows or buffers, and in some other cases, if the
2774 window start is in the middle of a line, Emacs adjusts the window
2775 start to the start of a line. This prevents certain operations from
2776 leaving the window start at a meaningless point within a line. This
2777 feature may interfere with testing some Lisp code by executing it
2778 using the commands of Lisp mode, because they trigger this
2779 readjustment. To test such code, put it into a command and bind the
2782 @defun window-start &optional window
2783 @cindex window top line
2784 This function returns the display-start position of window
2785 @var{window}. If @var{window} is @code{nil}, the selected window is
2795 When you create a window, or display a different buffer in it, the
2796 display-start position is set to a display-start position recently used
2797 for the same buffer, or to @code{point-min} if the buffer doesn't have
2800 Redisplay updates the window-start position (if you have not specified
2801 it explicitly since the previous redisplay)---to make sure point appears
2802 on the screen. Nothing except redisplay automatically changes the
2803 window-start position; if you move point, do not expect the window-start
2804 position to change in response until after the next redisplay.
2806 For a realistic example of using @code{window-start}, see the
2807 description of @code{count-lines}. @xref{Definition of count-lines}.
2810 @cindex window end position
2811 @defun window-end &optional window update
2812 This function returns the position where display of its buffer ends in
2813 @var{window}. The default for @var{window} is the selected window.
2815 Simply changing the buffer text or moving point does not update the
2816 value that @code{window-end} returns. The value is updated only when
2817 Emacs redisplays and redisplay completes without being preempted.
2819 If the last redisplay of @var{window} was preempted, and did not finish,
2820 Emacs does not know the position of the end of display in that window.
2821 In that case, this function returns @code{nil}.
2823 If @var{update} is non-@code{nil}, @code{window-end} always returns an
2824 up-to-date value for where display ends, based on the current
2825 @code{window-start} value. If a previously saved value of that position
2826 is still valid, @code{window-end} returns that value; otherwise it
2827 computes the correct value by scanning the buffer text.
2829 Even if @var{update} is non-@code{nil}, @code{window-end} does not
2830 attempt to scroll the display if point has moved off the screen, the
2831 way real redisplay would do. It does not alter the
2832 @code{window-start} value. In effect, it reports where the displayed
2833 text will end if scrolling is not required.
2836 @defun set-window-start window position &optional noforce
2837 This function sets the display-start position of @var{window} to
2838 @var{position} in @var{window}'s buffer. It returns @var{position}.
2840 The display routines insist that the position of point be visible when a
2841 buffer is displayed. Normally, they change the display-start position
2842 (that is, scroll the window) whenever necessary to make point visible.
2843 However, if you specify the start position with this function using
2844 @code{nil} for @var{noforce}, it means you want display to start at
2845 @var{position} even if that would put the location of point off the
2846 screen. If this does place point off screen, the display routines move
2847 point to the left margin on the middle line in the window.
2849 For example, if point @w{is 1} and you set the start of the window
2850 @w{to 37}, the start of the next line, point will be ``above'' the top
2851 of the window. The display routines will automatically move point if
2852 it is still 1 when redisplay occurs. Here is an example:
2856 ;; @r{Here is what @samp{foo} looks like before executing}
2857 ;; @r{the @code{set-window-start} expression.}
2861 ---------- Buffer: foo ----------
2862 @point{}This is the contents of buffer foo.
2868 ---------- Buffer: foo ----------
2882 ;; @r{Here is what @samp{foo} looks like after executing}
2883 ;; @r{the @code{set-window-start} expression.}
2884 ---------- Buffer: foo ----------
2890 ---------- Buffer: foo ----------
2894 If @var{noforce} is non-@code{nil}, and @var{position} would place point
2895 off screen at the next redisplay, then redisplay computes a new window-start
2896 position that works well with point, and thus @var{position} is not used.
2899 @defun pos-visible-in-window-p &optional position window partially
2900 This function returns non-@code{nil} if @var{position} is within the
2901 range of text currently visible on the screen in @var{window}. It
2902 returns @code{nil} if @var{position} is scrolled vertically out of view.
2903 Locations that are partially obscured are not considered visible unless
2904 @var{partially} is non-@code{nil}. The argument @var{position} defaults
2905 to the current position of point in @var{window}; @var{window}, to the
2906 selected window. If @var{position} is @code{t}, that means to check the
2907 last visible position in @var{window}.
2909 This function considers only vertical scrolling. If @var{position} is
2910 out of view only because @var{window} has been scrolled horizontally,
2911 @code{pos-visible-in-window-p} returns non-@code{nil} anyway.
2912 @xref{Horizontal Scrolling}.
2914 If @var{position} is visible, @code{pos-visible-in-window-p} returns
2915 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
2916 non-@code{nil}, and the character following @var{position} is fully
2917 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
2918 @var{x} and @var{y} are the pixel coordinates relative to the top left
2919 corner of the window; otherwise it returns an extended list of the form
2920 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
2921 where @var{rtop} and @var{rbot} specify the number of off-window pixels
2922 at the top and bottom of the row at @var{position}, @var{rowh} specifies
2923 the visible height of that row, and @var{vpos} specifies the vertical
2924 position (zero-based row number) of that row.
2930 ;; @r{If point is off the screen now, recenter it now.}
2931 (or (pos-visible-in-window-p
2932 (point) (selected-window))
2938 @defun window-line-height &optional line window
2939 This function returns the height of text line @var{line} in
2940 @var{window}. If @var{line} is one of @code{header-line} or
2941 @code{mode-line}, @code{window-line-height} returns information about
2942 the corresponding line of the window. Otherwise, @var{line} is a text
2943 line number starting from 0. A negative number counts from the end of
2944 the window. The default for @var{line} is the current line in
2945 @var{window}; the default for @var{window} is the selected window.
2947 If the display is not up to date, @code{window-line-height} returns
2948 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
2949 to obtain related information.
2951 If there is no line corresponding to the specified @var{line},
2952 @code{window-line-height} returns @code{nil}. Otherwise, it returns
2953 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
2954 where @var{height} is the height in pixels of the visible part of the
2955 line, @var{vpos} and @var{ypos} are the vertical position in lines and
2956 pixels of the line relative to the top of the first text line, and
2957 @var{offbot} is the number of off-window pixels at the bottom of the
2958 text line. If there are off-window pixels at the top of the (first)
2959 text line, @var{ypos} is negative.
2962 @node Textual Scrolling
2963 @section Textual Scrolling
2964 @cindex textual scrolling
2965 @cindex scrolling textually
2967 @dfn{Textual scrolling} means moving the text up or down through a
2968 window. It works by changing the value of the window's display-start
2969 location. It may also change the value of @code{window-point} to keep
2970 point on the screen.
2972 Textual scrolling was formerly called ``vertical scrolling,'' but we
2973 changed its name to distinguish it from the new vertical fractional
2974 scrolling feature (@pxref{Vertical Scrolling}).
2976 In the commands @code{scroll-up} and @code{scroll-down}, the directions
2977 ``up'' and ``down'' refer to the motion of the text in the buffer at which
2978 you are looking through the window. Imagine that the text is
2979 written on a long roll of paper and that the scrolling commands move the
2980 paper up and down. Thus, if you are looking at text in the middle of a
2981 buffer and repeatedly call @code{scroll-down}, you will eventually see
2982 the beginning of the buffer.
2984 Some people have urged that the opposite convention be used: they
2985 imagine that the window moves over text that remains in place. Then
2986 ``down'' commands would take you to the end of the buffer. This view is
2987 more consistent with the actual relationship between windows and the
2988 text in the buffer, but it is less like what the user sees. The
2989 position of a window on the terminal does not move, and short scrolling
2990 commands clearly move the text up or down on the screen. We have chosen
2991 names that fit the user's point of view.
2993 The textual scrolling functions (aside from
2994 @code{scroll-other-window}) have unpredictable results if the current
2995 buffer is different from the buffer that is displayed in the selected
2996 window. @xref{Current Buffer}.
2998 If the window contains a row which is taller than the height of the
2999 window (for example in the presence of a large image), the scroll
3000 functions will adjust the window's vertical scroll position to scroll
3001 the partially visible row. To disable this feature, Lisp code may bind
3002 the variable @code{auto-window-vscroll} to @code{nil} (@pxref{Vertical
3005 @deffn Command scroll-up &optional count
3006 This function scrolls the text in the selected window upward
3007 @var{count} lines. If @var{count} is negative, scrolling is actually
3010 If @var{count} is @code{nil} (or omitted), then the length of scroll
3011 is @code{next-screen-context-lines} lines less than the usable height of
3012 the window (not counting its mode line).
3014 @code{scroll-up} returns @code{nil}, unless it gets an error
3015 because it can't scroll any further.
3018 @deffn Command scroll-down &optional count
3019 This function scrolls the text in the selected window downward
3020 @var{count} lines. If @var{count} is negative, scrolling is actually
3023 If @var{count} is omitted or @code{nil}, then the length of the scroll
3024 is @code{next-screen-context-lines} lines less than the usable height of
3025 the window (not counting its mode line).
3027 @code{scroll-down} returns @code{nil}, unless it gets an error because
3028 it can't scroll any further.
3031 @deffn Command scroll-other-window &optional count
3032 This function scrolls the text in another window upward @var{count}
3033 lines. Negative values of @var{count}, or @code{nil}, are handled
3034 as in @code{scroll-up}.
3036 You can specify which buffer to scroll by setting the variable
3037 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
3038 already displayed, @code{scroll-other-window} displays it in some
3041 When the selected window is the minibuffer, the next window is normally
3042 the one at the top left corner. You can specify a different window to
3043 scroll, when the minibuffer is selected, by setting the variable
3044 @code{minibuffer-scroll-window}. This variable has no effect when any
3045 other window is selected. When it is non-@code{nil} and the
3046 minibuffer is selected, it takes precedence over
3047 @code{other-window-scroll-buffer}. @xref{Definition of
3048 minibuffer-scroll-window}.
3050 When the minibuffer is active, it is the next window if the selected
3051 window is the one at the bottom right corner. In this case,
3052 @code{scroll-other-window} attempts to scroll the minibuffer. If the
3053 minibuffer contains just one line, it has nowhere to scroll to, so the
3054 line reappears after the echo area momentarily displays the message
3055 @samp{Beginning of buffer}.
3059 @defvar other-window-scroll-buffer
3060 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
3061 which buffer's window to scroll.
3064 @defopt scroll-margin
3065 This option specifies the size of the scroll margin---a minimum number
3066 of lines between point and the top or bottom of a window. Whenever
3067 point gets within this many lines of the top or bottom of the window,
3068 redisplay scrolls the text automatically (if possible) to move point
3069 out of the margin, closer to the center of the window.
3072 @defopt scroll-conservatively
3073 This variable controls how scrolling is done automatically when point
3074 moves off the screen (or into the scroll margin). If the value is a
3075 positive integer @var{n}, then redisplay scrolls the text up to
3076 @var{n} lines in either direction, if that will bring point back into
3077 proper view. This behavior is called @dfn{conservative scrolling}.
3078 Otherwise, scrolling happens in the usual way, under the control of
3079 other variables such as @code{scroll-up-aggressively} and
3080 @code{scroll-down-aggressively}.
3082 The default value is zero, which means that conservative scrolling
3086 @defopt scroll-down-aggressively
3087 The value of this variable should be either @code{nil} or a fraction
3088 @var{f} between 0 and 1. If it is a fraction, that specifies where on
3089 the screen to put point when scrolling down. More precisely, when a
3090 window scrolls down because point is above the window start, the new
3091 start position is chosen to put point @var{f} part of the window
3092 height from the top. The larger @var{f}, the more aggressive the
3095 A value of @code{nil} is equivalent to .5, since its effect is to center
3096 point. This variable automatically becomes buffer-local when set in any
3100 @defopt scroll-up-aggressively
3101 Likewise, for scrolling up. The value, @var{f}, specifies how far
3102 point should be placed from the bottom of the window; thus, as with
3103 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
3107 This variable is an older variant of @code{scroll-conservatively}.
3108 The difference is that if its value is @var{n}, that permits scrolling
3109 only by precisely @var{n} lines, not a smaller number. This feature
3110 does not work with @code{scroll-margin}. The default value is zero.
3113 @defopt scroll-preserve-screen-position
3114 If this option is @code{t}, scrolling which would move the current
3115 point position out of the window chooses the new position of point
3116 so that the vertical position of the cursor is unchanged, if possible.
3118 If it is non-@code{nil} and not @code{t}, then the scrolling functions
3119 always preserve the vertical position of point, if possible.
3122 @defopt next-screen-context-lines
3123 The value of this variable is the number of lines of continuity to
3124 retain when scrolling by full screens. For example, @code{scroll-up}
3125 with an argument of @code{nil} scrolls so that this many lines at the
3126 bottom of the window appear instead at the top. The default value is
3130 @deffn Command recenter &optional count
3131 @cindex centering point
3132 This function scrolls the text in the selected window so that point is
3133 displayed at a specified vertical position within the window. It does
3134 not ``move point'' with respect to the text.
3136 If @var{count} is a nonnegative number, that puts the line containing
3137 point @var{count} lines down from the top of the window. If
3138 @var{count} is a negative number, then it counts upward from the
3139 bottom of the window, so that @minus{}1 stands for the last usable
3140 line in the window. If @var{count} is a non-@code{nil} list, then it
3141 stands for the line in the middle of the window.
3143 If @var{count} is @code{nil}, @code{recenter} puts the line containing
3144 point in the middle of the window, then clears and redisplays the entire
3147 When @code{recenter} is called interactively, @var{count} is the raw
3148 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
3149 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
3150 @var{count} to 4, which positions the current line four lines from the
3153 With an argument of zero, @code{recenter} positions the current line at
3154 the top of the window. This action is so handy that some people make a
3155 separate key binding to do this. For example,
3159 (defun line-to-top-of-window ()
3160 "Scroll current line to top of window.
3161 Replaces three keystroke sequence C-u 0 C-l."
3165 (global-set-key [kp-multiply] 'line-to-top-of-window)
3170 @node Vertical Scrolling
3171 @section Vertical Fractional Scrolling
3172 @cindex vertical fractional scrolling
3173 @cindex vertical scroll position
3175 @dfn{Vertical fractional scrolling} means shifting text in a window
3176 up or down by a specified multiple or fraction of a line. Each window
3177 has a @dfn{vertical scroll position}, which is a number, never less than
3178 zero. It specifies how far to raise the contents of the window.
3179 Raising the window contents generally makes all or part of some lines
3180 disappear off the top, and all or part of some other lines appear at the
3181 bottom. The usual value is zero.
3183 The vertical scroll position is measured in units of the normal line
3184 height, which is the height of the default font. Thus, if the value is
3185 .5, that means the window contents are scrolled up half the normal line
3186 height. If it is 3.3, that means the window contents are scrolled up
3187 somewhat over three times the normal line height.
3189 What fraction of a line the vertical scrolling covers, or how many
3190 lines, depends on what the lines contain. A value of .5 could scroll a
3191 line whose height is very short off the screen, while a value of 3.3
3192 could scroll just part of the way through a tall line or an image.
3194 @defun window-vscroll &optional window pixels-p
3195 This function returns the current vertical scroll position of
3196 @var{window}. The default for @var{window} is the selected window.
3197 If @var{pixels-p} is non-@code{nil}, the return value is measured in
3198 pixels, rather than in units of the normal line height.
3208 @defun set-window-vscroll window lines &optional pixels-p
3209 This function sets @var{window}'s vertical scroll position to
3210 @var{lines}. If @var{window} is @code{nil}, the selected window is
3211 used. The argument @var{lines} should be zero or positive; if not, it
3215 The actual vertical scroll position must always correspond
3216 to an integral number of pixels, so the value you specify
3217 is rounded accordingly.
3219 The return value is the result of this rounding.
3223 (set-window-vscroll (selected-window) 1.2)
3228 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
3229 pixels. In this case, the return value is @var{lines}.
3232 @defvar auto-window-vscroll
3233 If this variable is non-@code{nil}, the line-move, scroll-up, and
3234 scroll-down functions will automatically modify the vertical scroll
3235 position to scroll through display rows that are taller than the height
3236 of the window, for example in the presence of large images.
3239 @node Horizontal Scrolling
3240 @section Horizontal Scrolling
3241 @cindex horizontal scrolling
3243 @dfn{Horizontal scrolling} means shifting the image in the window left
3244 or right by a specified multiple of the normal character width. Each
3245 window has a @dfn{horizontal scroll position}, which is a number, never
3246 less than zero. It specifies how far to shift the contents left.
3247 Shifting the window contents left generally makes all or part of some
3248 characters disappear off the left, and all or part of some other
3249 characters appear at the right. The usual value is zero.
3251 The horizontal scroll position is measured in units of the normal
3252 character width, which is the width of space in the default font. Thus,
3253 if the value is 5, that means the window contents are scrolled left by 5
3254 times the normal character width. How many characters actually
3255 disappear off to the left depends on their width, and could vary from
3258 Because we read from side to side in the ``inner loop,'' and from top
3259 to bottom in the ``outer loop,'' the effect of horizontal scrolling is
3260 not like that of textual or vertical scrolling. Textual scrolling
3261 involves selection of a portion of text to display, and vertical
3262 scrolling moves the window contents contiguously; but horizontal
3263 scrolling causes part of @emph{each line} to go off screen.
3265 Usually, no horizontal scrolling is in effect; then the leftmost
3266 column is at the left edge of the window. In this state, scrolling to
3267 the right is meaningless, since there is no data to the left of the edge
3268 to be revealed by it; so this is not allowed. Scrolling to the left is
3269 allowed; it scrolls the first columns of text off the edge of the window
3270 and can reveal additional columns on the right that were truncated
3271 before. Once a window has a nonzero amount of leftward horizontal
3272 scrolling, you can scroll it back to the right, but only so far as to
3273 reduce the net horizontal scroll to zero. There is no limit to how far
3274 left you can scroll, but eventually all the text will disappear off the
3277 @vindex auto-hscroll-mode
3278 If @code{auto-hscroll-mode} is set, redisplay automatically alters
3279 the horizontal scrolling of a window as necessary to ensure that point
3280 is always visible. However, you can still set the horizontal
3281 scrolling value explicitly. The value you specify serves as a lower
3282 bound for automatic scrolling, i.e. automatic scrolling will not
3283 scroll a window to a column less than the specified one.
3285 @deffn Command scroll-left &optional count set-minimum
3286 This function scrolls the selected window @var{count} columns to the
3287 left (or to the right if @var{count} is negative). The default
3288 for @var{count} is the window width, minus 2.
3290 The return value is the total amount of leftward horizontal scrolling in
3291 effect after the change---just like the value returned by
3292 @code{window-hscroll} (below).
3294 Once you scroll a window as far right as it can go, back to its normal
3295 position where the total leftward scrolling is zero, attempts to scroll
3296 any farther right have no effect.
3298 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
3299 the lower bound for automatic scrolling; that is, automatic scrolling
3300 will not scroll a window to a column less than the value returned by
3301 this function. Interactive calls pass non-@code{nil} for
3305 @deffn Command scroll-right &optional count set-minimum
3306 This function scrolls the selected window @var{count} columns to the
3307 right (or to the left if @var{count} is negative). The default
3308 for @var{count} is the window width, minus 2. Aside from the direction
3309 of scrolling, this works just like @code{scroll-left}.
3312 @defun window-hscroll &optional window
3313 This function returns the total leftward horizontal scrolling of
3314 @var{window}---the number of columns by which the text in @var{window}
3315 is scrolled left past the left margin. The default for
3316 @var{window} is the selected window.
3318 The return value is never negative. It is zero when no horizontal
3319 scrolling has been done in @var{window} (which is usually the case).
3338 @defun set-window-hscroll window columns
3339 This function sets horizontal scrolling of @var{window}. The value of
3340 @var{columns} specifies the amount of scrolling, in terms of columns
3341 from the left margin. The argument @var{columns} should be zero or
3342 positive; if not, it is taken as zero. Fractional values of
3343 @var{columns} are not supported at present.
3345 Note that @code{set-window-hscroll} may appear not to work if you test
3346 it by evaluating a call with @kbd{M-:} in a simple way. What happens
3347 is that the function sets the horizontal scroll value and returns, but
3348 then redisplay adjusts the horizontal scrolling to make point visible,
3349 and this overrides what the function did. You can observe the
3350 function's effect if you call it while point is sufficiently far from
3351 the left margin that it will remain visible.
3353 The value returned is @var{columns}.
3357 (set-window-hscroll (selected-window) 10)
3363 Here is how you can determine whether a given position @var{position}
3364 is off the screen due to horizontal scrolling:
3368 (defun hscroll-on-screen (window position)
3370 (goto-char position)
3372 (>= (- (current-column) (window-hscroll window)) 0)
3373 (< (- (current-column) (window-hscroll window))
3374 (window-width window)))))
3379 @node Coordinates and Windows
3380 @section Coordinates and Windows
3382 This section describes how to relate screen coordinates to windows.
3384 @defun window-at x y &optional frame
3385 This function returns the window containing the specified cursor
3386 position in the frame @var{frame}. The coordinates @var{x} and @var{y}
3387 are measured in characters and count from the top left corner of the
3388 frame. If they are out of range, @code{window-at} returns @code{nil}.
3390 If you omit @var{frame}, the selected frame is used.
3393 @defun coordinates-in-window-p coordinates window
3394 This function checks whether a particular frame position falls within
3395 the window @var{window}.
3397 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
3398 . @var{y})}. The coordinates @var{x} and @var{y} are measured in
3399 characters, and count from the top left corner of the screen or frame.
3401 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
3402 if the coordinates are inside @var{window}. The value also indicates
3403 what part of the window the position is in, as follows:
3406 @item (@var{relx} . @var{rely})
3407 The coordinates are inside @var{window}. The numbers @var{relx} and
3408 @var{rely} are the equivalent window-relative coordinates for the
3409 specified position, counting from 0 at the top left corner of the
3413 The coordinates are in the mode line of @var{window}.
3416 The coordinates are in the header line of @var{window}.
3419 The coordinates are in the vertical line between @var{window} and its
3420 neighbor to the right. This value occurs only if the window doesn't
3421 have a scroll bar; positions in a scroll bar are considered outside the
3422 window for these purposes.
3426 The coordinates are in the left or right fringe of the window.
3430 The coordinates are in the left or right margin of the window.
3433 The coordinates are not in any part of @var{window}.
3436 The function @code{coordinates-in-window-p} does not require a frame as
3437 argument because it always uses the frame that @var{window} is on.
3441 @node Window Configurations
3442 @section Window Configurations
3443 @cindex window configurations
3444 @cindex saving window information
3446 A @dfn{window configuration} records the entire layout of one
3447 frame---all windows, their sizes, which buffers they contain, how those
3448 buffers are scrolled, and their values of point and the mark; also their
3449 fringes, margins, and scroll bar settings. It also includes the value
3450 of @code{minibuffer-scroll-window}. As a special exception, the window
3451 configuration does not record the value of point in the selected window
3452 for the current buffer. Also, the window configuration does not record
3453 the values of window parameters; see @ref{Window Parameters}.
3455 You can bring back an entire frame layout by restoring a previously
3456 saved window configuration. If you want to record the layout of all
3457 frames instead of just one, use a frame configuration instead of a
3458 window configuration; see @ref{Frame Configurations}.
3460 @defun current-window-configuration &optional frame
3461 This function returns a new object representing @var{frame}'s current
3462 window configuration. The default for @var{frame} is the selected
3466 @defun set-window-configuration configuration
3467 This function restores the configuration of windows and buffers as
3468 specified by @var{configuration}, for the frame that @var{configuration}
3471 The argument @var{configuration} must be a value that was previously
3472 returned by @code{current-window-configuration}. The configuration is
3473 restored in the frame from which @var{configuration} was made, whether
3474 that frame is selected or not. This always counts as a window size
3475 change and triggers execution of the @code{window-size-change-functions}
3476 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
3477 know how to tell whether the new configuration actually differs from the
3480 If the frame which @var{configuration} was saved from is dead, all this
3481 function does is restore the three variables @code{window-min-height},
3482 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
3483 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
3485 Here is a way of using this function to get the same effect
3486 as @code{save-window-excursion}:
3490 (let ((config (current-window-configuration)))
3492 (progn (split-window-vertically nil)
3494 (set-window-configuration config)))
3499 @defspec save-window-excursion forms@dots{}
3500 This special form records the window configuration, executes @var{forms}
3501 in sequence, then restores the earlier window configuration. The window
3502 configuration includes, for each window, the value of point and the
3503 portion of the buffer that is visible. It also includes the choice of
3504 selected window. However, it does not include the value of point in
3505 the current buffer; use @code{save-excursion} also, if you wish to
3508 Don't use this construct when @code{save-selected-window} is sufficient.
3510 Exit from @code{save-window-excursion} always triggers execution of
3511 @code{window-size-change-functions}. (It doesn't know how to tell
3512 whether the restored configuration actually differs from the one in
3513 effect at the end of the @var{forms}.)
3515 The return value is the value of the final form in @var{forms}.
3521 @result{} #<window 25 on control.texi>
3524 (setq w (selected-window))
3525 @result{} #<window 19 on control.texi>
3528 (save-window-excursion
3529 (delete-other-windows w)
3530 (switch-to-buffer "foo")
3532 @result{} do-something
3533 ;; @r{The screen is now split again.}
3538 @defun window-configuration-p object
3539 This function returns @code{t} if @var{object} is a window configuration.
3542 @defun compare-window-configurations config1 config2
3543 This function compares two window configurations as regards the
3544 structure of windows, but ignores the values of point and mark and the
3545 saved scrolling positions---it can return @code{t} even if those
3548 The function @code{equal} can also compare two window configurations; it
3549 regards configurations as unequal if they differ in any respect, even a
3550 saved point or mark.
3553 @defun window-configuration-frame config
3554 This function returns the frame for which the window configuration
3555 @var{config} was made.
3558 Other primitives to look inside of window configurations would make
3559 sense, but are not implemented because we did not need them. See the
3560 file @file{winner.el} for some more operations on windows
3563 @node Window Parameters
3564 @section Window Parameters
3565 @cindex window parameters
3567 This sections describes how window parameters can be used to associate
3568 additional information with windows.
3570 @defun window-parameter window parameter
3571 This function returns @var{window}'s value for @var{parameter}. The
3572 default for @var{window} is the selected window. If @var{window}
3573 has no setting for @var{parameter}, this function returns @code{nil}.
3576 @defun window-parameters &optional window
3577 This function returns all parameters of @var{window} and their values.
3578 The default for @var{window} is the selected window. The return value
3579 is an association list of elements of the form @code{(@var{parameter}
3583 @defun set-window-parameter window parameter value
3584 This function sets @var{window}'s value of @var{parameter} to
3585 @var{value} and returns @var{value}. The default for @var{window}
3586 is the selected window.
3589 Currently, window parameters are not saved in window configurations and
3590 consequently not restored by @code{set-window-configuration}. Hence,
3591 any change of a parameter introduced via @code{set-window-parameter} can
3592 be undone only by invoking @code{set-window-parameter} for the same
3593 parameter again. Since @code{save-window-excursion} relies on window
3594 configurations (@pxref{Window Configurations}), window parameters are
3595 not saved and restored by that special form, either.
3598 @section Hooks for Window Scrolling and Changes
3599 @cindex hooks for window operations
3601 This section describes how a Lisp program can take action whenever a
3602 window displays a different part of its buffer or a different buffer.
3603 There are three actions that can change this: scrolling the window,
3604 switching buffers in the window, and changing the size of the window.
3605 The first two actions run @code{window-scroll-functions}; the last runs
3606 @code{window-size-change-functions}.
3608 @defvar window-scroll-functions
3609 This variable holds a list of functions that Emacs should call before
3610 redisplaying a window with scrolling. Displaying a different buffer in
3611 the window also runs these functions.
3613 This variable is not a normal hook, because each function is called with
3614 two arguments: the window, and its new display-start position.
3616 These functions must be careful in using @code{window-end}
3617 (@pxref{Window Start and End}); if you need an up-to-date value, you
3618 must use the @var{update} argument to ensure you get it.
3620 @strong{Warning:} don't use this feature to alter the way the window
3621 is scrolled. It's not designed for that, and such use probably won't
3625 @defvar window-size-change-functions
3626 This variable holds a list of functions to be called if the size of any
3627 window changes for any reason. The functions are called just once per
3628 redisplay, and just once for each frame on which size changes have
3631 Each function receives the frame as its sole argument. There is no
3632 direct way to find out which windows on that frame have changed size, or
3633 precisely how. However, if a size-change function records, at each
3634 call, the existing windows and their sizes, it can also compare the
3635 present sizes and the previous sizes.
3637 Creating or deleting windows counts as a size change, and therefore
3638 causes these functions to be called. Changing the frame size also
3639 counts, because it changes the sizes of the existing windows.
3641 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
3642 Configurations}) in these functions, because that always counts as a
3643 size change, and it would cause these functions to be called over and
3644 over. In most cases, @code{save-selected-window} (@pxref{Selecting
3645 Windows}) is what you need here.
3648 @defvar window-configuration-change-hook
3649 A normal hook that is run every time you change the window configuration
3650 of an existing frame. This includes splitting or deleting windows,
3651 changing the sizes of windows, or displaying a different buffer in a
3654 The buffer-local part of this hook is run once per each window on the
3655 affected frame, with the relevant window selected and its buffer
3656 current. The global part is run once for the modified frame, with that
3660 In addition, you can use @code{jit-lock-register} to register a Font
3661 Lock fontification function, which will be called whenever parts of a
3662 buffer are (re)fontified because a window was scrolled or its size
3663 changed. @xref{Other Font Lock Variables}.