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 * Display Action Functions:: Subroutines for @code{display-buffer}.
28 * Choosing Window Options:: Extra options affecting how buffers are displayed.
29 * Window History:: Each window remembers the buffers displayed in it.
30 * Dedicated Windows:: How to avoid displaying another buffer in
32 * Quitting Windows:: How to restore the state prior to displaying a
34 * Window Point:: Each window has its own location of point.
35 * Window Start and End:: Buffer positions indicating which text is
36 on-screen in a window.
37 * Textual Scrolling:: Moving text up and down through the window.
38 * Vertical Scrolling:: Moving the contents up and down on the window.
39 * Horizontal Scrolling:: Moving the contents sideways on the window.
40 * Coordinates and Windows:: Converting coordinates to windows.
41 * Window Configurations:: Saving and restoring the state of the screen.
42 * Window Parameters:: Associating additional information with windows.
43 * Window Hooks:: Hooks for scrolling, window size changes,
44 redisplay going past a certain point,
45 or window configuration changes.
50 @section Basic Concepts of Emacs Windows
53 A @dfn{window} is a area of the screen which is used to display a
54 buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a
55 special Lisp object type.
57 @cindex multiple windows
58 Windows are grouped into frames (@pxref{Frames}). Each frame
59 contains at least one window; the user can subdivide it into multiple,
60 non-overlapping windows to view several buffers at once. Lisp
61 programs can use multiple windows for a variety of purposes. In
62 Rmail, for example, you can view a summary of message titles in one
63 window, and the contents of the selected message in another window.
65 @cindex terminal screen
66 @cindex screen of terminal
67 Emacs uses the word ``window'' with a different meaning than in
68 graphical desktop environments and window systems, such as the X
69 Window System. When Emacs is run on X, each of its graphical X
70 windows is an Emacs frame (containing one or more Emacs windows).
71 When Emacs is run on a text-only terminal, the frame fills the entire
75 Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
76 within the area of the frame. When a window is created, resized, or
77 deleted, the change in window space is taken from or given to the
78 adjacent windows, so that the total area of the frame is unchanged.
81 @cindex internal windows
82 A @dfn{live window} is one that is actually displaying a buffer in a
83 frame. Such a window can be @dfn{deleted}, i.e. removed from the
84 frame (@pxref{Deleting Windows}); then it is no longer live, but the
85 Lisp object representing it might be still referenced from other Lisp
86 objects. A deleted window may be brought back to life by restoring a
87 saved window configuration (@pxref{Window Configurations}).
90 This function returns @code{t} if @var{object} is a window (whether or
91 not it is live). Otherwise, it returns @code{nil}.
94 @defun window-live-p object
95 This function returns @code{t} if @var{object} is a live window and
96 @code{nil} otherwise. A live window is one that displays a buffer.
99 The windows in each frame are organized into a @dfn{window tree}.
100 @xref{Windows and Frames}. The leaf nodes of each window tree are
101 live windows---the ones actually displaying buffers. The internal
102 nodes of the window tree are internal windows, which are not live.
103 You can distinguish internal windows from deleted windows with
104 @code{window-valid-p}.
106 @defun window-valid-p object
107 This function returns @code{t} if @var{object} is a live window, or an
108 internal window in a window tree. Otherwise, it returns @code{nil},
109 including for the case where @var{object} is a deleted window.
112 @cindex selected window
113 In each frame, at any time, exactly one Emacs window is designated
114 as @dfn{selected within the frame}. For the selected frame, that
115 window is called the @dfn{selected window}---the one in which most
116 editing takes place, and in which the cursor for selected windows
117 appears (@pxref{Cursor Parameters}). The selected window's buffer is
118 usually also the current buffer, except when @code{set-buffer} has
119 been used (@pxref{Current Buffer}). As for non-selected frames, the
120 window selected within the frame becomes the selected window if the
121 frame is ever selected. @xref{Selecting Windows}.
123 @defun selected-window
124 This function returns the selected window (which is always a live
128 @node Windows and Frames
129 @section Windows and Frames
131 Each window belongs to exactly one frame (@pxref{Frames}).
133 @defun window-frame window
134 This function returns the frame that the window @var{window} belongs
135 to. If @var{window} is @code{nil}, it defaults to the selected
139 @defun window-list &optional frame minibuffer window
140 This function returns a list of live windows belonging to the frame
141 @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
144 The optional argument @var{minibuffer} specifies whether to include
145 the minibuffer window in the returned list. If @var{minibuffer} is
146 @code{t}, the minibuffer window is included. If @var{minibuffer} is
147 @code{nil} or omitted, the minibuffer window is included only if it is
148 active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the
149 minibuffer window is never included.
151 The optional argument @var{window}, if non-@code{nil}, should be a
152 live window on the specified frame; then @var{window} will be the
153 first element in the returned list. If @var{window} is omitted or
154 @code{nil}, the window selected within the frame is first element.
159 Windows in the same frame are organized into a @dfn{window tree},
160 whose leaf nodes are the live windows. The internal nodes of a window
161 tree are not live; they exist for the purpose of organizing the
162 relationships between live windows. The root node of a window tree is
163 called the @dfn{root window}. It can be either a live window (if the
164 frame has just one window), or an internal window.
166 A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
167 frame's window tree unless the frame is a minibuffer-only frame.
168 Nonetheless, most of the functions in this section accept the
169 minibuffer window as an argument. Also, the function
170 @code{window-tree} described at the end of this section lists the
171 minibuffer window alongside the actual window tree.
173 @defun frame-root-window &optional frame-or-window
174 This function returns the root window for @var{frame-or-window}. The
175 argument @var{frame-or-window} should be either a window or a frame;
176 if omitted or @code{nil}, it defaults to the selected frame. If
177 @var{frame-or-window} is a window, the return value is the root window
178 of that window's frame.
181 @cindex parent window
183 @cindex sibling window
184 When a window is split, there are two live windows where previously
185 there was one. One of these is represented by the same Lisp window
186 object as the original window, and the other is represented by a
187 newly-created Lisp window object. Both of these live windows become
188 leaf nodes of the window tree, as @dfn{child windows} of a single
189 internal window. If necessary, Emacs automatically creates this
190 internal window, which is also called the @dfn{parent window}, and
191 assigns it to the appropriate position in the window tree. A set of
192 windows that share the same parent are called @dfn{siblings}.
194 @cindex parent window
195 @defun window-parent &optional window
196 This function returns the parent window of @var{window}. If
197 @var{window} is omitted or @code{nil}, it defaults to the selected
198 window. The return value is @code{nil} if @var{window} has no parent
199 (i.e. it is a minibuffer window or the root window of its frame).
202 Each internal window always has at least two child windows. If this
203 number falls to one as a result of window deletion, Emacs
204 automatically deletes the internal window, and its sole remaining
205 child window takes its place in the window tree.
207 Each child window can be either a live window, or an internal window
208 (which in turn would have its own child windows). Therefore, each
209 internal window can be thought of as occupying a certain rectangular
210 @dfn{screen area}---the union of the areas occupied by the live
211 windows that are ultimately descended from it.
213 @cindex window combination
214 @cindex vertical combination
215 @cindex horizontal combination
216 For each internal window, the screen areas of the immediate children
217 are arranged either vertically or horizontally (never both). If the
218 child windows are arranged one above the other, they are said to form
219 a @dfn{vertical combination}; if they are arranged side by side, they
220 are said to form a @dfn{horizontal combination}. Consider the
225 ______________________________________
226 | ______ ____________________________ |
227 || || __________________________ ||
231 || |||____________W4____________|||
232 || || __________________________ ||
235 || |||____________W5____________|||
236 ||__W2__||_____________W3_____________ |
237 |__________________W1__________________|
243 The root window of this frame is an internal window, @code{W1}. Its
244 child windows form a horizontal combination, consisting of the live
245 window @code{W2} and the internal window @code{W3}. The child windows
246 of @code{W3} form a vertical combination, consisting of the live
247 windows @code{W4} and @code{W5}. Hence, the live windows in this
248 window tree are @code{W2} @code{W4}, and @code{W5}.
250 The following functions can be used to retrieve a child window of an
251 internal window, and the siblings of a child window.
253 @defun window-top-child window
254 This function returns the topmost child window of @var{window}, if
255 @var{window} is an internal window whose children form a vertical
256 combination. For any other type of window, the return value is
260 @defun window-left-child window
261 This function returns the leftmost child window of @var{window}, if
262 @var{window} is an internal window whose children form a horizontal
263 combination. For any other type of window, the return value is
267 @defun window-child window
268 This function returns the first child window of the internal window
269 @var{window}---the topmost child window for a vertical combination, or
270 the leftmost child window for a horizontal combination. If
271 @var{window} is a live window, the return value is @code{nil}.
274 @defun window-combined-p &optional window horizontal
275 This function returns a non-@code{nil} value if and only if
276 @var{window} is part of a vertical combination. If @var{window} is
277 omitted or @code{nil}, it defaults to the selected one.
279 If the optional argument @var{horizontal} is non-@code{nil}, this
280 means to return non-@code{nil} if and only if @var{window} is part of
281 a horizontal combination.
284 @defun window-next-sibling &optional window
285 This function returns the next sibling of the window @var{window}. If
286 omitted or @code{nil}, @var{window} defaults to the selected window.
287 The return value is @code{nil} if @var{window} is the last child of
291 @defun window-prev-sibling &optional window
292 This function returns the previous sibling of the window @var{window}.
293 If omitted or @code{nil}, @var{window} defaults to the selected
294 window. The return value is @code{nil} if @var{window} is the first
298 The functions @code{window-next-sibling} and
299 @code{window-prev-sibling} should not be confused with the functions
300 @code{next-window} and @code{previous-window} which respectively
301 return the next and previous window in the cyclic ordering of windows
302 (@pxref{Cyclic Window Ordering}).
304 You can use the following functions to find the first live window on
305 a frame, and to retrieve the entire window tree of a frame:
307 @defun frame-first-window &optional frame-or-window
308 This function returns the live window at the upper left corner of the
309 frame specified by @var{frame-or-window}. The argument
310 @var{frame-or-window} must denote a window or a live frame and defaults
311 to the selected frame. If @var{frame-or-window} specifies a window,
312 this function returns the first window on that window's frame. Under
313 the assumption that the frame from our canonical example is selected
314 @code{(frame-first-window)} returns @code{W2}.
317 @defun window-tree &optional frame
318 This function returns a list representing the window tree for frame
319 @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
322 The return value is a list of the form @code{(@var{root} @var{mini})},
323 where @var{root} represents the window tree of the frame's root
324 window, and @var{mini} is the frame's minibuffer window.
326 If the root window is live, @var{root} is that window itself.
327 Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
328 @var{w2} ...)} where @var{dir} is @code{nil} for a horizontal
329 combination and @code{t} for a vertical combination, @var{edges} gives
330 the size and position of the combination, and the remaining elements
331 are the child windows. Each child window may again be a window object
332 (for a live window) or a list with the same format as above (for an
333 internal window). The @var{edges} element is a list @code{(@var{left}
334 @var{top} @var{right} @var{bottom})}, similar to the value returned by
335 @code{window-edges} (@pxref{Coordinates and Windows}).
339 @section Window Sizes
341 @cindex size of window
343 The following schematic shows the structure of a live window:
347 _________________________________________
348 ^ |______________ Header Line_______________|
349 | |LS|LF|LM| |RM|RF|RS| ^
351 Window | | | | Text Area | | | | Window
352 Total | | | | (Window Body) | | | | Body
353 Height | | | | | | | | Height
354 | | | | |<- Window Body Width ->| | | | |
355 | |__|__|__|_______________________|__|__|__| v
356 v |_______________ Mode Line _______________|
358 <----------- Window Total Width -------->
364 @cindex text area of a window
365 @cindex body of a window
366 At the center of the window is the @dfn{text area}, or @dfn{body},
367 where the buffer text is displayed. On each side of the text area is
368 a series of vertical areas; from innermost to outermost, these are the
369 left and right margins, denoted by LM and RM in the schematic
370 (@pxref{Display Margins}); the left and right fringes, denoted by LF
371 and RF (@pxref{Fringes}); and the left or right scroll bar, only one of
372 which is present at any time, denoted by LS and RS (@pxref{Scroll
373 Bars}). At the top of the window is an optional header line
374 (@pxref{Header Lines}), and at the bottom of the window is the mode
375 line (@pxref{Mode Line Format}).
377 Emacs provides several functions for finding the height and width of
378 a window. Except where noted, these heights and widths are reported
379 as integer numbers of lines and columns respectively. On a graphical
380 display, each ``line'' and ``column'' actually corresponds to the
381 height and width of a ``default'' character specified by the frame's
382 default font. Thus, if a window is displaying text with a different
383 font or size, the reported height and width for that window may differ
384 from the actual number of text lines or columns displayed within it.
386 @cindex window height
387 @cindex height of a window
388 @cindex total height of a window
390 @cindex width of a window
391 @cindex total width of a window
392 The @dfn{total height} of a window is the distance between the top
393 and bottom of the window, including the header line (if one exists)
394 and the mode line. The @dfn{total width} of a window is the distance
395 between the left and right edges of the mode line. Note that the
396 height of a frame is not the same as the height of its windows, since
397 a frame may also contain an echo area, menu bar, and tool bar
398 (@pxref{Size and Position}).
400 @defun window-total-height &optional window
401 This function returns the total height, in lines, of the window
402 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
403 to the selected window. If @var{window} is an internal window, the
404 return value is the total height occupied by its descendant windows.
407 @defun window-total-width &optional window
408 This function returns the total width, in columns, of the window
409 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
410 to the selected window. If @var{window} is internal, the return value
411 is the total width occupied by its descendant windows.
414 @defun window-total-size &optional window horizontal
415 This function returns either the total height or width of the window
416 @var{window}. If @var{horizontal} is omitted or @code{nil}, this is
417 equivalent to calling @code{window-total-height} for @var{window};
418 otherwise it is equivalent to calling @code{window-total-width} for
422 @cindex full-width window
423 @cindex full-height window
424 The following functions can be used to determine whether a given
425 window has any adjacent windows.
427 @defun window-full-height-p &optional window
428 This function returns non-@code{nil} if @var{window} has no other
429 window above or below it in its frame, i.e. its total height equals
430 the total height of the root window on that frame. If @var{window} is
431 omitted or @code{nil}, it defaults to the selected window.
434 @defun window-full-width-p &optional window
435 This function returns non-@code{nil} if @var{window} has no other
436 window to the left or right in its frame, i.e. its total width equals
437 that of the root window on that frame. If @var{window} is omitted or
438 @code{nil}, it defaults to the selected window.
441 @cindex window position
442 The following functions can be used to determine the position of a
443 window relative to the window area of its frame:
445 @defun window-top-line &optional window
446 This function returns the distance, in lines, between the top of
447 @var{window} and the top of the frame's window area. For instance,
448 the return value is 0 if there is no window above @var{window}. If
449 @var{window} is omitted or @code{nil}, it defaults to the selected
453 @defun window-left-column &optional window
454 This function returns the distance, in columns, between the left edge
455 of @var{window} and the left edge of the frame's window area. For
456 instance, the return value is 0 if there is no window to the left of
457 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
458 to the selected window.
461 @cindex window body height
462 @cindex body height of a window
463 @cindex window body width
464 @cindex body width of a window
465 @cindex body size of a window
466 @cindex window body size
467 The @dfn{body height} of a window is the height of its text area,
468 which does not include the mode or header line. Similarly, the
469 @dfn{body width} is the width of the text area, which does not include
470 the scroll bar, fringes, or margins.
472 @defun window-body-height &optional window
473 This function returns the body height, in lines, of the window
474 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
475 to the selected window; otherwise it must be a live window.
477 If there is a partially-visible line at the bottom of the text area,
478 that counts as a whole line; to exclude such a partially-visible line,
479 use @code{window-text-height}, below.
482 @defun window-body-width &optional window
483 This function returns the body width, in columns, of the window
484 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
485 to the selected window; otherwise it must be a live window.
488 @defun window-body-size &optional window horizontal
489 This function returns the body height or body width of @var{window}.
490 If @var{horizontal} is omitted or @code{nil}, it is equivalent to
491 calling @code{window-body-height} for @var{window}; otherwise it is
492 equivalent to calling @code{window-body-width}.
495 @defun window-text-height &optional window
496 This function is like @code{window-body-height}, except that any
497 partially-visible line at the bottom of the text area is not counted.
500 For compatibility with previous versions of Emacs,
501 @code{window-height} is an alias for @code{window-body-height}, and
502 @code{window-width} is an alias for @code{window-body-width}. These
503 aliases are considered obsolete and will be removed in the future.
505 @cindex fixed-size window
506 Commands that change the size of windows (@pxref{Resizing Windows}),
507 or split them (@pxref{Splitting Windows}), obey the variables
508 @code{window-min-height} and @code{window-min-width}, which specify
509 the smallest allowable window height and width. @xref{Change
510 Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
511 Manual}. They also obey the variable @code{window-size-fixed}, with
512 which a window can be @dfn{fixed} in size:
514 @defvar window-size-fixed
515 If this buffer-local variable is non-@code{nil}, the size of any
516 window displaying the buffer cannot normally be changed. Deleting a
517 window or changing the frame's size may still change its size, if
520 If the value is @code{height}, then only the window's height is fixed;
521 if the value is @code{width}, then only the window's width is fixed.
522 Any other non-@code{nil} value fixes both the width and the height.
525 @defun window-size-fixed-p &optional window horizontal
526 This function returns a non-@code{nil} value if @var{window}'s height
527 is fixed. If @var{window} is omitted or @code{nil}, it defaults to
528 the selected window. If the optional argument @var{horizontal} is
529 non-@code{nil}, the return value is non-@code{nil} if @var{window}'s
532 A @code{nil} return value does not necessarily mean that @var{window}
533 can be resized in the desired direction. To determine that, use the
534 function @code{window-resizable}. @xref{Resizing Windows}.
537 The following functions can be used to find a window's size and
538 position in pixels. Though mostly useful on graphical displays, they
539 can also be called on text-only terminals, where the screen area of
540 each text character is taken to be ``one pixel''.
542 @defun window-pixel-edges &optional window
543 This function return a list of pixel coordinates for the edges of
544 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
545 to the selected window.
547 The return value has the form @code{(@var{left} @var{top} @var{right}
548 @var{bottom})}. The list elements are, respectively, the X coordinate
549 of the left window edge, the Y coordinate of the top edge, one more
550 than the X coordinate of the right edge, and one more than the Y
551 coordinate of the bottom edge. The origin coordinate @samp{(0,0)} is
552 taken to be the top left corner of the frame's window area.
554 These edge values include the space used by the window's scroll bar,
555 margins, fringes, header line, and mode line, if any.
558 @defun window-inside-pixel-edges &optional window
559 This function is like @code{window-pixel-edges}, except that it
560 returns the edge coordinates for the window's text area, rather than
561 the edge coordinates for the window itself. @var{window} must specify
565 @defun window-absolute-pixel-edges &optional window
566 This function is like @code{window-pixel-edges}, except that it
567 returns the edge coordinates relative to the top left corner of the
571 @defun window-inside-absolute-pixel-edges &optional window
572 This function is like @code{window-inside-pixel-edges}, except that it
573 returns the edge coordinates relative to the top left corner of the
574 display screen. @var{window} must specify a live window.
577 @node Resizing Windows
578 @section Resizing Windows
579 @cindex window resizing
580 @cindex resize window
581 @cindex changing window size
582 @cindex window size, changing
584 This section describes functions for resizing a window without
585 changing the size of its frame. Because live windows do not overlap,
586 these functions are meaningful only on frames that contain two or more
587 windows: resizing a window also changes the size of a neighboring
588 window. If there is just one window on a frame, its size cannot be
589 changed except by resizing the frame (@pxref{Size and Position}).
591 Except where noted, these functions also accept internal windows as
592 arguments. Resizing an internal window causes its child windows to be
593 resized to fit the same space.
595 @defun window-resizable window delta &optional horizontal ignore
596 This function returns @var{delta} if the size of @var{window} can be
597 changed vertically by @var{delta} lines. If the optional argument
598 @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
599 @var{window} can be resized horizontally by @var{delta} columns. It
600 does not actually change the window size.
602 If @var{window} is @code{nil}, it defaults to the selected window.
604 A positive value of @var{delta} means to check whether the window can be
605 enlarged by that number of lines or columns; a negative value of
606 @var{delta} means to check whether the window can be shrunk by that many
607 lines or columns. If @var{delta} is non-zero, a return value of 0 means
608 that the window cannot be resized.
610 Normally, the variables @code{window-min-height} and
611 @code{window-min-width} specify the smallest allowable window size.
612 @xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU
613 Emacs Manual}. However, if the optional argument @var{ignore} is
614 non-@code{nil}, this function ignores @code{window-min-height} and
615 @code{window-min-width}, as well as @code{window-size-fixed}.
616 Instead, it considers the minimum-height window to be one consisting
617 of a header (if any), a mode line, plus a text area one line tall; and
618 a minimum-width window as one consisting of fringes, margins, and
619 scroll bar (if any), plus a text area two columns wide.
622 @defun window-resize window delta &optional horizontal ignore
623 This function resizes @var{window} by @var{delta} increments. If
624 @var{horizontal} is @code{nil}, it changes the height by @var{delta}
625 lines; otherwise, it changes the width by @var{delta} columns. A
626 positive @var{delta} means to enlarge the window, and a negative
627 @var{delta} means to shrink it.
629 If @var{window} is @code{nil}, it defaults to the selected window. If
630 the window cannot be resized as demanded, an error is signaled.
632 The optional argument @var{ignore} has the same meaning as for the
633 function @code{window-resizable} above.
635 The choice of which window edge this function alters depends on the
636 splitting and nesting status of the involved windows; in some cases,
637 it may alter both edges. @xref{Splitting Windows}. To resize by
638 moving only the bottom or right edge of a window, use the function
639 @code{adjust-window-trailing-edge}, below.
642 @c The commands enlarge-window, enlarge-window-horizontally,
643 @c shrink-window, and shrink-window-horizontally are documented in the
644 @c Emacs manual. They are not preferred for calling from Lisp.
646 @defun adjust-window-trailing-edge window delta &optional horizontal
647 This function moves @var{window}'s bottom edge by @var{delta} lines.
648 If optional argument @var{horizontal} is non-@code{nil}, it instead
649 moves the right edge by @var{delta} columns. If @var{window} is
650 @code{nil}, it defaults to the selected window.
652 A positive @var{delta} moves the edge downwards or to the right; a
653 negative @var{delta} moves it upwards or to the left. If the edge
654 cannot be moved as far as specified by @var{delta}, this function
655 moves it as far as possible but does not signal a error.
657 This function tries to resize windows adjacent to the edge that is
658 moved. If this is not possible for some reason (e.g. if that adjacent
659 window is fixed-size), it may resize other windows.
662 The following commands resize windows in more specific ways. When
663 called interactively, they act on the selected window.
665 @deffn Command fit-window-to-buffer &optional window max-height min-height override
666 This command adjusts the height of @var{window} to fit the text in it.
667 It returns non-@code{nil} if it was able to resize @var{window}, and
668 @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
669 defaults to the selected window. Otherwise, it should be a live
672 The optional argument @var{max-height}, if non-@code{nil}, specifies
673 the maximum total height that this function can give @var{window}.
674 The optional argument @var{min-height}, if no-@code{nil}, specifies
675 the minimum total height that it can give, which overrides the
676 variable @code{window-min-height}.
678 If the optional argument @var{override} is non-@code{nil}, this
679 function ignores any size restrictions imposed by
680 @code{window-min-height} and @code{window-min-width}.
683 @deffn Command shrink-window-if-larger-than-buffer &optional window
684 This command attempts to reduce @var{window}'s height as much as
685 possible while still showing its full buffer, but no less than
686 @code{window-min-height} lines. The return value is non-@code{nil} if
687 the window was resized, and @code{nil} otherwise. If @var{window} is
688 omitted or @code{nil}, it defaults to the selected window. Otherwise,
689 it should be a live window.
691 This command does nothing if the window is already too short to
692 display all of its buffer, or if any of the buffer is scrolled
693 off-screen, or if the window is the only live window in its frame.
696 @cindex balancing window sizes
697 @deffn Command balance-windows &optional window-or-frame
698 This function balances windows in a way that gives more space to
699 full-width and/or full-height windows. If @var{window-or-frame}
700 specifies a frame, it balances all windows on that frame. If
701 @var{window-or-frame} specifies a window, it balances only that window
702 and its siblings (@pxref{Windows and Frames}).
705 @deffn Command balance-windows-area
706 This function attempts to give all windows on the selected frame
707 approximately the same share of the screen area. Full-width or
708 full-height windows are not given more space than other windows.
711 @cindex maximizing windows
712 @deffn Command maximize-window &optional window
713 This function attempts to make @var{window} as large as possible, in
714 both dimensions, without resizing its frame or deleting other windows.
715 If @var{window} is omitted or @code{nil}, it defaults to the selected
719 @cindex minimizing windows
720 @deffn Command minimize-window &optional window
721 This function attempts to make @var{window} as small as possible, in
722 both dimensions, without deleting it or resizing its frame. If
723 @var{window} is omitted or @code{nil}, it defaults to the selected
728 @node Splitting Windows
729 @section Splitting Windows
730 @cindex splitting windows
731 @cindex window splitting
733 This section describes functions for creating a new window by
734 @dfn{splitting} an existing one.
736 @deffn Command split-window &optional window size side
737 This function creates a new live window next to the window
738 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
739 to the selected window. That window is ``split'', and reduced in
740 size. The space is taken up by the new window, which is returned.
742 The optional second argument @var{size} determines the sizes of
743 @var{window} and/or the new window. If it is omitted or @code{nil},
744 both windows are given equal sizes; if there is an odd line, it is
745 allocated to the new window. If @var{size} is a positive number,
746 @var{window} is given @var{size} lines (or columns, depending on the
747 value of @var{side}). If @var{size} is a negative number, the new
748 window is given @minus{}@var{size} lines (or columns).
750 If @var{size} is @code{nil}, this function obeys the variables
751 @code{window-min-height} and @code{window-min-width}. @xref{Change
752 Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
753 Manual}. Thus, it signals an error if splitting would result in
754 making a window smaller than those variables specify. However, a
755 non-@code{nil} value for @var{size} causes those variables to be
756 ignored; in that case, the smallest allowable window is considered to
757 be one that has space for a text area one line tall and/or two columns
760 The optional third argument @var{side} determines the position of the
761 new window relative to @var{window}. If it is @code{nil} or
762 @code{below}, the new window is placed below @var{window}. If it is
763 @code{above}, the new window is placed above @var{window}. In both
764 these cases, @var{size} specifies a total window height, in lines.
766 If @var{side} is @code{t} or @code{right}, the new window is placed on
767 the right of @var{window}. If @var{side} is @code{left}, the new
768 window is placed on the left of @var{window}. In both these cases,
769 @var{size} specifies a total window width, in columns.
771 If @var{window} is a live window, the new window inherits various
772 properties from it, including margins and scroll bars. If
773 @var{window} is an internal window, the new window inherits the
774 properties of the window selected within @var{window}'s frame.
776 If the variable @code{ignore-window-parameters} is non-@code{nil}
777 (@pxref{Window Parameters}), this function ignores window parameters.
778 Otherwise, it consults the @code{split-window} parameter of
779 @var{window}; if this is @code{t}, it splits the window disregarding
780 any other window parameters. If the @code{split-window} parameter
781 specifies a function, that function is called with the arguments
782 @var{window}, @var{size}, and @var{side} to split @var{window}, in
783 lieu of the usual action of @code{split-window}.
786 As an example, we show a combination of @code{split-window} calls
787 that yields the window configuration discussed in @ref{Windows and
788 Frames}. This example demonstrates splitting a live window as well as
789 splitting an internal window. We begin with a frame containing a
790 single window (a live root window), which we denote by @var{W4}.
791 Calling @code{(split-window W3)} yields this window configuration:
795 ______________________________________
796 | ____________________________________ |
800 ||_________________W4_________________||
801 | ____________________________________ |
805 ||_________________W5_________________||
806 |__________________W3__________________|
812 The @code{split-window} call has created a new live window, denoted by
813 @var{W5}. It has also created a new internal window, denoted by
814 @var{W3}, which becomes the root window and the parent of both
815 @var{W4} and @var{W5}.
817 Next, we call @code{(split-window W3 nil 'left)}, passing the
818 internal window @var{W3} as the argument. The result:
822 ______________________________________
823 | ______ ____________________________ |
824 || || __________________________ ||
828 || |||____________W4____________|||
829 || || __________________________ ||
832 || |||____________W5____________|||
833 ||__W2__||_____________W3_____________ |
834 |__________________W1__________________|
839 A new live window @var{W2} is created, to the left of the internal
840 window @var{W3}. A new internal window @var{W1} is created, becoming
843 The following two options can be used to modify the operation of
846 @defopt window-splits
847 If this variable is @code{nil}, @code{split-window} can only split a
848 window (denoted by @var{window}) if @var{window}'s screen area is
849 large enough to accommodate both itself and the new window. This is
852 If this variable is non-@code{nil}, @code{split-window} tries to
853 resize all windows that are part of the same combination as
854 @var{window}, in order to accommodate the new window. In particular,
855 this may allow @code{split-window} to succeed even if @var{window} is
856 a fixed-size window or too small to ordinarily split.
858 Also if this variable is non-@code{nil}, subsequent resizing and
859 deleting @var{window} will usually affect @emph{all} windows in
860 @var{window}'s combination.
862 The setting of this variable has no effect if @code{window-nest} (see
863 below) is non-@code{nil}.
866 To illustrate the use of @code{window-splits} consider the following
867 window configuration:
870 ______________________________________
871 | ____________________________________ |
876 ||_________________W2_________________||
877 | ____________________________________ |
882 ||_________________W3_________________||
883 |__________________W1__________________|
888 Splitting window @code{W3} with @code{window-splits} @code{nil}
889 produces a configuration where the size of @code{W2} remains unchanged:
892 ______________________________________
893 | ____________________________________ |
898 ||_________________W2_________________||
899 | ____________________________________ |
901 ||_________________W3_________________||
902 | ____________________________________ |
904 ||_________________W4_________________||
905 |__________________W1__________________|
910 Splitting @code{W3} with @code{window-splits} non-@code{nil} instead
911 produces a configuration where all windows have approximately the same
916 ______________________________________
917 | ____________________________________ |
920 ||_________________W2_________________||
921 | ____________________________________ |
924 ||_________________W3_________________||
925 | ____________________________________ |
928 ||_________________W4_________________||
929 |__________________W1__________________|
935 If this variable is @code{nil}, @code{split-window} creates a new parent
936 window if and only if the old window has no parent window or shall be
937 split orthogonally to the combination it is part of. If this variable
938 is non-@code{nil}, @code{split-window} always creates a new parent
939 window. If this variable is always non-@code{nil}, a frame's window
940 tree is a binary tree so every window but the frame's root window has
943 The value of this variable is also assigned to the nest status of the
944 new parent window. The nest status of any window can be retrieved via
945 the function @code{window-nest} and altered by the function
946 @code{set-window-nest}, see below.
949 @defun window-nest &optional window
950 This function returns the nest status of @var{window}. The argument
951 @var{window} can be any window and defaults to the selected one. Note,
952 however, that the nest status is currently meaningful for internal
956 The @dfn{nest status} of a window specifies whether that window may be
957 removed and its child windows recombined with that window's siblings
958 when such a sibling's child window is deleted. The nest status is
959 initially assigned by @code{split-window} from the current value of the
960 variable @code{window-nest} (see above) and can be reset by the function
961 @code{set-window-nest} (see below).
963 If the return value is @code{nil}, child windows of @var{window} may be
964 recombined with @var{window}'s siblings when a window gets deleted. A
965 return value of @code{nil} means that child windows of @var{window} are
966 never (re-)combined with @var{window}'s siblings in such a case.
969 @defun set-window-nest window &optional status
970 This functions sets the nest status (see above) of @var{window} to
971 @var{status}. The argument @var{window} can be any window and defaults
972 to the selected one. Note that setting the nest status is meaningful
973 for internal windows only. The return value is @var{status}.
976 To illustrate the use of @code{window-nest} consider the following
977 configuration (throughout the following examples we shall assume that
978 @code{window-splits} invariantly is @code{nil}).
981 ______________________________________
982 | ____________________________________ |
989 ||_________________W2_________________||
990 | ____________________________________ |
993 ||_________________W3_________________||
994 |__________________W1__________________|
999 Splitting @code{W2} into two windows above each other with
1000 @code{window-nest} equal @code{nil} will get you a configuration like:
1003 ______________________________________
1004 | ____________________________________ |
1007 ||_________________W2_________________||
1008 | ____________________________________ |
1011 ||_________________W4_________________||
1012 | ____________________________________ |
1015 ||_________________W3_________________||
1016 |__________________W1__________________|
1021 If you now enlarge window @code{W4}, Emacs steals the necessary space
1022 from window @code{W3} resulting in a configuration like:
1025 ______________________________________
1026 | ____________________________________ |
1029 ||_________________W2_________________||
1030 | ____________________________________ |
1034 ||_________________W4_________________||
1035 | ____________________________________ |
1037 ||_________________W3_________________||
1038 |__________________W1__________________|
1043 Deleting window @code{W4}, will return its space to @code{W2} as
1047 ______________________________________
1048 | ____________________________________ |
1056 ||_________________W2_________________||
1057 | ____________________________________ |
1059 ||_________________W3_________________||
1060 |__________________W1__________________|
1065 Hence, with respect to the initial configuration, window @code{W2} has
1066 grown at the expense of window @code{W3}. If, however, in the initial
1067 configuration you had split @code{W2} with @code{window-nest} bound to
1068 @code{t}, a new internal window @code{W5} would have been created as
1072 ______________________________________
1073 | ____________________________________ |
1074 || __________________________________ ||
1076 |||________________W2________________|||
1077 || __________________________________ ||
1079 |||________________W4________________|||
1080 ||_________________W5_________________||
1081 | ____________________________________ |
1084 ||_________________W3_________________||
1085 |__________________W1__________________|
1090 Enlarging @code{W4} would now have stolen the necessary space from
1091 @code{W2} instead of @code{W3} as
1094 ______________________________________
1095 | ____________________________________ |
1096 || __________________________________ ||
1097 |||________________W2________________|||
1098 || __________________________________ ||
1101 |||________________W4________________|||
1102 ||_________________W5_________________||
1103 | ____________________________________ |
1106 ||_________________W3_________________||
1107 |__________________W1__________________|
1112 and the subsequent deletion of @code{W4} would have restored the initial
1115 For interactive use, Emacs provides two commands which always split the
1118 @deffn Command split-window-below &optional size
1119 This function splits the selected window into two windows, one above the
1120 other, leaving the upper of the two windows selected, with @var{size}
1121 lines. (If @var{size} is negative, then the lower of the two windows
1122 gets @minus{}@var{size} lines and the upper window gets the rest, but
1123 the upper window is still the one selected.) However, if
1124 @code{split-window-keep-point} (see below) is @code{nil}, then either
1125 window can be selected.
1127 In other respects, this function is similar to @code{split-window}.
1128 In particular, the upper window is the original one and the return value
1129 is the new, lower window.
1132 @defopt split-window-keep-point
1133 If this variable is non-@code{nil} (the default), then
1134 @code{split-window-below} behaves as described above.
1136 If it is @code{nil}, then @code{split-window-below} adjusts point
1137 in each of the two windows to avoid scrolling. (This is useful on
1138 slow terminals.) It selects whichever window contains the screen line
1139 that point was previously on. Other functions are not affected by
1143 @deffn Command split-window-right &optional size
1144 This function splits the selected window into two windows
1145 side-by-side, leaving the selected window on the left with @var{size}
1146 columns. If @var{size} is negative, the rightmost window gets
1147 @minus{}@var{size} columns, but the leftmost window still remains
1152 @node Deleting Windows
1153 @section Deleting Windows
1154 @cindex deleting windows
1156 A window remains visible on its frame unless you @dfn{delete} it by
1157 calling certain functions that delete windows. A deleted window cannot
1158 appear on the screen, but continues to exist as a Lisp object until
1159 there are no references to it. There is no way to cancel the deletion
1160 of a window aside from restoring a saved window configuration
1161 (@pxref{Window Configurations}). Restoring a window configuration also
1162 deletes any windows that aren't part of that configuration. Erroneous
1163 information may result from using a deleted window as if it were live.
1165 @deffn Command delete-window &optional window
1166 This function removes @var{window} from display and returns @code{nil}.
1167 The argument @var{window} can denote any window and defaults to the
1168 selected one. An error is signaled if @var{window} is the only window
1169 on its frame. Hence @var{window} must have at least one sibling window
1170 (@pxref{Windows and Frames}) in order to get deleted. If @var{window}
1171 is the selected window on its frame, this function selects the most
1172 recently selected live window on that frame instead.
1174 If the variable @code{ignore-window-parameters} (@pxref{Window
1175 Parameters}) is non-@code{nil}, this function ignores all parameters of
1176 @var{window}. Otherwise, if the @code{delete-window} parameter of
1177 @var{window} is @code{t}, it deletes the window disregarding other
1178 window parameters. If the @code{delete-window} parameter specifies a
1179 function, that function is called with @var{window} as its sole
1182 If @code{window-splits} (@pxref{Splitting Windows}) is @code{nil}, the
1183 space @var{window} took up is given to its left sibling if such a window
1184 exists and to its right sibling otherwise. If @code{window-splits} is
1185 non-@code{nil}, the space of @var{window} is proportionally distributed
1186 among the remaining windows in the same combination.
1189 @deffn Command delete-other-windows &optional window
1190 This function makes @var{window} fill its frame and returns @code{nil}.
1191 The argument @var{window} can denote an arbitrary window and defaults to
1192 the selected one. Upon exit, @var{window} will be the selected window
1195 If the variable @code{ignore-window-parameters} (@pxref{Window
1196 Parameters}) is non-@code{nil}, this function ignores all parameters of
1197 @var{window}. Otherwise, if the @code{delete-other-windows} parameter
1198 of @var{window} equals @code{t}, it deletes all other windows
1199 disregarding any remaining window parameters. If the
1200 @code{delete-other-windows} parameter of @var{window} specifies a
1201 function, it calls that function with @var{window} as its sole argument.
1204 @deffn Command delete-windows-on &optional buffer-or-name frame
1205 This function deletes all windows showing @var{buffer-or-name}. If
1206 there are no windows showing @var{buffer-or-name}, it does nothing.
1207 The optional argument @var{buffer-or-name} may be a buffer or the name
1208 of an existing buffer and defaults to the current buffer. Invoking
1209 this command on a minibuffer signals an error.
1211 The function @code{delete-windows-on} operates by calling
1212 @code{delete-window} for each window showing @var{buffer-or-name}. If a
1213 frame has several windows showing different buffers, then those showing
1214 @var{buffer-or-name} are removed, and the other windows expand to fill
1217 If all windows in some frame are showing @var{buffer-or-name} (including
1218 the case where there is only one window), then that frame is deleted
1219 provided there are other frames left.
1221 The optional argument @var{frame} specifies which frames to operate on.
1222 This function does not use it in quite the same way as the other
1223 functions which scan all live windows (@pxref{Cyclic Window Ordering});
1224 specifically, the values @code{t} and @code{nil} have the opposite of
1225 their meanings in the other functions. Here are the full details:
1229 means operate on all frames.
1231 means operate on the selected frame.
1232 @item @code{visible}
1233 means operate on all visible frames.
1235 means operate on all visible or iconified frames.
1237 means operate on that frame.
1242 @node Selecting Windows
1243 @section Selecting Windows
1244 @cindex selecting a window
1246 @defun select-window window &optional norecord
1247 This function makes @var{window} the selected window, see @ref{Basic
1248 Windows}. Unless @var{window} already is the selected window, this also
1249 makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current
1250 buffer. Moreover, the cursor for selected windows will be displayed in
1251 @var{window} after the next redisplay. This function returns
1254 Normally, @var{window}'s selected buffer is moved to the front of the
1255 buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
1256 recently selected window. But if the optional argument @var{norecord}
1257 is non-@code{nil}, the buffer list remains unchanged and @var{window}
1258 does not become the most recently selected one.
1261 @cindex most recently selected windows
1262 The sequence of calls to @code{select-window} with a non-@code{nil}
1263 @var{norecord} argument determines an ordering of windows by their
1264 selection time. The function @code{get-lru-window} can be used to
1265 retrieve the least recently selected live window in this ordering, see
1266 @ref{Cyclic Window Ordering}.
1268 @defmac save-selected-window forms@dots{}
1269 This macro records the selected frame, as well as the selected window
1270 of each frame, executes @var{forms} in sequence, then restores the
1271 earlier selected frame and windows. It also saves and restores the
1272 current buffer. It returns the value of the last form in @var{forms}.
1274 This macro does not save or restore anything about the sizes,
1275 arrangement or contents of windows; therefore, if @var{forms} change
1276 them, the change persists. If the previously selected window of some
1277 frame is no longer live at the time of exit from @var{forms}, that
1278 frame's selected window is left alone. If the previously selected
1279 window is no longer live, then whatever window is selected at the end of
1280 @var{forms} remains selected. The current buffer is restored if and
1281 only if it is still live when exiting @var{forms}.
1283 This macro changes neither the ordering of recently selected windows nor
1287 @defmac with-selected-window window forms@dots{}
1288 This macro selects @var{window}, executes @var{forms} in sequence, then
1289 restores the previously selected window and current buffer. The ordering
1290 of recently selected windows and the buffer list remain unchanged unless
1291 you deliberately change them within @var{forms}, for example, by calling
1292 @code{select-window} with argument @var{norecord} @code{nil}.
1294 The order of recently selected windows and the buffer list are not
1295 changed by this macro.
1298 @cindex frame selected window
1299 @cindex window selected within frame
1300 Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly
1301 one window on any frame is selected within the frame. The significance
1302 of this designation is that selecting the frame also selects this
1303 window. Conversely, selecting a window for Emacs with
1304 @code{select-window} also makes that window selected within its frame.
1306 @defun frame-selected-window &optional frame
1307 This function returns the window on @var{frame} that is selected within
1308 @var{frame}. The optional argument @var{frame} must denote a live frame
1309 and defaults to the selected one.
1312 @defun set-frame-selected-window frame window &optional norecord
1313 This function sets the selected window of frame @var{frame} to
1314 @var{window}. The argument @var{frame} must denote a live frame and
1315 defaults to the selected one. If @var{frame} is the selected frame,
1316 this also makes @var{window} the selected window. The argument
1317 @var{window} must denote a live window. This function returns
1320 Optional argument @var{norecord} non-@code{nil} means to neither change
1321 the list of most recently selected windows (@pxref{Selecting Windows})
1322 nor the buffer list (@pxref{The Buffer List}).
1326 @node Cyclic Window Ordering
1327 @section Cyclic Ordering of Windows
1328 @cindex cyclic ordering of windows
1329 @cindex ordering of windows, cyclic
1330 @cindex window ordering, cyclic
1332 When you use the command @kbd{C-x o} (@code{other-window}) to select
1333 some other window, it moves through live windows in a specific order.
1334 For any given configuration of windows, this order never varies. It is
1335 called the @dfn{cyclic ordering of windows}.
1337 For a particular frame, this ordering is determined by the window
1338 tree of that frame, see @ref{Windows and Frames}. More precisely, the
1339 ordering is obtained by a depth-first traversal of the frame's window
1340 tree supplemented, if requested, by the frame's minibuffer window.
1342 If there's just one live frame, the cyclic ordering is the ordering
1343 for that frame. Otherwise, the cyclic ordering is obtained by appending
1344 the orderings for individual frames in order of the list of all live
1345 frames, @ref{Finding All Frames}. In any case, the ordering is made
1346 ``cyclic'' by having the last window precede the first window in the
1349 @defun next-window &optional window minibuf all-frames
1350 @cindex minibuffer window, and @code{next-window}
1351 This function returns the window following @var{window} in the cyclic
1352 ordering of windows. The argument @var{window} must specify a live
1353 window and defaults to the selected one.
1355 The optional argument @var{minibuf} specifies whether minibuffer windows
1356 shall be included in the cyclic ordering. Normally, when @var{minibuf}
1357 is @code{nil}, a minibuffer window is included only if it is currently
1358 ``active''; this matches the behavior of @kbd{C-x o}. (Note that a
1359 minibuffer window is active as long as its minibuffer is in use; see
1362 If @var{minibuf} is @code{t}, the cyclic ordering includes all
1363 minibuffer windows. If @var{minibuf} is neither @code{t} nor
1364 @code{nil}, minibuffer windows are not included even if they are active.
1366 The optional argument @var{all-frames} specifies which frames to
1367 consider. Here are the possible values and their meanings:
1371 means consider all windows on @var{window}'s frame, plus the minibuffer
1372 window used by that frame even if it lies in some other frame. If the
1373 minibuffer counts (as determined by @var{minibuf}), then all windows on
1374 all frames that share that minibuffer count too.
1377 means consider all windows on all existing frames.
1379 @item @code{visible}
1380 means consider all windows on all visible frames. (To get useful
1381 results, ensure that @var{window} is on a visible frame.)
1384 means consider all windows on all visible or iconified frames.
1387 means consider all windows on that frame.
1390 means consider the windows on @var{window}'s frame, and no others.
1393 This example assumes there are two windows, both displaying the
1394 buffer @samp{windows.texi}:
1399 @result{} #<window 56 on windows.texi>
1402 (next-window (selected-window))
1403 @result{} #<window 52 on windows.texi>
1406 (next-window (next-window (selected-window)))
1407 @result{} #<window 56 on windows.texi>
1412 @defun previous-window &optional window minibuf all-frames
1413 This function returns the window preceding @var{window} in the cyclic
1414 ordering of windows. The other arguments specify which windows to
1415 consider as in @code{next-window}.
1418 @deffn Command other-window count &optional all-frames
1419 This function selects another window in the cyclic ordering of windows.
1420 @var{count} specifies the number of windows to skip in the ordering,
1421 starting with the selected window, before making the selection. If
1422 @var{count} is a positive number, it skips @var{count} windows forwards.
1423 @var{count} negative means skip @minus{}@var{count} windows backwards.
1424 If @var{count} is zero, it does not skip any window, thus re-selecting
1425 the selected window. In an interactive call, @var{count} is the numeric
1428 The optional argument @var{all-frames} has the same meaning as in
1429 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
1430 is always effectively @code{nil}. This function returns @code{nil}.
1432 This function does not select a window that has a non-@code{nil}
1433 @code{no-other-window} window parameter (@pxref{Window Parameters}).
1436 The following function returns a copy of the list of windows in the
1439 @defun window-list-1 &optional window &optional minibuf &optional all_frames
1440 This function returns a list of live windows. The optional arguments
1441 @var{minibuf} and @var{all-frames} specify the set of windows to include
1442 in the list. See the description of @code{next-window} for details.
1444 The optional argument @var{window} specifies the first window to list
1445 and defaults to the selected window. If @var{window} is not on the list
1446 of windows returned, some other window will be listed first but no error
1450 The functions described below use @code{window-list-1} for generating a
1451 copy of the list of all relevant windows. Hence, any change of the
1452 window configuration that occurs while one of these functions is
1453 executed is @emph{not} reflected in the list of windows investigated.
1455 @defun walk-windows proc &optional minibuf all-frames
1456 This function cycles through live windows. It calls the function
1457 @var{proc} once for each window, with the window as its sole argument.
1459 The optional arguments @var{minibuf} and @var{all-frames} specify the
1460 set of windows to include in the walk, see @code{next-window} above. If
1461 @var{all-frames} specifies a frame, the first window walked is the first
1462 window on that frame as returned by @code{frame-first-window} and not
1463 necessarily the selected window.
1465 If @var{proc} changes the window configuration by splitting or deleting
1466 windows, that change is not reflected in the set of windows walked.
1467 That set is determined entirely by the set of live windows at the time
1468 this function was invoked.
1471 The following function allows to determine whether a specific window is
1472 the only live window.
1474 @defun one-window-p &optional no-mini all-frames
1475 This function returns non-@code{nil} if the selected window is the only
1478 The optional argument @var{no-mini}, if non-@code{nil}, means don't
1479 count the minibuffer even if it is active; otherwise, the minibuffer
1480 window is counted when it is active. The optional argument
1481 @var{all-frames} has the same meaning as for @code{next-window}, see
1485 @cindex finding windows
1486 The following functions choose (but do not select) one of the windows
1487 on the screen, offering various criteria for the choice.
1489 @cindex least recently used window
1490 @defun get-lru-window &optional all-frames dedicated
1491 This function returns the window least recently ``used'' (that is,
1492 selected). If any full-width windows are present, it only considers
1493 these. The optional argument @var{all-frames} has the same meaning as
1494 in @code{next-window}.
1496 The selected window is returned if it is the only candidate. A
1497 minibuffer window is never a candidate. A dedicated window
1498 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1499 argument @var{dedicated} is non-@code{nil}.
1502 @cindex largest window
1503 @defun get-largest-window &optional all-frames dedicated
1504 This function returns the window with the largest area (height times
1505 width). A minibuffer window is never a candidate. A dedicated window
1506 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1507 argument @var{dedicated} is non-@code{nil}.
1509 If there are two candidate windows of the same size, this function
1510 prefers the one that comes first in the cyclic ordering of windows,
1511 starting from the selected window.
1513 The optional argument @var{all-frames} specifies which set of windows to
1514 consider as with @code{next-window}, see above.
1517 @cindex window that satisfies a predicate
1518 @cindex conditional selection of windows
1519 @defun get-window-with-predicate predicate &optional minibuf all-frames default
1520 This function returns a window satisfying @var{predicate}. It cycles
1521 through all visible windows calling @var{predicate} on each one of them
1522 with that window as its argument. The function returns the first window
1523 for which @var{predicate} returns a non-@code{nil} value; if that never
1524 happens, it returns @var{default} (which defaults to @code{nil}).
1526 The optional arguments @var{minibuf} and @var{all-frames} specify the
1527 set of windows to investigate. See the description of
1528 @code{next-window} for details.
1531 @node Buffers and Windows
1532 @section Buffers and Windows
1533 @cindex examining windows
1534 @cindex windows, controlling precisely
1535 @cindex buffers, controlled in windows
1537 To find out which buffer is displayed in a given window the following
1540 @defun window-buffer &optional window
1541 This function returns the buffer that @var{window} is displaying. The
1542 argument @var{window} can be any window and defaults to the selected
1543 one. If @var{window} is an internal window, this function returns
1547 The basic, low-level function to associate a window with a buffer is
1548 @code{set-window-buffer}. Higher-level functions like
1549 @code{switch-to-buffer} and @code{display-buffer} try to obey a number
1550 of user customizations regulating which windows are supposed to
1551 display which buffers. @xref{Switching Buffers}. When writing an
1552 application, you should avoid using @code{set-window-buffer} unless
1553 you are sure you need it.
1555 @defun set-window-buffer window buffer-or-name &optional keep-margins
1556 This function makes @var{window} display @var{buffer-or-name} and
1557 returns @code{nil}. The argument @var{window} has to denote a live
1558 window and defaults to the selected one. The argument
1559 @var{buffer-or-name} must specify a buffer or the name of an existing
1560 buffer. An error is signaled when @var{window} is @dfn{strongly}
1561 dedicated to its buffer (@pxref{Dedicated Windows}) and does not already
1562 display @var{buffer-or-name}.
1564 Normally, displaying @var{buffer-or-name} in @var{window} resets the
1565 window's position, display margins, fringe widths, and scroll bar
1566 settings based on the local variables of the specified buffer. However,
1567 if the optional argument @var{keep-margins} is non-@code{nil}, display
1568 margins and fringe widths of @var{window} remain unchanged.
1571 This function is the fundamental primitive for changing which buffer is
1572 displayed in a window, and all ways of doing that call this function.
1573 Neither the selected window nor the current buffer are changed by this
1576 This function runs @code{window-scroll-functions} before running
1577 @code{window-configuration-change-hook}, see @ref{Window Hooks}.
1580 @defvar buffer-display-count
1581 This buffer-local variable records the number of times a buffer has been
1582 displayed in a window. It is incremented each time
1583 @code{set-window-buffer} is called for the buffer.
1586 @defvar buffer-display-time
1587 This variable records the time at which a buffer was last made visible
1588 in a window. It is always local in each buffer; each time
1589 @code{set-window-buffer} is called, it sets this variable to
1590 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
1591 When a buffer is first created, @code{buffer-display-time} starts out
1592 with the value @code{nil}.
1595 @defun get-buffer-window &optional buffer-or-name all-frames
1596 This function returns a window displaying @var{buffer-or-name}, or
1597 @code{nil} if there is none. If there are several such windows, then
1598 the function returns the first one in the cyclic ordering of windows,
1599 starting from the selected window, @xref{Cyclic Window Ordering}.
1601 The argument @var{buffer-or-name} may be a buffer or a buffer name and
1602 defaults to the current buffer. The optional argument @var{all-frames}
1603 specifies which windows to consider:
1607 @code{nil} means consider windows on the selected frame.
1609 @code{t} means consider windows on all existing frames.
1611 @code{visible} means consider windows on all visible frames.
1613 0 means consider windows on all visible or iconified frames.
1615 A frame means consider windows on that frame only.
1618 Observe that the behavior of @code{get-buffer-window} may differ from
1619 that of @code{next-window} (@pxref{Cyclic Window Ordering}) when
1620 @var{all-frames} equals @code{nil} or any value not listed here.
1621 Perhaps we will change @code{get-buffer-window} in the future to make it
1622 compatible with the other functions.
1625 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
1626 This function returns a list of all windows currently displaying
1627 @var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer
1628 or the name of an existing buffer and defaults to the current buffer.
1630 The two remaining arguments work like the same-named arguments of
1631 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
1632 like the optional arguments of @code{get-buffer-window}.
1635 @deffn Command replace-buffer-in-windows &optional buffer-or-name
1636 This command replaces @var{buffer-or-name} with some other buffer, in
1637 all windows displaying it. For each such window, it choose another
1638 buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
1640 The argument @var{buffer-or-name} may be a buffer, or the name of an
1641 existing buffer; it defaults to the current buffer.
1643 If a window displaying @var{buffer-or-name} is dedicated
1644 (@pxref{Dedicated Windows}) and is not the only window on its frame,
1645 that window is deleted. If that window is the only window on its frame
1646 and there are other frames on the frame's terminal, that frame is dealt
1647 with by the function specified by @code{frame-auto-hide-function}
1648 (@pxref{Quitting Windows}). Otherwise, the buffer provided by the
1649 function @code{switch-to-prev-buffer} (@pxref{Window History}) is
1650 displayed in the window instead.
1654 @node Switching Buffers
1655 @section Switching to a Buffer in a Window
1656 @cindex switching to a buffer
1657 @cindex displaying a buffer
1659 This section describes high-level functions for switching to a
1660 specified buffer in some window.
1662 Do @emph{not} use these functions to make a buffer temporarily
1663 current just so a Lisp program can access or modify it. They have
1664 side-effects, such as changing window histories (@pxref{Window
1665 History}), which will surprise the user if used that way. If you want
1666 to make a buffer current to modify it in Lisp, use
1667 @code{with-current-buffer}, @code{save-current-buffer}, or
1668 @code{set-buffer}. @xref{Current Buffer}.
1670 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
1671 This function displays @var{buffer-or-name} in the selected window,
1672 and makes it the current buffer. (In contrast, @code{set-buffer}
1673 makes the buffer current but does not display it; @pxref{Current
1674 Buffer}). It is often used interactively (as the binding of @kbd{C-x
1675 b}), as well as in Lisp programs. The return value is the buffer
1678 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
1679 returned by @code{other-buffer} (@pxref{The Buffer List}). If
1680 @var{buffer-or-name} is a string that is not the name of any existing
1681 buffer, this function creates a new buffer with that name; the new
1682 buffer's major mode is determined by the variable @code{major-mode}
1683 (@pxref{Major Modes}).
1685 Normally the specified buffer is put at the front of the buffer
1686 list---both the global buffer list and the selected frame's buffer
1687 list (@pxref{The Buffer List}). However, this is not done if the
1688 optional argument @var{norecord} is non-@code{nil}.
1690 If this function is unable to display the buffer in the selected
1691 window---usually because the selected window is a minibuffer window or
1692 is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then
1693 it normally tries to display the buffer in some other window, in the
1694 manner of @code{pop-to-buffer} (see below). However, if the optional
1695 argument @var{force-same-window} is non-@code{nil}, it signals an error
1699 The next two functions are similar to @code{switch-to-buffer}, except
1700 for the described features.
1702 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
1703 This function makes the buffer specified by @var{buffer-or-name}
1704 current and displays it in some window other than the selected window.
1705 It uses the function @code{pop-to-buffer} internally (see below).
1707 If the selected window already displays the specified buffer, it
1708 continues to do so, but another window is nonetheless found to display
1711 The @var{buffer-or-name} and @var{norecord} arguments have the same
1712 meanings as in @code{switch-to-buffer}.
1715 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
1716 This function makes the buffer specified by @var{buffer-or-name}
1717 current and displays it, usually in a new frame. It uses the function
1718 @code{pop-to-buffer} (see below).
1720 If the specified buffer is already displayed in another window, in any
1721 frame on the current terminal, this switches to that window instead of
1722 creating a new frame. However, the selected window is never used for
1725 The @var{buffer-or-name} and @var{norecord} arguments have the same
1726 meanings as in @code{switch-to-buffer}.
1729 The above commands use @code{pop-to-buffer}, which is the function
1730 used by Lisp programs to flexibly display a buffer in some window and
1731 select that window for editing:
1733 @defun pop-to-buffer buffer-or-name &optional action norecord
1734 This function makes @var{buffer-or-name} the current buffer and
1735 displays it in some window, preferably not the window previously
1736 selected. It then selects the displaying window. If that window is
1737 on a different graphical frame, that frame is given input focus if
1738 possible (@pxref{Input Focus}). The return value is the buffer that
1741 This function uses @code{display-buffer} to display the buffer, so all
1742 the variables affecting @code{display-buffer} will affect it as well.
1743 @xref{Choosing Window}.
1745 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
1746 returned by @code{other-buffer} (@pxref{The Buffer List}). If
1747 @var{buffer-or-name} is a string that is not the name of any existing
1748 buffer, this function creates a new buffer with that name; the new
1749 buffer's major mode is determined by the variable @code{major-mode}
1750 (@pxref{Major Modes}).
1752 If @var{action} is non-@code{nil}, it should be a display action to
1753 pass to @code{display-buffer} (@pxref{Choosing Window}).
1754 Alternatively, a non-@code{nil}, non-list value means to pop to a
1755 window other than the selected one---even if the buffer is already
1756 displayed in the selected window.
1758 Like @code{switch-to-buffer}, this function updates the buffer list
1759 unless @var{norecord} is non-@code{nil}.
1762 @node Choosing Window
1763 @section Choosing a Window for Display
1765 The command @code{display-buffer} flexibly chooses a window for
1766 display, and displays a specified buffer in that window. It can be
1767 called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
1768 used as a subroutine by many functions and commands, including
1769 @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
1772 @cindex display action
1773 @cindex action function, for display-buffer
1774 @cindex action alist, for display-buffer
1775 This command performs several complex steps to find a window to
1776 display in. These steps are described by means of @dfn{display
1777 actions}, which have the form @code{(@var{function} . @var{alist})}.
1778 Here, @var{function} is either a function or a list of functions,
1779 which we refer to as @dfn{action functions}; @var{alist} is an
1780 association list, which we refer to as @dfn{action alists}.
1782 An action function accepts two arguments: the buffer to display and
1783 an action alist. It attempts to display the buffer in some window,
1784 picking or creating a window according to its own criteria. If
1785 successful, it returns the window; otherwise, it returns @code{nil}.
1786 @xref{Display Action Functions}, for a list of predefined action
1789 @code{display-buffer} works by combining display actions from
1790 several sources, and calling the action functions in turn, until one
1791 of them manages to display the buffer and returns a non-@code{nil}
1794 @deffn Command display-buffer buffer-or-name &optional action frame
1795 This command makes @var{buffer-or-name} appear in some window, without
1796 selecting the window or making the buffer current. The argument
1797 @var{buffer-or-name} must be a buffer or the name of an existing
1798 buffer. The return value is the window chosen to display the buffer.
1800 The optional argument @var{action}, if non-@code{nil}, should normally
1801 be a display action (described above). @code{display-buffer} builds a
1802 list of action functions and an action alist, by consolidating display
1803 actions from the following sources (in order):
1807 The variable @code{display-buffer-overriding-action}.
1810 The user option @code{display-buffer-alist}.
1813 The @var{action} argument.
1816 The user option @code{display-buffer-base-action}.
1819 The constant @code{display-buffer-fallback-action}.
1823 Each action function is called in turn, passing the buffer as the
1824 first argument and the combined action alist as the second argument,
1825 until one of the functions returns non-@code{nil}.
1827 The argument @var{action} can also have a non-@code{nil}, non-list
1828 value. This has the special meaning that the buffer should be
1829 displayed in a window other than the selected one, even if the
1830 selected window is already displaying it. If called interactively
1831 with a prefix argument, @var{action} is @code{t}.
1833 The optional argument @var{frame}, if non-@code{nil}, specifies which
1834 frames to check when deciding whether the buffer is already displayed.
1835 It is equivalent to adding an element @code{(reusable-frames
1836 . @var{frame})} to the action alist of @var{action}. @xref{Display
1840 @defvar display-buffer-overriding-action
1841 The value of this variable should be a display action, which is
1842 treated with the highest priority by @code{display-buffer}. The
1843 default value is empty, i.e. @code{(nil . nil)}.
1846 @defopt display-buffer-alist
1847 The value of this option is an alist mapping regular expressions to
1848 display actions. If the name of the buffer passed to
1849 @code{display-buffer} matches a regular expression in this alist, then
1850 @code{display-buffer} uses the corresponding display action.
1853 @defopt display-buffer-base-action
1854 The value of this option should be a display action. This option can
1855 be used to define a ``standard'' display action for calls to
1856 @code{display-buffer}.
1859 @defvr Constant display-buffer-fallback-action
1860 This display action specifies the fallback behavior for
1861 @code{display-buffer} if no other display actions are given.
1864 @node Display Action Functions
1865 @section Action Functions for @code{display-buffer}
1867 The following basic action functions are defined in Emacs. Each of
1868 these functions takes two arguments: @var{buffer}, the buffer to
1869 display, and @var{alist}, an action alist. Each action function
1870 returns the window if it succeeds, and @code{nil} if it fails.
1872 @defun display-buffer-same-window buffer alist
1873 This function tries to display @var{buffer} in the selected window.
1874 It fails if the selected window is a minibuffer window or is dedicated
1875 to another buffer (@pxref{Dedicated Windows}). It also fails if
1876 @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
1879 @defun display-buffer-reuse-window buffer alist
1880 This function tries to ``display'' @var{buffer} by finding a window
1881 that is already displaying it.
1883 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
1884 the selected window is not eligible for reuse.
1886 If @var{alist} contains a @code{reusable-frames} entry, its value
1887 determines which frames to search for a reusable window:
1891 @code{nil} means consider windows on the selected frame.
1892 (Actually, the last non-minibuffer frame.)
1894 @code{t} means consider windows on all frames.
1896 @code{visible} means consider windows on all visible frames.
1898 0 means consider windows on all visible or iconified frames.
1900 A frame means consider windows on that frame only.
1903 If @var{alist} contains no @code{reusable-frames} entry, this function
1904 normally searches just the selected frame; however, if either the
1905 variable @code{display-buffer-reuse-frames} or the variable
1906 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
1907 current terminal. @xref{Choosing Window Options}.
1910 @defun display-buffer-pop-up-frame buffer alist
1911 This function creates a new frame, and displays the buffer in that
1915 @defun display-buffer-pop-up-window buffer alist
1916 This function tries to display @var{buffer} by splitting the largest
1917 or least recently-used window. It uses @code{split-window-sensibly}
1918 as a subroutine (@pxref{Choosing Window Options}).
1921 @defun display-buffer-use-some-window buffer alist
1922 This function tries to display @var{buffer} by choosing an existing
1923 window and displaying the buffer in that window. It can fail if all
1924 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
1927 @node Choosing Window Options
1928 @section Additional Options for Displaying Buffers
1930 The behavior of the standard display actions of @code{display-buffer}
1931 (@pxref{Choosing Window}) can be modified by a variety of user
1934 @defopt display-buffer-reuse-frames
1935 If this variable is non-@code{nil}, @code{display-buffer} searches
1936 visible and iconified frames for a window displaying
1937 @var{buffer-or-name}. If there is such a window, @code{display-buffer}
1938 makes that window's frame visible and raises it if necessary, and
1939 returns the window. If there is no such window or
1940 @code{display-buffer-reuse-frames} is @code{nil}, the behavior of
1941 @code{display-buffer} is determined by the variables described next.
1944 @defopt pop-up-windows
1945 This variable specifies whether @code{display-buffer} is allowed to
1946 split (@pxref{Splitting Windows}) an existing window. If this variable
1947 is non-@code{nil}, @code{display-buffer} tries to split the largest or
1948 least recently used window on the selected frame. (If the selected
1949 frame is a minibuffer-only frame, @code{display-buffer} tries to split a
1950 window on another frame instead.) If this variable is @code{nil} or the
1951 variable @code{pop-up-frames} (see below) is non-@code{nil},
1952 @code{display-buffer} does not split any window.
1955 @defopt split-window-preferred-function
1956 This variable must specify a function with one argument, which is a
1957 window. The @code{display-buffer} routines will call this function with
1958 one or more candidate windows when they look for a window to split. The
1959 function is expected to split that window and return the new window. If
1960 the function returns @code{nil}, this means that the argument window
1961 cannot (or shall not) be split.
1963 The default value of @code{split-window-preferred-function} is the
1964 function @code{split-window-sensibly} described below. If you
1965 customize this option, bear in mind that the @code{display-buffer}
1966 routines may call your function up to two times when trying to split a
1967 window. The argument of the first call is the largest window on the
1968 chosen frame (as returned by @code{get-largest-window}). If that call
1969 fails to return a live window, your function is called a second time
1970 with the least recently used window on that frame (as returned by
1971 @code{get-lru-window}).
1973 The function specified by this option may try to split any other window
1974 instead of the argument window. Note that the window selected at the
1975 time @code{display-buffer} was invoked is still selected when your
1976 function is called. Hence, you can split the selected window (instead
1977 of the largest or least recently used one) by simply ignoring the window
1978 argument in the body of your function. You can even choose to not split
1979 any window as long as the return value of your function specifies a live
1980 window or @code{nil}, but you are not encouraged to do so
1981 unconditionally. If you want @code{display-buffer} to never split any
1982 windows, set @code{pop-up-windows} to @code{nil}.
1985 @defun split-window-sensibly window
1986 This function takes a window as argument and tries to split that window
1987 in a suitable way. The two variables described next are useful for
1988 tuning the behavior of this function.
1991 @defopt split-height-threshold
1992 This variable specifies whether @code{split-window-sensibly} may split
1993 windows vertically. If it is an integer, @code{split-window-sensibly}
1994 tries to vertically split a window only if it has at least this many
1995 lines. If the window has less lines, splitting fails, or the value of
1996 this variable is @code{nil}, @code{split-window-sensibly} will try to
1997 split the window horizontally, subject to restrictions of
1998 @code{split-width-threshold} (see below). If splitting horizontally
1999 fails too and the window is the only window on its frame,
2000 @code{split-window-sensibly} will try to split the window vertically
2001 disregarding the value of @code{split-height-threshold}. If this fails
2002 as well, @code{split-window-sensibly} returns @code{nil}.
2004 @code{split-window-sensibly} does not split vertically a window whose
2005 height is fixed (@pxref{Resizing Windows}). Also, it vertically splits
2006 a window only if the space taken up by that window can accommodate two
2007 windows one above the other that are both at least
2008 @code{window-min-height} lines tall. Moreover, if the window that shall
2009 be split has a mode line, @code{split-window-sensibly} does not split
2010 the window unless the new window can accommodate a mode line too.
2013 @defopt split-width-threshold
2014 This variable specifies whether @code{split-window-sensibly} may split
2015 windows horizontally. If it is an integer, @code{split-window-sensibly}
2016 tries to horizontally split a window only if it has at least this many
2017 columns. If it is @code{nil}, @code{split-window-sensibly} will not
2018 split the window horizontally. (It still might split the window
2019 vertically, though, see above.)
2021 @code{split-window-sensibly} does not split horizontally a window if
2022 that window's width is fixed (@pxref{Resizing Windows}). Also, it
2023 horizontally splits a window only if the space that window takes up can
2024 accommodate two windows side by side that are both at least
2025 @code{window-min-width} columns wide.
2028 @defopt even-window-heights
2029 This variable specifies whether @code{display-buffer} should even out
2030 window heights if the buffer gets displayed in an existing window, above
2031 or beneath another window. If @code{even-window-heights} is
2032 non-@code{nil}, the default, window heights will be evened out. If
2033 either of the involved window has fixed height (@pxref{Resizing
2034 Windows}) or @code{even-window-heights} is @code{nil}, the original
2035 window heights will be left alone.
2039 @defopt pop-up-frames
2040 This variable specifies whether @code{display-buffer} should make new
2041 frames. If it is non-@code{nil}, @code{display-buffer} looks for a
2042 window already displaying @var{buffer-or-name} on any visible or
2043 iconified frame. If it finds such a window, it makes that window's
2044 frame visible and raises it if necessary, and returns the window.
2045 Otherwise it makes a new frame, unless the variable's value is
2046 @code{graphic-only} and the selected frame is not on a graphic display.
2047 @xref{Frames}, for more information.
2049 Note that the value of @code{pop-up-windows} does not matter if
2050 @code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is
2051 @code{nil}, then @code{display-buffer} either splits a window or reuses
2056 @defopt pop-up-frame-function
2057 This variable specifies how to make a new frame if @code{pop-up-frames}
2060 The value of this variable must be a function of no arguments. When
2061 @code{display-buffer} makes a new frame, it does so by calling that
2062 function, which should return a frame. The default value of this
2063 variable is a function that creates a frame using the parameters
2064 specified by @code{pop-up-frame-alist} described next.
2067 @defopt pop-up-frame-alist
2068 This variable holds an alist specifying frame parameters used by the
2069 default value of @code{pop-up-frame-function} for making new frames.
2070 @xref{Frame Parameters}, for more information about frame parameters.
2073 @defopt special-display-buffer-names
2074 A list of buffer names identifying buffers that should be displayed
2075 specially. If the name of @var{buffer-or-name} is in this list,
2076 @code{display-buffer} handles the buffer specially. By default, special
2077 display means to give the buffer a dedicated frame.
2079 If an element is a list, instead of a string, then the @sc{car} of that
2080 list is the buffer name, and the rest of that list says how to create
2081 the frame. There are two possibilities for the rest of that list (its
2082 @sc{cdr}): It can be an alist, specifying frame parameters, or it can
2083 contain a function and arguments to give to it. (The function's first
2084 argument is always the buffer to be displayed; the arguments from the
2085 list come after that.)
2090 (("myfile" (minibuffer) (menu-bar-lines . 0)))
2094 specifies to display a buffer named @samp{myfile} in a dedicated frame
2095 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
2097 The list of frame parameters can also use the phony frame parameters
2098 @code{same-frame} and @code{same-window}. If the specified frame
2099 parameters include @code{(same-window . @var{value})} and @var{value}
2100 is non-@code{nil}, that means to display the buffer in the current
2101 selected window. Otherwise, if they include @code{(same-frame .
2102 @var{value})} and @var{value} is non-@code{nil}, that means to display
2103 the buffer in a new window in the currently selected frame.
2106 @defopt special-display-regexps
2107 A list of regular expressions specifying buffers that should be
2108 displayed specially. If the buffer's name matches any of the regular
2109 expressions in this list, @code{display-buffer} handles the buffer
2110 specially. By default, special display means to give the buffer a
2113 If an element is a list, instead of a string, then the @sc{car} of the
2114 list is the regular expression, and the rest of the list says how to
2115 create the frame. See @code{special-display-buffer-names} above.
2118 @defun special-display-p buffer-name
2119 This function returns non-@code{nil} if displaying a buffer
2120 named @var{buffer-name} with @code{display-buffer} would
2121 create a special frame. The value is @code{t} if it would
2122 use the default frame parameters, or else the specified list
2123 of frame parameters.
2126 @defopt special-display-function
2127 This variable holds the function to call to display a buffer specially.
2128 It receives the buffer as an argument, and should return the window in
2129 which it is displayed. The default value of this variable is
2130 @code{special-display-popup-frame}, see below.
2133 @defun special-display-popup-frame buffer &optional args
2134 This function tries to make @var{buffer} visible in a frame of its own.
2135 If @var{buffer} is already displayed in some window, it makes that
2136 window's frame visible and raises it. Otherwise, it creates a frame
2137 that is dedicated to @var{buffer}. The return value is the window used
2138 to display @var{buffer}.
2140 If @var{args} is an alist, it specifies frame parameters for the new
2141 frame. If @var{args} is a list whose @sc{car} is a symbol, then
2142 @code{(car @var{args})} is called as a function to actually create and
2143 set up the frame; it is called with @var{buffer} as first argument, and
2144 @code{(cdr @var{args})} as additional arguments.
2146 This function always uses an existing window displaying @var{buffer},
2147 whether or not it is in a frame of its own; but if you set up the above
2148 variables in your init file, before @var{buffer} was created, then
2149 presumably the window was previously made by this function.
2152 @defopt special-display-frame-alist
2153 @anchor{Definition of special-display-frame-alist}
2154 This variable holds frame parameters for
2155 @code{special-display-popup-frame} to use when it creates a frame.
2158 @defopt same-window-buffer-names
2159 A list of buffer names for buffers that should be displayed in the
2160 selected window. If the buffer's name is in this list,
2161 @code{display-buffer} handles the buffer by switching to it in the
2165 @defopt same-window-regexps
2166 A list of regular expressions that specify buffers that should be
2167 displayed in the selected window. If the buffer's name matches any of
2168 the regular expressions in this list, @code{display-buffer} handles the
2169 buffer by switching to it in the selected window.
2172 @defun same-window-p buffer-name
2173 This function returns @code{t} if displaying a buffer
2174 named @var{buffer-name} with @code{display-buffer} would
2175 put it in the selected window.
2179 @defopt display-buffer-function
2180 This variable is the most flexible way to customize the behavior of
2181 @code{display-buffer}. If it is non-@code{nil}, it should be a function
2182 that @code{display-buffer} calls to do the work. The function should
2183 accept two arguments, the first two arguments that @code{display-buffer}
2184 received. It should choose or create a window, display the specified
2185 buffer in it, and then return the window.
2187 This variable takes precedence over all the other options described
2191 If all options described above fail to produce a suitable window,
2192 @code{display-buffer} tries to reuse an existing window. As a last
2193 resort, it will try to display @var{buffer-or-name} on a separate frame.
2194 In that case, the value of @code{pop-up-frames} is disregarded.
2197 @node Window History
2198 @section Window History
2199 @cindex window history
2201 Each window remembers the buffers it has displayed earlier and the order
2202 in which these buffers have been removed from it. This history is used,
2203 for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and
2204 Windows}). This list is automatically maintained by Emacs, but you can
2205 use the following functions to explicitly inspect or alter it:
2207 @defun window-prev-buffers &optional window
2208 This function returns a list specifying the previous contents of
2209 @var{window}, which should be a live window and defaults to the
2212 Each list element has the form @code{(@var{buffer} @var{window-start}
2213 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
2214 the window, @var{window-start} is the window start position when that
2215 buffer was last shown, and @var{window-pos} is the point position when
2216 that buffer was last shown.
2218 The list is ordered so that earlier elements correspond to more
2219 recently-shown buffers, and the first element usually corresponds to the
2220 buffer most recently removed from the window.
2223 @defun set-window-prev-buffers window prev-buffers
2224 This function sets @var{window}'s previous buffers to the value of
2225 @var{prev-buffers}. The argument @var{window} must be a live window
2226 and defaults to the selected one. The argument @var{prev-buffers}
2227 should be a list of the same form as that returned by
2228 @code{window-prev-buffers}.
2231 In addition, each buffer maintains a list of @dfn{next buffers}, which
2232 is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
2233 below). This list is mainly used by @code{switch-to-prev-buffer} and
2234 @code{switch-to-next-buffer} for choosing buffers to switch to.
2236 @defun window-next-buffers &optional window
2237 This function returns the list of buffers recently re-shown in
2238 @var{window} via @code{switch-to-prev-buffer}. The @var{window}
2239 argument must denote a live window or @code{nil} (meaning the selected
2243 @defun set-window-next-buffers window next-buffers
2244 This function sets the next buffer list of @var{window} to
2245 @var{next-buffers}. The @var{window} argument should be a live window
2246 or @code{nil} (meaning the selected window). The argument
2247 @var{next-buffers} should be a list of buffers.
2250 The following commands can be used to cycle through the global buffer
2251 list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
2252 they cycle according to the specified window's history list, rather
2253 than the global buffer list. In addition, they restore
2254 window-specific window start and point positions, and may show a
2255 buffer even if it is already shown in another window. The
2256 @code{switch-to-prev-buffer} command, in particular, is used by
2257 @code{replace-buffer-in-windows}, @code{bury-buffer} and
2258 @code{quit-window} to find a replacement buffer for a window.
2260 @deffn Command switch-to-prev-buffer &optional window bury-or-kill
2261 This command displays the previous buffer in @var{window}. The
2262 argument @var{window} should be a live window or @code{nil} (meaning
2263 the selected window). If the optional argument @var{bury-or-kill} is
2264 non-@code{nil}, this means that the buffer currently shown in
2265 @var{window} is about to be buried or killed and consequently shall
2266 not be switched to in future invocations of this command.
2268 The previous buffer is usually the buffer shown before the buffer
2269 currently shown in @var{window}. However, a buffer that has been buried
2270 or killed or has been already shown by a recent invocation of
2271 @code{switch-to-prev-buffer} does not qualify as previous buffer.
2273 If repeated invocations of this command have already shown all buffers
2274 previously shown in @var{window}, further invocations will show buffers
2275 from the buffer list of the frame @var{window} appears on (@pxref{The
2279 @deffn Command switch-to-next-buffer &optional window
2280 This command switches to the next buffer in @var{window} thus undoing
2281 the effect of the last @code{switch-to-prev-buffer} command in
2282 @var{window}. The argument @var{window} must be a live window and
2283 defaults to the selected one.
2285 If there is no recent invocation of a @code{switch-to-prev-buffer} that
2286 can be undone, this function tries to show a buffer from the buffer list
2287 of the frame @var{window} appears on (@pxref{The Buffer List}).
2291 @node Dedicated Windows
2292 @section Dedicated Windows
2293 @cindex dedicated window
2295 Functions for displaying a buffer can be told to not use specific
2296 windows by marking these windows as @dfn{dedicated} to their buffers.
2297 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
2298 window for displaying another buffer in it. @code{get-lru-window} and
2299 @code{get-largest-window} (@pxref{Selecting Windows}) do not consider
2300 dedicated windows as candidates when their @var{dedicated} argument is
2301 non-@code{nil}. The behavior of @code{set-window-buffer}
2302 (@pxref{Buffers and Windows}) with respect to dedicated windows is
2303 slightly different, see below.
2305 When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
2306 delete a dedicated window and that window is the only window on its
2307 frame, it deletes the window's frame too, provided there are other
2308 frames left. @code{replace-buffer-in-windows} (@pxref{Switching
2309 Buffers}) tries to delete all dedicated windows showing its buffer
2310 argument. When such a window is the only window on its frame, that
2311 frame is deleted, provided there are other frames left. If there are
2312 no more frames left, some other buffer is displayed in the window, and
2313 the window is marked as non-dedicated.
2315 When you kill a buffer (@pxref{Killing Buffers}) displayed in a
2316 dedicated window, any such window usually gets deleted too, since
2317 @code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
2318 up windows. Burying a buffer (@pxref{The Buffer List}) deletes the
2319 selected window if it is dedicated to that buffer. If, however, that
2320 window is the only window on its frame, @code{bury-buffer} displays
2321 another buffer in it and iconifies the frame.
2323 @defun window-dedicated-p &optional window
2324 This function returns non-@code{nil} if @var{window} is dedicated to its
2325 buffer and @code{nil} otherwise. More precisely, the return value is
2326 the value assigned by the last call of @code{set-window-dedicated-p} for
2327 @var{window} or @code{nil} if that function was never called with
2328 @var{window} as its argument. The default for @var{window} is the
2332 @defun set-window-dedicated-p window flag
2333 This function marks @var{window} as dedicated to its buffer if
2334 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
2336 As a special case, if @var{flag} is @code{t}, @var{window} becomes
2337 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
2338 signals an error when the window it acts upon is strongly dedicated to
2339 its buffer and does not already display the buffer it is asked to
2340 display. Other functions do not treat @code{t} differently from any
2341 non-@code{nil} value.
2345 @node Quitting Windows
2346 @section Quitting Windows
2348 When you want to get rid of a window used for displaying a buffer you
2349 can call @code{delete-window} or @code{delete-windows-on}
2350 (@pxref{Deleting Windows}) to remove that window from its frame. If the
2351 buffer is shown on a separate frame, you might want to call
2352 @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
2353 hand, a window has been reused for displaying the buffer, you might
2354 prefer showing the buffer previously shown in that window by calling the
2355 function @code{switch-to-prev-buffer} (@pxref{Window History}).
2356 Finally, you might want to either bury (@pxref{The Buffer List}) or kill
2357 (@pxref{Killing Buffers}) the window's buffer.
2359 The following function uses information on how the window for
2360 displaying the buffer was obtained in the first place thus attempting to
2361 automatize the above decisions for you.
2363 @deffn Command quit-window &optional kill window
2364 This command quits @var{window} and buries its buffer. The argument
2365 @var{window} must be a live window and defaults to the selected one.
2366 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
2367 instead of burying it.
2369 Quitting @var{window} means to proceed as follows: If @var{window} was
2370 created specially for displaying its current buffer, delete @var{window}
2371 provided its frame contains at least one other live window. If
2372 @var{window} is the only window on its frame and there are other frames
2373 on the frame's terminal, the value of @var{kill} determines how to
2374 proceed with the window. If @var{kill} is @code{nil}, the fate of the
2375 frame is determined by calling @code{frame-auto-hide-function} (see
2376 below) with that frame as sole argument. If @var{kill} is
2377 non-@code{nil}, the frame is deleted unconditionally.
2379 If @var{window} was reused for displaying its buffer, this command tries
2380 to display the buffer previously shown in it. It also tries to restore
2381 the window start (@pxref{Window Start and End}) and point (@pxref{Window
2382 Point}) positions of the previously shown buffer. If, in addition, the
2383 current buffer was temporarily resized, this command will also try to
2384 restore the original height of @var{window}.
2386 The three cases described so far require that the buffer shown in
2387 @var{window} is still the buffer displayed by the last buffer display
2388 function for this window. If another buffer has been shown in the
2389 meantime or the buffer previously shown no longer exists, this command
2390 calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some
2391 other buffer instead.
2394 The function @code{quit-window} bases its decisions on information
2395 stored in @var{window}'s @code{quit-restore} window parameter
2396 (@pxref{Window Parameters}) and resets that parameter to @code{nil}
2399 The following option specifies how to deal with a frame containing just
2400 one window that shall be either quit or whose buffer shall be buried.
2402 @defopt frame-auto-hide-function
2403 The function specified by this option is called to automatically hide
2404 frames. This function is called with one argument - a frame.
2406 The function specified here is called by @code{bury-buffer} (@pxref{The
2407 Buffer List}) when the selected window is dedicated and shows the buffer
2408 that shall be buried. It is also called by @code{quit-window} (see
2409 above) when the frame of the window that shall be quit has been
2410 specially created for displaying that window's buffer and the buffer
2413 The default is to call @code{iconify-frame} (@pxref{Visibility of
2414 Frames}). Alternatively, you may either specify @code{delete-frame}
2415 (@pxref{Deleting Frames}) to remove the frame from its display,
2416 @code{ignore} to leave the frame unchanged, or any other function that
2417 can take a frame as its sole argument.
2419 Note that the function specified by this option is called if and only if
2420 there's at least one other frame on the terminal of the frame it's
2421 supposed to handle and that frame contains only one live window.
2426 @section Windows and Point
2427 @cindex window position
2428 @cindex window point
2429 @cindex position in window
2430 @cindex point in window
2432 Each window has its own value of point (@pxref{Point}), independent of
2433 the value of point in other windows displaying the same buffer. This
2434 makes it useful to have multiple windows showing one buffer.
2438 The window point is established when a window is first created; it is
2439 initialized from the buffer's point, or from the window point of another
2440 window opened on the buffer if such a window exists.
2443 Selecting a window sets the value of point in its buffer from the
2444 window's value of point. Conversely, deselecting a window sets the
2445 window's value of point from that of the buffer. Thus, when you switch
2446 between windows that display a given buffer, the point value for the
2447 selected window is in effect in the buffer, while the point values for
2448 the other windows are stored in those windows.
2451 As long as the selected window displays the current buffer, the window's
2452 point and the buffer's point always move together; they remain equal.
2456 As far as the user is concerned, point is where the cursor is, and
2457 when the user switches to another buffer, the cursor jumps to the
2458 position of point in that buffer.
2460 @defun window-point &optional window
2461 This function returns the current position of point in @var{window}.
2462 For a nonselected window, this is the value point would have (in that
2463 window's buffer) if that window were selected. The default for
2464 @var{window} is the selected window.
2466 When @var{window} is the selected window and its buffer is also the
2467 current buffer, the value returned is the same as point in that buffer.
2468 Strictly speaking, it would be more correct to return the ``top-level''
2469 value of point, outside of any @code{save-excursion} forms. But that
2470 value is hard to find.
2473 @defun set-window-point window position
2474 This function positions point in @var{window} at position
2475 @var{position} in @var{window}'s buffer. It returns @var{position}.
2477 If @var{window} is selected, and its buffer is current,
2478 this simply does @code{goto-char}.
2481 @defvar window-point-insertion-type
2482 This variable specifies the marker insertion type (@pxref{Marker
2483 Insertion Types}) of @code{window-point}. The default is @code{nil},
2484 so @code{window-point} will stay behind text inserted there.
2487 @node Window Start and End
2488 @section The Window Start and End Positions
2489 @cindex window start position
2491 Each window maintains a marker used to keep track of a buffer position
2492 that specifies where in the buffer display should start. This position
2493 is called the @dfn{display-start} position of the window (or just the
2494 @dfn{start}). The character after this position is the one that appears
2495 at the upper left corner of the window. It is usually, but not
2496 inevitably, at the beginning of a text line.
2498 After switching windows or buffers, and in some other cases, if the
2499 window start is in the middle of a line, Emacs adjusts the window
2500 start to the start of a line. This prevents certain operations from
2501 leaving the window start at a meaningless point within a line. This
2502 feature may interfere with testing some Lisp code by executing it
2503 using the commands of Lisp mode, because they trigger this
2504 readjustment. To test such code, put it into a command and bind the
2507 @defun window-start &optional window
2508 @cindex window top line
2509 This function returns the display-start position of window
2510 @var{window}. If @var{window} is @code{nil}, the selected window is
2520 When you create a window, or display a different buffer in it, the
2521 display-start position is set to a display-start position recently used
2522 for the same buffer, or to @code{point-min} if the buffer doesn't have
2525 Redisplay updates the window-start position (if you have not specified
2526 it explicitly since the previous redisplay)---to make sure point appears
2527 on the screen. Nothing except redisplay automatically changes the
2528 window-start position; if you move point, do not expect the window-start
2529 position to change in response until after the next redisplay.
2531 For a realistic example of using @code{window-start}, see the
2532 description of @code{count-lines}. @xref{Definition of count-lines}.
2535 @cindex window end position
2536 @defun window-end &optional window update
2537 This function returns the position where display of its buffer ends in
2538 @var{window}. The default for @var{window} is the selected window.
2540 Simply changing the buffer text or moving point does not update the
2541 value that @code{window-end} returns. The value is updated only when
2542 Emacs redisplays and redisplay completes without being preempted.
2544 If the last redisplay of @var{window} was preempted, and did not finish,
2545 Emacs does not know the position of the end of display in that window.
2546 In that case, this function returns @code{nil}.
2548 If @var{update} is non-@code{nil}, @code{window-end} always returns an
2549 up-to-date value for where display ends, based on the current
2550 @code{window-start} value. If a previously saved value of that position
2551 is still valid, @code{window-end} returns that value; otherwise it
2552 computes the correct value by scanning the buffer text.
2554 Even if @var{update} is non-@code{nil}, @code{window-end} does not
2555 attempt to scroll the display if point has moved off the screen, the
2556 way real redisplay would do. It does not alter the
2557 @code{window-start} value. In effect, it reports where the displayed
2558 text will end if scrolling is not required.
2561 @defun set-window-start window position &optional noforce
2562 This function sets the display-start position of @var{window} to
2563 @var{position} in @var{window}'s buffer. It returns @var{position}.
2565 The display routines insist that the position of point be visible when a
2566 buffer is displayed. Normally, they change the display-start position
2567 (that is, scroll the window) whenever necessary to make point visible.
2568 However, if you specify the start position with this function using
2569 @code{nil} for @var{noforce}, it means you want display to start at
2570 @var{position} even if that would put the location of point off the
2571 screen. If this does place point off screen, the display routines move
2572 point to the left margin on the middle line in the window.
2574 For example, if point @w{is 1} and you set the start of the window
2575 @w{to 37}, the start of the next line, point will be ``above'' the top
2576 of the window. The display routines will automatically move point if
2577 it is still 1 when redisplay occurs. Here is an example:
2581 ;; @r{Here is what @samp{foo} looks like before executing}
2582 ;; @r{the @code{set-window-start} expression.}
2586 ---------- Buffer: foo ----------
2587 @point{}This is the contents of buffer foo.
2593 ---------- Buffer: foo ----------
2607 ;; @r{Here is what @samp{foo} looks like after executing}
2608 ;; @r{the @code{set-window-start} expression.}
2609 ---------- Buffer: foo ----------
2615 ---------- Buffer: foo ----------
2619 If @var{noforce} is non-@code{nil}, and @var{position} would place point
2620 off screen at the next redisplay, then redisplay computes a new window-start
2621 position that works well with point, and thus @var{position} is not used.
2624 @defun pos-visible-in-window-p &optional position window partially
2625 This function returns non-@code{nil} if @var{position} is within the
2626 range of text currently visible on the screen in @var{window}. It
2627 returns @code{nil} if @var{position} is scrolled vertically out of view.
2628 Locations that are partially obscured are not considered visible unless
2629 @var{partially} is non-@code{nil}. The argument @var{position} defaults
2630 to the current position of point in @var{window}; @var{window}, to the
2631 selected window. If @var{position} is @code{t}, that means to check the
2632 last visible position in @var{window}.
2634 This function considers only vertical scrolling. If @var{position} is
2635 out of view only because @var{window} has been scrolled horizontally,
2636 @code{pos-visible-in-window-p} returns non-@code{nil} anyway.
2637 @xref{Horizontal Scrolling}.
2639 If @var{position} is visible, @code{pos-visible-in-window-p} returns
2640 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
2641 non-@code{nil}, and the character following @var{position} is fully
2642 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
2643 @var{x} and @var{y} are the pixel coordinates relative to the top left
2644 corner of the window; otherwise it returns an extended list of the form
2645 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
2646 where @var{rtop} and @var{rbot} specify the number of off-window pixels
2647 at the top and bottom of the row at @var{position}, @var{rowh} specifies
2648 the visible height of that row, and @var{vpos} specifies the vertical
2649 position (zero-based row number) of that row.
2655 ;; @r{If point is off the screen now, recenter it now.}
2656 (or (pos-visible-in-window-p
2657 (point) (selected-window))
2663 @defun window-line-height &optional line window
2664 This function returns the height of text line @var{line} in
2665 @var{window}. If @var{line} is one of @code{header-line} or
2666 @code{mode-line}, @code{window-line-height} returns information about
2667 the corresponding line of the window. Otherwise, @var{line} is a text
2668 line number starting from 0. A negative number counts from the end of
2669 the window. The default for @var{line} is the current line in
2670 @var{window}; the default for @var{window} is the selected window.
2672 If the display is not up to date, @code{window-line-height} returns
2673 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
2674 to obtain related information.
2676 If there is no line corresponding to the specified @var{line},
2677 @code{window-line-height} returns @code{nil}. Otherwise, it returns
2678 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
2679 where @var{height} is the height in pixels of the visible part of the
2680 line, @var{vpos} and @var{ypos} are the vertical position in lines and
2681 pixels of the line relative to the top of the first text line, and
2682 @var{offbot} is the number of off-window pixels at the bottom of the
2683 text line. If there are off-window pixels at the top of the (first)
2684 text line, @var{ypos} is negative.
2687 @node Textual Scrolling
2688 @section Textual Scrolling
2689 @cindex textual scrolling
2690 @cindex scrolling textually
2692 @dfn{Textual scrolling} means moving the text up or down through a
2693 window. It works by changing the window's display-start location. It
2694 may also change the value of @code{window-point} to keep point on the
2695 screen (@pxref{Window Point}).
2697 The basic textual scrolling functions are @code{scroll-up} (which
2698 scrolls forward) and @code{scroll-down} (which scrolls backward). In
2699 these function names, ``up'' and ``down'' refer to the direction of
2700 motion of the buffer text relative to the window. Imagine that the
2701 text is written on a long roll of paper and that the scrolling
2702 commands move the paper up and down. Thus, if you are looking at the
2703 middle of a buffer and repeatedly call @code{scroll-down}, you will
2704 eventually see the beginning of the buffer.
2706 Some people have urged that the opposite convention be used: they
2707 imagine the window moving over text that remains in place, so that
2708 ``down'' commands take you to the end of the buffer. This convention
2709 is consistent with fact that such a command is bound to a key named
2710 @key{PageDown} on modern keyboards. We have not switched to this
2711 convention as that is likely to break existing Emacs Lisp code.
2713 Textual scrolling functions (aside from @code{scroll-other-window})
2714 have unpredictable results if the current buffer is not the one
2715 displayed in the selected window. @xref{Current Buffer}.
2717 If the window contains a row taller than the height of the window
2718 (for example in the presence of a large image), the scroll functions
2719 will adjust the window's vertical scroll position to scroll the
2720 partially visible row. Lisp callers can disable this feature by
2721 binding the variable @code{auto-window-vscroll} to @code{nil}
2722 (@pxref{Vertical Scrolling}).
2724 @deffn Command scroll-up &optional count
2725 This function scrolls forward by @var{count} lines in the selected
2728 If @var{count} is negative, it scrolls backward instead. If
2729 @var{count} is @code{nil} (or omitted), the distance scrolled is
2730 @code{next-screen-context-lines} lines less than the height of the
2733 If the selected window cannot be scrolled any further, this function
2734 signals an error. Otherwise, it returns @code{nil}.
2737 @deffn Command scroll-down &optional count
2738 This function scrolls backward by @var{count} lines in the selected
2741 If @var{count} is negative, it scrolls forward instead. If
2742 @var{count} is omitted or @code{nil}, the distance scrolled is
2743 @code{next-screen-context-lines} lines less than the height of the
2746 If the selected window cannot be scrolled any further, this function
2747 signals an error. Otherwise, it returns @code{nil}.
2750 @deffn Command scroll-up-command &optional count
2751 This behaves like @code{scroll-up}, except that if the selected window
2752 cannot be scrolled any further and the value of the variable
2753 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
2754 end of the buffer instead. If point is already there, it signals an
2758 @deffn Command scroll-down-command &optional count
2759 This behaves like @code{scroll-down}, except that if the selected
2760 window cannot be scrolled any further and the value of the variable
2761 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
2762 beginning of the buffer instead. If point is already there, it
2766 @deffn Command scroll-other-window &optional count
2767 This function scrolls the text in another window upward @var{count}
2768 lines. Negative values of @var{count}, or @code{nil}, are handled
2769 as in @code{scroll-up}.
2771 You can specify which buffer to scroll by setting the variable
2772 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
2773 already displayed, @code{scroll-other-window} displays it in some
2776 When the selected window is the minibuffer, the next window is normally
2777 the one at the top left corner. You can specify a different window to
2778 scroll, when the minibuffer is selected, by setting the variable
2779 @code{minibuffer-scroll-window}. This variable has no effect when any
2780 other window is selected. When it is non-@code{nil} and the
2781 minibuffer is selected, it takes precedence over
2782 @code{other-window-scroll-buffer}. @xref{Definition of
2783 minibuffer-scroll-window}.
2785 When the minibuffer is active, it is the next window if the selected
2786 window is the one at the bottom right corner. In this case,
2787 @code{scroll-other-window} attempts to scroll the minibuffer. If the
2788 minibuffer contains just one line, it has nowhere to scroll to, so the
2789 line reappears after the echo area momentarily displays the message
2790 @samp{Beginning of buffer}.
2793 @defvar other-window-scroll-buffer
2794 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
2795 which buffer's window to scroll.
2798 @defopt scroll-margin
2799 This option specifies the size of the scroll margin---a minimum number
2800 of lines between point and the top or bottom of a window. Whenever
2801 point gets within this many lines of the top or bottom of the window,
2802 redisplay scrolls the text automatically (if possible) to move point
2803 out of the margin, closer to the center of the window.
2806 @defopt scroll-conservatively
2807 This variable controls how scrolling is done automatically when point
2808 moves off the screen (or into the scroll margin). If the value is a
2809 positive integer @var{n}, then redisplay scrolls the text up to
2810 @var{n} lines in either direction, if that will bring point back into
2811 proper view. This behavior is called @dfn{conservative scrolling}.
2812 Otherwise, scrolling happens in the usual way, under the control of
2813 other variables such as @code{scroll-up-aggressively} and
2814 @code{scroll-down-aggressively}.
2816 The default value is zero, which means that conservative scrolling
2820 @defopt scroll-down-aggressively
2821 The value of this variable should be either @code{nil} or a fraction
2822 @var{f} between 0 and 1. If it is a fraction, that specifies where on
2823 the screen to put point when scrolling down. More precisely, when a
2824 window scrolls down because point is above the window start, the new
2825 start position is chosen to put point @var{f} part of the window
2826 height from the top. The larger @var{f}, the more aggressive the
2829 A value of @code{nil} is equivalent to .5, since its effect is to center
2830 point. This variable automatically becomes buffer-local when set in any
2834 @defopt scroll-up-aggressively
2835 Likewise, for scrolling up. The value, @var{f}, specifies how far
2836 point should be placed from the bottom of the window; thus, as with
2837 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
2841 This variable is an older variant of @code{scroll-conservatively}.
2842 The difference is that if its value is @var{n}, that permits scrolling
2843 only by precisely @var{n} lines, not a smaller number. This feature
2844 does not work with @code{scroll-margin}. The default value is zero.
2847 @cindex @code{scroll-command} property
2848 @defopt scroll-preserve-screen-position
2849 If this option is @code{t}, whenever a scrolling command moves point
2850 off-window, Emacs tries to adjust point to keep the cursor at its old
2851 vertical position in the window, rather than the window edge.
2853 If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
2854 to keep the cursor at the same vertical position, even if the
2855 scrolling command didn't move point off-window.
2857 This option affects all scroll commands that have a non-@code{nil}
2858 @code{scroll-command} symbol property.
2861 @defopt next-screen-context-lines
2862 The value of this variable is the number of lines of continuity to
2863 retain when scrolling by full screens. For example, @code{scroll-up}
2864 with an argument of @code{nil} scrolls so that this many lines at the
2865 bottom of the window appear instead at the top. The default value is
2869 @defopt scroll-error-top-bottom
2870 If this option is @code{nil} (the default), @code{scroll-up-command}
2871 and @code{scroll-down-command} simply signal an error when no more
2872 scrolling is possible.
2874 If the value is @code{t}, these commands instead move point to the
2875 beginning or end of the buffer (depending on scrolling direction);
2876 only if point is already on that position do they signal an error.
2879 @deffn Command recenter &optional count
2880 @cindex centering point
2881 This function scrolls the text in the selected window so that point is
2882 displayed at a specified vertical position within the window. It does
2883 not ``move point'' with respect to the text.
2885 If @var{count} is a non-negative number, that puts the line containing
2886 point @var{count} lines down from the top of the window. If
2887 @var{count} is a negative number, then it counts upward from the
2888 bottom of the window, so that @minus{}1 stands for the last usable
2889 line in the window. If @var{count} is a non-@code{nil} list, then it
2890 stands for the line in the middle of the window.
2892 If @var{count} is @code{nil}, @code{recenter} puts the line containing
2893 point in the middle of the window, then clears and redisplays the entire
2896 When @code{recenter} is called interactively, @var{count} is the raw
2897 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
2898 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
2899 @var{count} to 4, which positions the current line four lines from the
2902 With an argument of zero, @code{recenter} positions the current line at
2903 the top of the window. This action is so handy that some people make a
2904 separate key binding to do this. For example,
2908 (defun line-to-top-of-window ()
2909 "Scroll current line to top of window.
2910 Replaces three keystroke sequence C-u 0 C-l."
2914 (global-set-key [kp-multiply] 'line-to-top-of-window)
2919 @node Vertical Scrolling
2920 @section Vertical Fractional Scrolling
2921 @cindex vertical fractional scrolling
2922 @cindex vertical scroll position
2924 @dfn{Vertical fractional scrolling} means shifting text in a window
2925 up or down by a specified multiple or fraction of a line. Each window
2926 has a @dfn{vertical scroll position}, which is a number, never less than
2927 zero. It specifies how far to raise the contents of the window.
2928 Raising the window contents generally makes all or part of some lines
2929 disappear off the top, and all or part of some other lines appear at the
2930 bottom. The usual value is zero.
2932 The vertical scroll position is measured in units of the normal line
2933 height, which is the height of the default font. Thus, if the value is
2934 .5, that means the window contents are scrolled up half the normal line
2935 height. If it is 3.3, that means the window contents are scrolled up
2936 somewhat over three times the normal line height.
2938 What fraction of a line the vertical scrolling covers, or how many
2939 lines, depends on what the lines contain. A value of .5 could scroll a
2940 line whose height is very short off the screen, while a value of 3.3
2941 could scroll just part of the way through a tall line or an image.
2943 @defun window-vscroll &optional window pixels-p
2944 This function returns the current vertical scroll position of
2945 @var{window}. The default for @var{window} is the selected window.
2946 If @var{pixels-p} is non-@code{nil}, the return value is measured in
2947 pixels, rather than in units of the normal line height.
2957 @defun set-window-vscroll window lines &optional pixels-p
2958 This function sets @var{window}'s vertical scroll position to
2959 @var{lines}. If @var{window} is @code{nil}, the selected window is
2960 used. The argument @var{lines} should be zero or positive; if not, it
2964 The actual vertical scroll position must always correspond
2965 to an integral number of pixels, so the value you specify
2966 is rounded accordingly.
2968 The return value is the result of this rounding.
2972 (set-window-vscroll (selected-window) 1.2)
2977 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
2978 pixels. In this case, the return value is @var{lines}.
2981 @defvar auto-window-vscroll
2982 If this variable is non-@code{nil}, the line-move, scroll-up, and
2983 scroll-down functions will automatically modify the vertical scroll
2984 position to scroll through display rows that are taller than the height
2985 of the window, for example in the presence of large images.
2988 @node Horizontal Scrolling
2989 @section Horizontal Scrolling
2990 @cindex horizontal scrolling
2992 @dfn{Horizontal scrolling} means shifting the image in the window left
2993 or right by a specified multiple of the normal character width. Each
2994 window has a @dfn{horizontal scroll position}, which is a number, never
2995 less than zero. It specifies how far to shift the contents left.
2996 Shifting the window contents left generally makes all or part of some
2997 characters disappear off the left, and all or part of some other
2998 characters appear at the right. The usual value is zero.
3000 The horizontal scroll position is measured in units of the normal
3001 character width, which is the width of space in the default font. Thus,
3002 if the value is 5, that means the window contents are scrolled left by 5
3003 times the normal character width. How many characters actually
3004 disappear off to the left depends on their width, and could vary from
3007 Because we read from side to side in the ``inner loop,'' and from top
3008 to bottom in the ``outer loop,'' the effect of horizontal scrolling is
3009 not like that of textual or vertical scrolling. Textual scrolling
3010 involves selection of a portion of text to display, and vertical
3011 scrolling moves the window contents contiguously; but horizontal
3012 scrolling causes part of @emph{each line} to go off screen.
3014 Usually, no horizontal scrolling is in effect; then the leftmost
3015 column is at the left edge of the window. In this state, scrolling to
3016 the right is meaningless, since there is no data to the left of the edge
3017 to be revealed by it; so this is not allowed. Scrolling to the left is
3018 allowed; it scrolls the first columns of text off the edge of the window
3019 and can reveal additional columns on the right that were truncated
3020 before. Once a window has a nonzero amount of leftward horizontal
3021 scrolling, you can scroll it back to the right, but only so far as to
3022 reduce the net horizontal scroll to zero. There is no limit to how far
3023 left you can scroll, but eventually all the text will disappear off the
3026 @vindex auto-hscroll-mode
3027 If @code{auto-hscroll-mode} is set, redisplay automatically alters
3028 the horizontal scrolling of a window as necessary to ensure that point
3029 is always visible. However, you can still set the horizontal
3030 scrolling value explicitly. The value you specify serves as a lower
3031 bound for automatic scrolling, i.e. automatic scrolling will not
3032 scroll a window to a column less than the specified one.
3034 @deffn Command scroll-left &optional count set-minimum
3035 This function scrolls the selected window @var{count} columns to the
3036 left (or to the right if @var{count} is negative). The default
3037 for @var{count} is the window width, minus 2.
3039 The return value is the total amount of leftward horizontal scrolling in
3040 effect after the change---just like the value returned by
3041 @code{window-hscroll} (below).
3043 Once you scroll a window as far right as it can go, back to its normal
3044 position where the total leftward scrolling is zero, attempts to scroll
3045 any farther right have no effect.
3047 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
3048 the lower bound for automatic scrolling; that is, automatic scrolling
3049 will not scroll a window to a column less than the value returned by
3050 this function. Interactive calls pass non-@code{nil} for
3054 @deffn Command scroll-right &optional count set-minimum
3055 This function scrolls the selected window @var{count} columns to the
3056 right (or to the left if @var{count} is negative). The default
3057 for @var{count} is the window width, minus 2. Aside from the direction
3058 of scrolling, this works just like @code{scroll-left}.
3061 @defun window-hscroll &optional window
3062 This function returns the total leftward horizontal scrolling of
3063 @var{window}---the number of columns by which the text in @var{window}
3064 is scrolled left past the left margin. The default for
3065 @var{window} is the selected window.
3067 The return value is never negative. It is zero when no horizontal
3068 scrolling has been done in @var{window} (which is usually the case).
3087 @defun set-window-hscroll window columns
3088 This function sets horizontal scrolling of @var{window}. The value of
3089 @var{columns} specifies the amount of scrolling, in terms of columns
3090 from the left margin. The argument @var{columns} should be zero or
3091 positive; if not, it is taken as zero. Fractional values of
3092 @var{columns} are not supported at present.
3094 Note that @code{set-window-hscroll} may appear not to work if you test
3095 it by evaluating a call with @kbd{M-:} in a simple way. What happens
3096 is that the function sets the horizontal scroll value and returns, but
3097 then redisplay adjusts the horizontal scrolling to make point visible,
3098 and this overrides what the function did. You can observe the
3099 function's effect if you call it while point is sufficiently far from
3100 the left margin that it will remain visible.
3102 The value returned is @var{columns}.
3106 (set-window-hscroll (selected-window) 10)
3112 Here is how you can determine whether a given position @var{position}
3113 is off the screen due to horizontal scrolling:
3117 (defun hscroll-on-screen (window position)
3119 (goto-char position)
3121 (>= (- (current-column) (window-hscroll window)) 0)
3122 (< (- (current-column) (window-hscroll window))
3123 (window-width window)))))
3128 @node Coordinates and Windows
3129 @section Coordinates and Windows
3131 This section describes how to relate screen coordinates to windows.
3133 @defun window-at x y &optional frame
3134 This function returns the window containing the specified cursor
3135 position in the frame @var{frame}. The coordinates @var{x} and @var{y}
3136 are measured in characters and count from the top left corner of the
3137 frame. If they are out of range, @code{window-at} returns @code{nil}.
3139 If you omit @var{frame}, the selected frame is used.
3142 @defun coordinates-in-window-p coordinates window
3143 This function checks whether a particular frame position falls within
3144 the window @var{window}.
3146 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
3147 . @var{y})}. The coordinates @var{x} and @var{y} are measured in
3148 characters, and count from the top left corner of the screen or frame.
3150 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
3151 if the coordinates are inside @var{window}. The value also indicates
3152 what part of the window the position is in, as follows:
3155 @item (@var{relx} . @var{rely})
3156 The coordinates are inside @var{window}. The numbers @var{relx} and
3157 @var{rely} are the equivalent window-relative coordinates for the
3158 specified position, counting from 0 at the top left corner of the
3162 The coordinates are in the mode line of @var{window}.
3165 The coordinates are in the header line of @var{window}.
3168 The coordinates are in the vertical line between @var{window} and its
3169 neighbor to the right. This value occurs only if the window doesn't
3170 have a scroll bar; positions in a scroll bar are considered outside the
3171 window for these purposes.
3175 The coordinates are in the left or right fringe of the window.
3179 The coordinates are in the left or right margin of the window.
3182 The coordinates are not in any part of @var{window}.
3185 The function @code{coordinates-in-window-p} does not require a frame as
3186 argument because it always uses the frame that @var{window} is on.
3190 @node Window Configurations
3191 @section Window Configurations
3192 @cindex window configurations
3193 @cindex saving window information
3195 A @dfn{window configuration} records the entire layout of one
3196 frame---all windows, their sizes, which buffers they contain, how those
3197 buffers are scrolled, and their values of point and the mark; also their
3198 fringes, margins, and scroll bar settings. It also includes the value
3199 of @code{minibuffer-scroll-window}. As a special exception, the window
3200 configuration does not record the value of point in the selected window
3201 for the current buffer.
3203 You can bring back an entire frame layout by restoring a previously
3204 saved window configuration. If you want to record the layout of all
3205 frames instead of just one, use a frame configuration instead of a
3206 window configuration; see @ref{Frame Configurations}.
3208 @defun current-window-configuration &optional frame
3209 This function returns a new object representing @var{frame}'s current
3210 window configuration. The default for @var{frame} is the selected
3214 @defun set-window-configuration configuration
3215 This function restores the configuration of windows and buffers as
3216 specified by @var{configuration}, for the frame that @var{configuration}
3219 The argument @var{configuration} must be a value that was previously
3220 returned by @code{current-window-configuration}. The configuration is
3221 restored in the frame from which @var{configuration} was made, whether
3222 that frame is selected or not. This always counts as a window size
3223 change and triggers execution of the @code{window-size-change-functions}
3224 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
3225 know how to tell whether the new configuration actually differs from the
3228 If the frame which @var{configuration} was saved from is dead, all this
3229 function does is restore the three variables @code{window-min-height},
3230 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
3231 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
3233 Here is a way of using this function to get the same effect
3234 as @code{save-window-excursion}:
3238 (let ((config (current-window-configuration)))
3240 (progn (split-window-below nil)
3242 (set-window-configuration config)))
3247 @defspec save-window-excursion forms@dots{}
3248 This special form records the window configuration, executes @var{forms}
3249 in sequence, then restores the earlier window configuration. The window
3250 configuration includes, for each window, the value of point and the
3251 portion of the buffer that is visible. It also includes the choice of
3252 selected window. However, it does not include the value of point in
3253 the current buffer; use @code{save-excursion} also, if you wish to
3256 Don't use this construct when @code{save-selected-window} is sufficient.
3258 Exit from @code{save-window-excursion} always triggers execution of
3259 @code{window-size-change-functions}. (It doesn't know how to tell
3260 whether the restored configuration actually differs from the one in
3261 effect at the end of the @var{forms}.)
3263 The return value is the value of the final form in @var{forms}.
3269 @result{} #<window 25 on control.texi>
3272 (setq w (selected-window))
3273 @result{} #<window 19 on control.texi>
3276 (save-window-excursion
3277 (delete-other-windows w)
3278 (switch-to-buffer "foo")
3280 @result{} do-something
3281 ;; @r{The screen is now split again.}
3286 @defun window-configuration-p object
3287 This function returns @code{t} if @var{object} is a window configuration.
3290 @defun compare-window-configurations config1 config2
3291 This function compares two window configurations as regards the
3292 structure of windows, but ignores the values of point and mark and the
3293 saved scrolling positions---it can return @code{t} even if those
3296 The function @code{equal} can also compare two window configurations; it
3297 regards configurations as unequal if they differ in any respect, even a
3298 saved point or mark.
3301 @defun window-configuration-frame config
3302 This function returns the frame for which the window configuration
3303 @var{config} was made.
3306 Other primitives to look inside of window configurations would make
3307 sense, but are not implemented because we did not need them. See the
3308 file @file{winner.el} for some more operations on windows
3311 The objects returned by @code{current-window-configuration} die
3312 together with the Emacs process. In order to store a window
3313 configuration on disk and read it back in another Emacs session the
3314 following two functions can be used.
3316 @defun window-state-get &optional window markers
3317 This function returns the state of @var{window} as a Lisp object. The
3318 argument @var{window} can be any window and defaults to the root window
3319 of the selected frame.
3321 The optional argument @var{markers} non-@code{nil} means to use markers
3322 for sampling positions like @code{window-point} or @code{window-start}.
3323 This argument should be non-@code{nil} only if the value is used for
3324 putting the state back in the same session since markers slow down
3328 The value returned by @code{window-state-get} can be converted by using
3329 one of the functions defined by Desktop Save Mode (@pxref{Desktop Save
3330 Mode}) to an object that can be written to a file. Such objects can be
3331 read back and converted to a Lisp object representing the state of the
3332 window. That Lisp object can be used as argument for the following
3333 function in order to restore the state window in another window.
3335 @defun window-state-put state &optional window ignore
3336 This function puts the window state @var{state} into @var{window}. The
3337 argument @var{state} should be the state of a window returned by an
3338 earlier invocation of @code{window-state-get}, see above. The optional
3339 argument @var{window} must specify a live window and defaults to the
3342 The optional argument @var{ignore} non-@code{nil} means to ignore
3343 minimum window sizes and fixed size restrictions. If @var{ignore}
3344 equals @code{safe}, this means windows can get as small as one line
3349 @node Window Parameters
3350 @section Window Parameters
3351 @cindex window parameters
3353 This section describes how window parameters can be used to associate
3354 additional information with windows.
3356 @defun window-parameter window parameter
3357 This function returns @var{window}'s value for @var{parameter}. The
3358 default for @var{window} is the selected window. If @var{window} has no
3359 setting for @var{parameter}, this function returns @code{nil}.
3362 @defun window-parameters &optional window
3363 This function returns all parameters of @var{window} and their values.
3364 The default for @var{window} is the selected window. The return value,
3365 if non-@code{nil} is an association list whose elements have the form
3366 @code{(@var{parameter} . @var{value})}.
3369 @defun set-window-parameter window parameter value
3370 This function sets @var{window}'s value of @var{parameter} to
3371 @var{value} and returns @var{value}. The default for @var{window}
3372 is the selected window.
3375 Some functions, notably @code{delete-window},
3376 @code{delete-other-windows} and @code{split-window} may behave specially
3377 when their @var{window} argument has a parameter set. You can override
3378 such special behavior by binding the following variable to a
3379 non-@code{nil} value:
3381 @defvar ignore-window-parameters
3382 If this variable is non-@code{nil}, some standard functions do not
3383 process window parameters. The functions currently affected by this are
3384 @code{split-window}, @code{delete-window}, @code{delete-other-windows}
3385 and @code{other-window}.
3387 An application can bind this variable to a non-@code{nil} value around
3388 calls to these functions. If it does so, the application is fully
3389 responsible for correctly assigning the parameters of all involved
3390 windows when exiting that function.
3393 The following parameters are currently used by the window management
3397 @item @code{delete-window}
3398 This parameter affects the execution of @code{delete-window}
3399 (@pxref{Deleting Windows}).
3401 @item @code{delete-other-windows}
3402 This parameter affects the execution of @code{delete-other-windows}
3403 (@pxref{Deleting Windows}).
3405 @item @code{split-window}
3406 This parameter affects the execution of @code{split-window}
3407 (@pxref{Splitting Windows}).
3409 @item @code{other-window}
3410 This parameter affects the execution of @code{other-window}
3411 (@pxref{Cyclic Window Ordering}).
3413 @item @code{no-other-window}
3414 This parameter marks the window as not selectable by @code{other-window}
3415 (@pxref{Cyclic Window Ordering}).
3418 In addition, the parameters @code{window-atom} and @code{window-side}
3419 are reserved and should not be used by applications. The
3420 @code{quit-restore} parameter tells how to proceed with a window when
3421 the buffer it shows is no more needed. This parameter is installed by
3422 the buffer display functions (@pxref{Choosing Window}) and consulted by
3423 the function @code{quit-window} (@pxref{Quitting Windows}).
3427 @section Hooks for Window Scrolling and Changes
3428 @cindex hooks for window operations
3430 This section describes how a Lisp program can take action whenever a
3431 window displays a different part of its buffer or a different buffer.
3432 There are three actions that can change this: scrolling the window,
3433 switching buffers in the window, and changing the size of the window.
3434 The first two actions run @code{window-scroll-functions}; the last runs
3435 @code{window-size-change-functions}.
3437 @defvar window-scroll-functions
3438 This variable holds a list of functions that Emacs should call before
3439 redisplaying a window with scrolling. Displaying a different buffer in
3440 the window also runs these functions.
3442 This variable is not a normal hook, because each function is called with
3443 two arguments: the window, and its new display-start position.
3445 These functions must be careful in using @code{window-end}
3446 (@pxref{Window Start and End}); if you need an up-to-date value, you
3447 must use the @var{update} argument to ensure you get it.
3449 @strong{Warning:} don't use this feature to alter the way the window
3450 is scrolled. It's not designed for that, and such use probably won't
3454 @defvar window-size-change-functions
3455 This variable holds a list of functions to be called if the size of any
3456 window changes for any reason. The functions are called just once per
3457 redisplay, and just once for each frame on which size changes have
3460 Each function receives the frame as its sole argument. There is no
3461 direct way to find out which windows on that frame have changed size, or
3462 precisely how. However, if a size-change function records, at each
3463 call, the existing windows and their sizes, it can also compare the
3464 present sizes and the previous sizes.
3466 Creating or deleting windows counts as a size change, and therefore
3467 causes these functions to be called. Changing the frame size also
3468 counts, because it changes the sizes of the existing windows.
3470 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
3471 Configurations}) in these functions, because that always counts as a
3472 size change, and it would cause these functions to be called over and
3473 over. In most cases, @code{save-selected-window} (@pxref{Selecting
3474 Windows}) is what you need here.
3477 @defvar window-configuration-change-hook
3478 A normal hook that is run every time you change the window configuration
3479 of an existing frame. This includes splitting or deleting windows,
3480 changing the sizes of windows, or displaying a different buffer in a
3483 The buffer-local part of this hook is run once per each window on the
3484 affected frame, with the relevant window selected and its buffer
3485 current. The global part is run once for the modified frame, with that
3489 In addition, you can use @code{jit-lock-register} to register a Font
3490 Lock fontification function, which will be called whenever parts of a
3491 buffer are (re)fontified because a window was scrolled or its size
3492 changed. @xref{Other Font Lock Variables}.