2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
9 This chapter describes the functions and variables related to Emacs
10 windows. @xref{Frames}, for how windows are assigned an area of screen
11 available for Emacs to use. @xref{Display}, for information on how text
12 is displayed in windows.
15 * Basic Windows:: Basic information on using windows.
16 * Windows and Frames:: Relating windows to the frame they appear on.
17 * Window Sizes:: Accessing a window's size.
18 * Resizing Windows:: Changing the sizes of windows.
19 * Splitting Windows:: Splitting one window into two windows.
20 * Deleting Windows:: Deleting a window gives its space to other windows.
21 * Selecting Windows:: The selected window is the one that you edit in.
22 * Cyclic Window Ordering:: Moving around the existing windows.
23 * Buffers and Windows:: Each window displays the contents of a buffer.
24 * Switching Buffers:: Higher-level functions for switching to a buffer.
25 * Choosing Window:: How to choose a window for displaying a buffer.
26 * Display Action Functions:: Subroutines for @code{display-buffer}.
27 * Choosing Window Options:: Extra options affecting how buffers are displayed.
28 * Window History:: Each window remembers the buffers displayed in it.
29 * Dedicated Windows:: How to avoid displaying another buffer in
31 * Quitting Windows:: How to restore the state prior to displaying a
33 * Window Point:: Each window has its own location of point.
34 * Window Start and End:: Buffer positions indicating which text is
35 on-screen in a window.
36 * Textual Scrolling:: Moving text up and down through the window.
37 * Vertical Scrolling:: Moving the contents up and down on the window.
38 * Horizontal Scrolling:: Moving the contents sideways on the window.
39 * Coordinates and Windows:: Converting coordinates to windows.
40 * Window Configurations:: Saving and restoring the state of the screen.
41 * Window Parameters:: Associating additional information with windows.
42 * Window Hooks:: Hooks for scrolling, window size changes,
43 redisplay going past a certain point,
44 or window configuration changes.
49 @section Basic Concepts of Emacs Windows
52 A @dfn{window} is a area of the screen that is used to display a
53 buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a
54 special Lisp object type.
56 @cindex multiple windows
57 Windows are grouped into frames (@pxref{Frames}). Each frame
58 contains at least one window; the user can subdivide it into multiple,
59 non-overlapping windows to view several buffers at once. Lisp
60 programs can use multiple windows for a variety of purposes. In
61 Rmail, for example, you can view a summary of message titles in one
62 window, and the contents of the selected message in another window.
64 @cindex terminal screen
65 @cindex screen of terminal
66 Emacs uses the word ``window'' with a different meaning than in
67 graphical desktop environments and window systems, such as the X
68 Window System. When Emacs is run on X, each of its graphical X
69 windows is an Emacs frame (containing one or more Emacs windows).
70 When Emacs is run on a text terminal, the frame fills the entire
74 Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
75 within the area of the frame. When a window is created, resized, or
76 deleted, the change in window space is taken from or given to the
77 adjacent windows, so that the total area of the frame is unchanged.
80 @cindex internal windows
81 A @dfn{live window} is one that is actually displaying a buffer in a
82 frame. Such a window can be @dfn{deleted}, i.e. removed from the
83 frame (@pxref{Deleting Windows}); then it is no longer live, but the
84 Lisp object representing it might be still referenced from other Lisp
85 objects. A deleted window may be brought back to life by restoring a
86 saved window configuration (@pxref{Window Configurations}).
89 This function returns @code{t} if @var{object} is a window (whether or
90 not it is live). Otherwise, it returns @code{nil}.
93 @defun window-live-p object
94 This function returns @code{t} if @var{object} is a live window and
95 @code{nil} otherwise. A live window is one that displays a buffer.
98 The windows in each frame are organized into a @dfn{window tree}.
99 @xref{Windows and Frames}. The leaf nodes of each window tree are
100 live windows---the ones actually displaying buffers. The internal
101 nodes of the window tree are internal windows, which are not live.
102 You can distinguish internal windows from deleted windows with
103 @code{window-valid-p}.
105 @defun window-valid-p object
106 This function returns @code{t} if @var{object} is a live window, or an
107 internal window in a window tree. Otherwise, it returns @code{nil},
108 including for the case where @var{object} is a deleted window.
111 @cindex selected window
112 @cindex window selected within a frame
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 live
152 window on the specified frame; then @var{window} will be the first
153 element in the returned list. If @var{window} is omitted or @code{nil},
154 the window selected within the frame is the 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 return the next
301 and previous window, respectively, 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, Emacs reports window heights and widths
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 body height
442 @cindex body height of a window
443 @cindex window body width
444 @cindex body width of a window
445 @cindex body size of a window
446 @cindex window body size
447 The @dfn{body height} of a window is the height of its text area,
448 which does not include the mode or header line. Similarly, the
449 @dfn{body width} is the width of the text area, which does not include
450 the scroll bar, fringes, or margins.
452 @defun window-body-height &optional window
453 This function returns the body height, in lines, of the window
454 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
455 to the selected window; otherwise it must be a live window.
457 If there is a partially-visible line at the bottom of the text area,
458 that counts as a whole line; to exclude such a partially-visible line,
459 use @code{window-text-height}, below.
462 @defun window-body-width &optional window
463 This function returns the body width, in columns, of the window
464 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
465 to the selected window; otherwise it must be a live window.
468 @defun window-body-size &optional window horizontal
469 This function returns the body height or body width of @var{window}.
470 If @var{horizontal} is omitted or @code{nil}, it is equivalent to
471 calling @code{window-body-height} for @var{window}; otherwise it is
472 equivalent to calling @code{window-body-width}.
475 @defun window-text-height &optional window
476 This function is like @code{window-body-height}, except that any
477 partially-visible line at the bottom of the text area is not counted.
480 For compatibility with previous versions of Emacs,
481 @code{window-height} is an alias for @code{window-total-height}, and
482 @code{window-width} is an alias for @code{window-body-width}. These
483 aliases are considered obsolete and will be removed in the future.
485 @cindex fixed-size window
486 Commands that change the size of windows (@pxref{Resizing Windows}),
487 or split them (@pxref{Splitting Windows}), obey the variables
488 @code{window-min-height} and @code{window-min-width}, which specify
489 the smallest allowable window height and width. @xref{Change
490 Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
491 Manual}. They also obey the variable @code{window-size-fixed}, with
492 which a window can be @dfn{fixed} in size:
494 @defvar window-size-fixed
495 If this buffer-local variable is non-@code{nil}, the size of any
496 window displaying the buffer cannot normally be changed. Deleting a
497 window or changing the frame's size may still change its size, if
500 If the value is @code{height}, then only the window's height is fixed;
501 if the value is @code{width}, then only the window's width is fixed.
502 Any other non-@code{nil} value fixes both the width and the height.
505 @defun window-size-fixed-p &optional window horizontal
506 This function returns a non-@code{nil} value if @var{window}'s height
507 is fixed. If @var{window} is omitted or @code{nil}, it defaults to
508 the selected window. If the optional argument @var{horizontal} is
509 non-@code{nil}, the return value is non-@code{nil} if @var{window}'s
512 A @code{nil} return value does not necessarily mean that @var{window}
513 can be resized in the desired direction. To determine that, use the
514 function @code{window-resizable}. @xref{Resizing Windows}.
517 @xref{Coordinates and Windows}, for more functions that report the
518 positions of various parts of a window relative to the frame, from
519 which you can calculate its size. In particular, you can use the
520 functions @code{window-pixel-edges} and
521 @code{window-inside-pixel-edges} to find the size in pixels, for
524 @node Resizing Windows
525 @section Resizing Windows
526 @cindex window resizing
527 @cindex resize window
528 @cindex changing window size
529 @cindex window size, changing
531 This section describes functions for resizing a window without
532 changing the size of its frame. Because live windows do not overlap,
533 these functions are meaningful only on frames that contain two or more
534 windows: resizing a window also changes the size of a neighboring
535 window. If there is just one window on a frame, its size cannot be
536 changed except by resizing the frame (@pxref{Size and Position}).
538 Except where noted, these functions also accept internal windows as
539 arguments. Resizing an internal window causes its child windows to be
540 resized to fit the same space.
542 @defun window-resizable window delta &optional horizontal ignore
543 This function returns @var{delta} if the size of @var{window} can be
544 changed vertically by @var{delta} lines. If the optional argument
545 @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
546 @var{window} can be resized horizontally by @var{delta} columns. It
547 does not actually change the window size.
549 If @var{window} is @code{nil}, it defaults to the selected window.
551 A positive value of @var{delta} means to check whether the window can be
552 enlarged by that number of lines or columns; a negative value of
553 @var{delta} means to check whether the window can be shrunk by that many
554 lines or columns. If @var{delta} is non-zero, a return value of 0 means
555 that the window cannot be resized.
557 Normally, the variables @code{window-min-height} and
558 @code{window-min-width} specify the smallest allowable window size.
559 @xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU
560 Emacs Manual}. However, if the optional argument @var{ignore} is
561 non-@code{nil}, this function ignores @code{window-min-height} and
562 @code{window-min-width}, as well as @code{window-size-fixed}.
563 Instead, it considers the minimum-height window to be one consisting
564 of a header (if any), a mode line, plus a text area one line tall; and
565 a minimum-width window as one consisting of fringes, margins, and
566 scroll bar (if any), plus a text area two columns wide.
569 @defun window-resize window delta &optional horizontal ignore
570 This function resizes @var{window} by @var{delta} increments. If
571 @var{horizontal} is @code{nil}, it changes the height by @var{delta}
572 lines; otherwise, it changes the width by @var{delta} columns. A
573 positive @var{delta} means to enlarge the window, and a negative
574 @var{delta} means to shrink it.
576 If @var{window} is @code{nil}, it defaults to the selected window. If
577 the window cannot be resized as demanded, an error is signaled.
579 The optional argument @var{ignore} has the same meaning as for the
580 function @code{window-resizable} above.
582 The choice of which window edges this function alters depends on the
583 values of the option @code{window-combination-resize} and the
584 combination limits of the involved windows; in some cases, it may alter
585 both edges. @xref{Splitting Windows}. To resize by moving only the
586 bottom or right edge of a window, use the function
587 @code{adjust-window-trailing-edge}, below.
590 @c The commands enlarge-window, enlarge-window-horizontally,
591 @c shrink-window, and shrink-window-horizontally are documented in the
592 @c Emacs manual. They are not preferred for calling from Lisp.
594 @defun adjust-window-trailing-edge window delta &optional horizontal
595 This function moves @var{window}'s bottom edge by @var{delta} lines.
596 If optional argument @var{horizontal} is non-@code{nil}, it instead
597 moves the right edge by @var{delta} columns. If @var{window} is
598 @code{nil}, it defaults to the selected window.
600 A positive @var{delta} moves the edge downwards or to the right; a
601 negative @var{delta} moves it upwards or to the left. If the edge
602 cannot be moved as far as specified by @var{delta}, this function
603 moves it as far as possible but does not signal a error.
605 This function tries to resize windows adjacent to the edge that is
606 moved. If this is not possible for some reason (e.g. if that adjacent
607 window is fixed-size), it may resize other windows.
610 The following commands resize windows in more specific ways. When
611 called interactively, they act on the selected window.
613 @deffn Command fit-window-to-buffer &optional window max-height min-height override
614 This command adjusts the height of @var{window} to fit the text in it.
615 It returns non-@code{nil} if it was able to resize @var{window}, and
616 @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
617 defaults to the selected window. Otherwise, it should be a live
620 The optional argument @var{max-height}, if non-@code{nil}, specifies
621 the maximum total height that this function can give @var{window}.
622 The optional argument @var{min-height}, if non-@code{nil}, specifies
623 the minimum total height that it can give, which overrides the
624 variable @code{window-min-height}.
626 If the optional argument @var{override} is non-@code{nil}, this
627 function ignores any size restrictions imposed by
628 @code{window-min-height} and @code{window-min-width}.
631 @deffn Command shrink-window-if-larger-than-buffer &optional window
632 This command attempts to reduce @var{window}'s height as much as
633 possible while still showing its full buffer, but no less than
634 @code{window-min-height} lines. The return value is non-@code{nil} if
635 the window was resized, and @code{nil} otherwise. If @var{window} is
636 omitted or @code{nil}, it defaults to the selected window. Otherwise,
637 it should be a live window.
639 This command does nothing if the window is already too short to
640 display all of its buffer, or if any of the buffer is scrolled
641 off-screen, or if the window is the only live window in its frame.
644 @cindex balancing window sizes
645 @deffn Command balance-windows &optional window-or-frame
646 This function balances windows in a way that gives more space to
647 full-width and/or full-height windows. If @var{window-or-frame}
648 specifies a frame, it balances all windows on that frame. If
649 @var{window-or-frame} specifies a window, it balances only that window
650 and its siblings (@pxref{Windows and Frames}).
653 @deffn Command balance-windows-area
654 This function attempts to give all windows on the selected frame
655 approximately the same share of the screen area. Full-width or
656 full-height windows are not given more space than other windows.
659 @cindex maximizing windows
660 @deffn Command maximize-window &optional window
661 This function attempts to make @var{window} as large as possible, in
662 both dimensions, without resizing its frame or deleting other windows.
663 If @var{window} is omitted or @code{nil}, it defaults to the selected
667 @cindex minimizing windows
668 @deffn Command minimize-window &optional window
669 This function attempts to make @var{window} as small as possible, in
670 both dimensions, without deleting it or resizing its frame. If
671 @var{window} is omitted or @code{nil}, it defaults to the selected
676 @node Splitting Windows
677 @section Splitting Windows
678 @cindex splitting windows
679 @cindex window splitting
681 This section describes functions for creating a new window by
682 @dfn{splitting} an existing one.
684 @deffn Command split-window &optional window size side
685 This function creates a new live window next to the window
686 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
687 to the selected window. That window is ``split'', and reduced in
688 size. The space is taken up by the new window, which is returned.
690 The optional second argument @var{size} determines the sizes of
691 @var{window} and/or the new window. If it is omitted or @code{nil},
692 both windows are given equal sizes; if there is an odd line, it is
693 allocated to the new window. If @var{size} is a positive number,
694 @var{window} is given @var{size} lines (or columns, depending on the
695 value of @var{side}). If @var{size} is a negative number, the new
696 window is given @minus{}@var{size} lines (or columns).
698 If @var{size} is @code{nil}, this function obeys the variables
699 @code{window-min-height} and @code{window-min-width}. @xref{Change
700 Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
701 Manual}. Thus, it signals an error if splitting would result in
702 making a window smaller than those variables specify. However, a
703 non-@code{nil} value for @var{size} causes those variables to be
704 ignored; in that case, the smallest allowable window is considered to
705 be one that has space for a text area one line tall and/or two columns
708 The optional third argument @var{side} determines the position of the
709 new window relative to @var{window}. If it is @code{nil} or
710 @code{below}, the new window is placed below @var{window}. If it is
711 @code{above}, the new window is placed above @var{window}. In both
712 these cases, @var{size} specifies a total window height, in lines.
714 If @var{side} is @code{t} or @code{right}, the new window is placed on
715 the right of @var{window}. If @var{side} is @code{left}, the new
716 window is placed on the left of @var{window}. In both these cases,
717 @var{size} specifies a total window width, in columns.
719 If @var{window} is a live window, the new window inherits various
720 properties from it, including margins and scroll bars. If
721 @var{window} is an internal window, the new window inherits the
722 properties of the window selected within @var{window}'s frame.
724 The behavior of this function may be altered by the window parameters
725 of @var{window}, so long as the variable
726 @code{ignore-window-parameters} is @code{nil}. If the value of
727 the @code{split-window} window parameter is @code{t}, this function
728 ignores all other window parameters. Otherwise, if the value of the
729 @code{split-window} window parameter is a function, that function is
730 called with the arguments @var{window}, @var{size}, and @var{side}, in
731 lieu of the usual action of @code{split-window}. Otherwise, this
732 function obeys the @code{window-atom} or @code{window-side} window
733 parameter, if any. @xref{Window Parameters}.
736 As an example, here is a sequence of @code{split-window} calls that
737 yields the window configuration discussed in @ref{Windows and Frames}.
738 This example demonstrates splitting a live window as well as splitting
739 an internal window. We begin with a frame containing a single window
740 (a live root window), which we denote by @var{W4}. Calling
741 @code{(split-window W4)} yields this window configuration:
745 ______________________________________
746 | ____________________________________ |
750 ||_________________W4_________________||
751 | ____________________________________ |
755 ||_________________W5_________________||
756 |__________________W3__________________|
762 The @code{split-window} call has created a new live window, denoted by
763 @var{W5}. It has also created a new internal window, denoted by
764 @var{W3}, which becomes the root window and the parent of both
765 @var{W4} and @var{W5}.
767 Next, we call @code{(split-window W3 nil 'left)}, passing the
768 internal window @var{W3} as the argument. The result:
772 ______________________________________
773 | ______ ____________________________ |
774 || || __________________________ ||
778 || |||____________W4____________|||
779 || || __________________________ ||
782 || |||____________W5____________|||
783 ||__W2__||_____________W3_____________ |
784 |__________________W1__________________|
789 A new live window @var{W2} is created, to the left of the internal
790 window @var{W3}. A new internal window @var{W1} is created, becoming
793 @defopt window-combination-resize
794 If this variable is @code{nil}, @code{split-window} can only split a
795 window (denoted by @var{window}) if @var{window}'s screen area is large
796 enough to accommodate both itself and the new window.
798 If this variable is @code{t}, @code{split-window} tries to resize all
799 windows that are part of the same combination as @var{window}, in order
800 to accommodate the new window. In particular, this may allow
801 @code{split-window} to succeed even if @var{window} is a fixed-size
802 window or too small to ordinarily split. Furthermore, subsequently
803 resizing or deleting @var{window} may resize all other windows in its
806 The default is @code{nil}. Other values are reserved for future use.
807 The value of this variable is ignored when
808 @code{window-combination-limit} is non-@code{nil} (see below).
811 To illustrate the effect of @code{window-combination-resize},
812 consider the following window configuration:
816 ______________________________________
817 | ____________________________________ |
822 ||_________________W2_________________||
823 | ____________________________________ |
828 ||_________________W3_________________||
829 |__________________W1__________________|
835 If @code{window-combination-resize} is @code{nil}, splitting window
836 @code{W3} leaves the size of @code{W2} unchanged:
840 ______________________________________
841 | ____________________________________ |
846 ||_________________W2_________________||
847 | ____________________________________ |
849 ||_________________W3_________________||
850 | ____________________________________ |
852 ||_________________W4_________________||
853 |__________________W1__________________|
859 If @code{window-combination-resize} is @code{t}, splitting @code{W3}
860 instead leaves all three live windows with approximately the same
865 ______________________________________
866 | ____________________________________ |
869 ||_________________W2_________________||
870 | ____________________________________ |
873 ||_________________W3_________________||
874 | ____________________________________ |
877 ||_________________W4_________________||
878 |__________________W1__________________|
883 @defopt window-combination-limit
884 If the value of this variable is @code{t}, the @code{split-window}
885 function always creates a new internal window. If the value is
886 @code{nil}, the new live window is allowed to share the existing
887 parent window, if one exists, provided the split occurs in the same
888 direction as the existing window combination (otherwise, a new
889 internal window is created anyway). The default is @code{nil}. Other
890 values are reserved for future use.
892 Thus, if the value of this variable is at all times @code{t}, then at
893 all times every window tree is a binary tree (a tree where each window
894 except the root window has exactly one sibling).
896 Furthermore, @code{split-window} calls
897 @code{set-window-combination-limit} on the newly-created internal
898 window, recording the current value of this variable. This affects
899 how the window tree is rearranged when the child windows are deleted
903 @cindex window combination limit
904 @defun set-window-combination-limit window limit
905 This functions sets the @dfn{combination limit} of the window
906 @var{window} to @var{limit}. This value can be retrieved via the
907 function @code{window-combination-limit}. See below for its effects;
908 note that it is only meaningful for internal windows. The
909 @code{split-window} function automatically calls this function, passing
910 the value of the variable @code{window-combination-limit} as
914 @defun window-combination-limit window
915 This function returns the combination limit for @var{window}.
917 The combination limit is meaningful only for an internal window. If
918 it is @code{nil}, then Emacs is allowed to automatically delete
919 @var{window}, in response to a window deletion, in order to group the
920 child windows of @var{window} with its sibling windows to form a new
921 window combination. If the combination limit is @code{t}, the child
922 windows of @var{window} are never automatically re-combined with its
926 To illustrate the effect of @code{window-combination-limit},
927 consider the following configuration (throughout this example, we will
928 assume that @code{window-combination-resize} is @code{nil}):
932 ______________________________________
933 | ____________________________________ |
940 ||_________________W2_________________||
941 | ____________________________________ |
944 ||_________________W3_________________||
945 |__________________W1__________________|
951 If @code{window-combination-limit} is @code{nil}, splitting @code{W2}
952 into two windows, one above the other, yields
956 ______________________________________
957 | ____________________________________ |
960 ||_________________W2_________________||
961 | ____________________________________ |
964 ||_________________W4_________________||
965 | ____________________________________ |
968 ||_________________W3_________________||
969 |__________________W1__________________|
975 The newly-created window, @code{W4}, shares the same internal window
976 @code{W1}. If @code{W4} is resized, it is allowed to resize the other
977 live window, @code{W3}.
979 If @code{window-combination-limit} is @code{t}, splitting @code{W2}
980 in the initial configuration would instead have produced this:
984 ______________________________________
985 | ____________________________________ |
986 || __________________________________ ||
988 |||________________W2________________|||
989 || __________________________________ ||
991 |||________________W4________________|||
992 ||_________________W5_________________||
993 | ____________________________________ |
996 ||_________________W3_________________||
997 |__________________W1__________________|
1003 A new internal window @code{W5} has been created; its children are
1004 @code{W2} and the new live window @code{W4}. Now, @code{W2} is the
1005 only sibling of @code{W4}, so resizing @code{W4} will resize
1006 @code{W2}, leaving @code{W3} unaffected.
1008 For interactive use, Emacs provides two commands which always split
1009 the selected window. These call @code{split-window} internally.
1011 @deffn Command split-window-right &optional size
1012 This function splits the selected window into two side-by-side
1013 windows, putting the selected window on the left. If @var{size} is
1014 positive, the left window gets @var{size} columns; if @var{size} is
1015 negative, the right window gets @minus{}@var{size} columns.
1018 @deffn Command split-window-below &optional size
1019 This function splits the selected window into two windows, one above
1020 the other, leaving the upper window selected. If @var{size} is
1021 positive, the upper window gets @var{size} lines; if @var{size} is
1022 negative, the lower window gets @minus{}@var{size} lines.
1025 @defopt split-window-keep-point
1026 If the value of this variable is non-@code{nil} (the default),
1027 @code{split-window-below} behaves as described above.
1029 If it is @code{nil}, @code{split-window-below} adjusts point in each
1030 of the two windows to minimize redisplay. (This is useful on slow
1031 terminals.) It selects whichever window contains the screen line that
1032 point was previously on. Note that this only affects
1033 @code{split-window-below}, not the lower-level @code{split-window}
1037 @node Deleting Windows
1038 @section Deleting Windows
1039 @cindex deleting windows
1041 @dfn{Deleting} a window removes it from the frame's window tree. If
1042 the window is a live window, it disappears from the screen. If the
1043 window is an internal window, its child windows are deleted too.
1045 Even after a window is deleted, it continues to exist as a Lisp
1046 object, until there are no more references to it. Window deletion can
1047 be reversed, by restoring a saved window configuration (@pxref{Window
1050 @deffn Command delete-window &optional window
1051 This function removes @var{window} from display and returns
1052 @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
1053 the selected window. If deleting the window would leave no more
1054 windows in the window tree (e.g. if it is the only live window in the
1055 frame), an error is signaled.
1057 By default, the space taken up by @var{window} is given to one of its
1058 adjacent sibling windows, if any. However, if the variable
1059 @code{window-combination-resize} is non-@code{nil}, the space is
1060 proportionally distributed among any remaining windows in the window
1061 combination. @xref{Splitting Windows}.
1063 The behavior of this function may be altered by the window parameters
1064 of @var{window}, so long as the variable
1065 @code{ignore-window-parameters} is @code{nil}. If the value of
1066 the @code{delete-window} window parameter is @code{t}, this function
1067 ignores all other window parameters. Otherwise, if the value of the
1068 @code{delete-window} window parameter is a function, that function is
1069 called with the argument @var{window}, in lieu of the usual action of
1070 @code{delete-window}. Otherwise, this function obeys the
1071 @code{window-atom} or @code{window-side} window parameter, if any.
1072 @xref{Window Parameters}.
1075 @deffn Command delete-other-windows &optional window
1076 This function makes @var{window} fill its frame, by deleting other
1077 windows as necessary. If @var{window} is omitted or @code{nil}, it
1078 defaults to the selected window. The return value is @code{nil}.
1080 The behavior of this function may be altered by the window parameters
1081 of @var{window}, so long as the variable
1082 @code{ignore-window-parameters} is @code{nil}. If the value of
1083 the @code{delete-other-windows} window parameter is @code{t}, this
1084 function ignores all other window parameters. Otherwise, if the value
1085 of the @code{delete-other-windows} window parameter is a function,
1086 that function is called with the argument @var{window}, in lieu of the
1087 usual action of @code{delete-other-windows}. Otherwise, this function
1088 obeys the @code{window-atom} or @code{window-side} window parameter,
1089 if any. @xref{Window Parameters}.
1092 @deffn Command delete-windows-on &optional buffer-or-name frame
1093 This function deletes all windows showing @var{buffer-or-name}, by
1094 calling @code{delete-window} on those windows. @var{buffer-or-name}
1095 should be a buffer, or the name of a buffer; if omitted or @code{nil},
1096 it defaults to the current buffer. If there are no windows showing
1097 the specified buffer, this function does nothing. If the specified
1098 buffer is a minibuffer, an error is signaled.
1100 If there is a dedicated window showing the buffer, and that window is
1101 the only one on its frame, this function also deletes that frame if it
1102 is not the only frame on the terminal.
1104 The optional argument @var{frame} specifies which frames to operate
1109 means operate on all frames.
1111 means operate on the selected frame.
1112 @item @code{visible}
1113 means operate on all visible frames.
1115 means operate on all visible or iconified frames.
1117 means operate on that frame.
1120 Note that this argument does not have the same meaning as in other
1121 functions which scan all live windows (@pxref{Cyclic Window
1122 Ordering}). Specifically, the meanings of @code{t} and @code{nil} here
1123 are the opposite of what they are in those other functions.
1126 @node Selecting Windows
1127 @section Selecting Windows
1128 @cindex selecting a window
1130 @defun select-window window &optional norecord
1131 This function makes @var{window} the selected window, as well as the
1132 window selected within its frame (@pxref{Basic Windows}). @var{window}
1133 must be a live window. This function makes also @var{window}'s buffer
1134 current (@pxref{Buffers and Windows}). The return value is
1137 By default, this function also moves @var{window}'s buffer to the front
1138 of the buffer list (@pxref{The Buffer List}), and makes @var{window} the
1139 most recently selected window. However, if the optional argument
1140 @var{norecord} is non-@code{nil}, these additional actions are omitted.
1143 @cindex most recently selected windows
1144 The sequence of calls to @code{select-window} with a non-@code{nil}
1145 @var{norecord} argument determines an ordering of windows by their
1146 selection time. The function @code{get-lru-window} can be used to
1147 retrieve the least recently selected live window (@pxref{Cyclic Window
1150 @defmac save-selected-window forms@dots{}
1151 This macro records the selected frame, as well as the selected window
1152 of each frame, executes @var{forms} in sequence, then restores the
1153 earlier selected frame and windows. It also saves and restores the
1154 current buffer. It returns the value of the last form in @var{forms}.
1156 This macro does not save or restore anything about the sizes,
1157 arrangement or contents of windows; therefore, if @var{forms} change
1158 them, the change persists. If the previously selected window of some
1159 frame is no longer live at the time of exit from @var{forms}, that
1160 frame's selected window is left alone. If the previously selected
1161 window is no longer live, then whatever window is selected at the end of
1162 @var{forms} remains selected. The current buffer is restored if and
1163 only if it is still live when exiting @var{forms}.
1165 This macro changes neither the ordering of recently selected windows nor
1169 @defmac with-selected-window window forms@dots{}
1170 This macro selects @var{window}, executes @var{forms} in sequence, then
1171 restores the previously selected window and current buffer. The ordering
1172 of recently selected windows and the buffer list remain unchanged unless
1173 you deliberately change them within @var{forms}; for example, by calling
1174 @code{select-window} with argument @var{norecord} @code{nil}.
1176 This macro does not change the order of recently selected windows or
1180 @defun frame-selected-window &optional frame
1181 This function returns the window on @var{frame} that is selected
1182 within that frame. @var{frame} should be a live frame; if omitted or
1183 @code{nil}, it defaults to the selected frame.
1186 @defun set-frame-selected-window frame window &optional norecord
1187 This function makes @var{window} the window selected within the frame
1188 @var{frame}. @var{frame} should be a live frame; if omitted or
1189 @code{nil}, it defaults to the selected frame. @var{window} should be
1190 a live window; if omitted or @code{nil}, it defaults to the selected
1193 If @var{frame} is the selected frame, this makes @var{window} the
1196 If the optional argument @var{norecord} is non-@code{nil}, this
1197 function does not alter the list of most recently selected windows,
1198 nor the buffer list.
1201 @node Cyclic Window Ordering
1202 @section Cyclic Ordering of Windows
1203 @cindex cyclic ordering of windows
1204 @cindex ordering of windows, cyclic
1205 @cindex window ordering, cyclic
1207 When you use the command @kbd{C-x o} (@code{other-window}) to select
1208 some other window, it moves through live windows in a specific order.
1209 For any given configuration of windows, this order never varies. It
1210 is called the @dfn{cyclic ordering of windows}.
1212 The ordering is determined by a depth-first traversal of the frame's
1213 window tree, retrieving the live windows which are the leaf nodes of
1214 the tree (@pxref{Windows and Frames}). If the minibuffer is active,
1215 the minibuffer window is included too. The ordering is cyclic, so the
1216 last window in the sequence is followed by the first one.
1218 @defun next-window &optional window minibuf all-frames
1219 @cindex minibuffer window, and @code{next-window}
1220 This function returns a live window, the one following @var{window} in
1221 the cyclic ordering of windows. @var{window} should be a live window;
1222 if omitted or @code{nil}, it defaults to the selected window.
1224 The optional argument @var{minibuf} specifies whether minibuffer windows
1225 should be included in the cyclic ordering. Normally, when @var{minibuf}
1226 is @code{nil}, a minibuffer window is included only if it is currently
1227 ``active''; this matches the behavior of @kbd{C-x o}. (Note that a
1228 minibuffer window is active as long as its minibuffer is in use; see
1231 If @var{minibuf} is @code{t}, the cyclic ordering includes all
1232 minibuffer windows. If @var{minibuf} is neither @code{t} nor
1233 @code{nil}, minibuffer windows are not included even if they are active.
1235 The optional argument @var{all-frames} specifies which frames to
1240 means to consider windows on @var{window}'s frame. If the minibuffer
1241 window is considered (as specified by the @var{minibuf} argument),
1242 then frames that share the minibuffer window are considered too.
1245 means to consider windows on all existing frames.
1247 @item @code{visible}
1248 means to consider windows on all visible frames.
1251 means to consider windows on all visible or iconified frames.
1254 means to consider windows on that specific frame.
1257 means to consider windows on @var{window}'s frame, and no others.
1260 If more than one frame is considered, the cyclic ordering is obtained
1261 by appending the orderings for those frames, in the same order as the
1262 list of all live frames (@pxref{Finding All Frames}).
1265 @defun previous-window &optional window minibuf all-frames
1266 This function returns a live window, the one preceding @var{window} in
1267 the cyclic ordering of windows. The other arguments are handled like
1268 in @code{next-window}.
1271 @deffn Command other-window count &optional all-frames
1272 This function selects a live window, one @var{count} places from the
1273 selected window in the cyclic ordering of windows. If @var{count} is
1274 a positive number, it skips @var{count} windows forwards; if
1275 @var{count} is negative, it skips @minus{}@var{count} windows
1276 backwards; if @var{count} is zero, that simply re-selects the selected
1277 window. When called interactively, @var{count} is the numeric prefix
1280 The optional argument @var{all-frames} has the same meaning as in
1281 @code{next-window}, like a @code{nil} @var{minibuf} argument to
1284 This function does not select a window that has a non-@code{nil}
1285 @code{no-other-window} window parameter (@pxref{Window Parameters}).
1288 @defun walk-windows fun &optional minibuf all-frames
1289 This function calls the function @var{fun} once for each live window,
1290 with the window as the argument.
1292 It follows the cyclic ordering of windows. The optional arguments
1293 @var{minibuf} and @var{all-frames} specify the set of windows
1294 included; these have the same arguments as in @code{next-window}. If
1295 @var{all-frames} specifies a frame, the first window walked is the
1296 first window on that frame (the one returned by
1297 @code{frame-first-window}), not necessarily the selected window.
1299 If @var{fun} changes the window configuration by splitting or deleting
1300 windows, that does not alter the set of windows walked, which is
1301 determined prior to calling @var{fun} for the first time.
1304 @defun one-window-p &optional no-mini all-frames
1305 This function returns @code{t} if the selected window is the only live
1306 window, and @code{nil} otherwise.
1308 If the minibuffer window is active, it is normally considered (so that
1309 this function returns @code{nil}). However, if the optional argument
1310 @var{no-mini} is non-@code{nil}, the minibuffer window is ignored even
1311 if active. The optional argument @var{all-frames} has the same
1312 meaning as for @code{next-window}.
1315 @cindex finding windows
1316 The following functions return a window which satisfies some
1317 criterion, without selecting it:
1319 @cindex least recently used window
1320 @defun get-lru-window &optional all-frames dedicated
1321 This function returns a live window which is heuristically the ``least
1322 recently used'' window. The optional argument @var{all-frames} has
1323 the same meaning as in @code{next-window}.
1325 If any full-width windows are present, only those windows are
1326 considered. The selected window is never returned, unless it is the
1327 only candidate. A minibuffer window is never a candidate. A
1328 dedicated window (@pxref{Dedicated Windows}) is never a candidate
1329 unless the optional argument @var{dedicated} is non-@code{nil}.
1332 @cindex largest window
1333 @defun get-largest-window &optional all-frames dedicated
1334 This function returns the window with the largest area (height times
1335 width). A minibuffer window is never a candidate. A dedicated window
1336 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1337 argument @var{dedicated} is non-@code{nil}.
1339 If there are two candidate windows of the same size, this function
1340 prefers the one that comes first in the cyclic ordering of windows,
1341 starting from the selected window.
1343 The optional argument @var{all-frames} specifies the windows to
1344 search, and has the same meaning as in @code{next-window}.
1347 @cindex window that satisfies a predicate
1348 @cindex conditional selection of windows
1349 @defun get-window-with-predicate predicate &optional minibuf all-frames default
1350 This function calls the function @var{predicate} for each of the
1351 windows in the cyclic order of windows in turn, passing it the window
1352 as an argument. If the predicate returns non-@code{nil} for any
1353 window, this function stops and returns that window. If no such
1354 window is found, the return value is @var{default} (which defaults to
1357 The optional arguments @var{minibuf} and @var{all-frames} specify the
1358 windows to search, and have the same meanings as in
1362 @node Buffers and Windows
1363 @section Buffers and Windows
1364 @cindex examining windows
1365 @cindex windows, controlling precisely
1366 @cindex buffers, controlled in windows
1368 This section describes low-level functions for examining and setting
1369 the contents of windows. @xref{Switching Buffers}, for higher-level
1370 functions for displaying a specific buffer in a window.
1372 @defun window-buffer &optional window
1373 This function returns the buffer that @var{window} is displaying. If
1374 @var{window} is omitted or @code{nil} it defaults to the selected
1375 window. If @var{window} is an internal window, this function returns
1379 @defun set-window-buffer window buffer-or-name &optional keep-margins
1380 This function makes @var{window} display @var{buffer-or-name}.
1381 @var{window} should be a live window; if @code{nil}, it defaults to
1382 the selected window. @var{buffer-or-name} should be a buffer, or the
1383 name of an existing buffer. This function does not change which
1384 window is selected, nor does it directly change which buffer is
1385 current (@pxref{Current Buffer}). Its return value is @code{nil}.
1387 If @var{window} is @dfn{strongly dedicated} to a buffer and
1388 @var{buffer-or-name} does not specify that buffer, this function
1389 signals an error. @xref{Dedicated Windows}.
1391 By default, this function resets @var{window}'s position, display
1392 margins, fringe widths, and scroll bar settings, based on the local
1393 variables in the specified buffer. However, if the optional argument
1394 @var{keep-margins} is non-@code{nil}, it leaves the display margins
1395 and fringe widths unchanged.
1397 When writing an application, you should normally use the higher-level
1398 functions described in @ref{Switching Buffers}, instead of calling
1399 @code{set-window-buffer} directly.
1401 This runs @code{window-scroll-functions}, followed by
1402 @code{window-configuration-change-hook}. @xref{Window Hooks}.
1405 @defvar buffer-display-count
1406 This buffer-local variable records the number of times a buffer has been
1407 displayed in a window. It is incremented each time
1408 @code{set-window-buffer} is called for the buffer.
1411 @defvar buffer-display-time
1412 This buffer-local variable records the time at which a buffer was last
1413 displayed in a window. The value is @code{nil} if the buffer has
1414 never been displayed. It is updated each time
1415 @code{set-window-buffer} is called for the buffer, with the value
1416 returned by @code{current-time} (@pxref{Time of Day}).
1419 @defun get-buffer-window &optional buffer-or-name all-frames
1420 This function returns the first window displaying @var{buffer-or-name}
1421 in the cyclic ordering of windows, starting from the selected window
1422 (@pxref{Cyclic Window Ordering}). If no such window exists, the
1423 return value is @code{nil}.
1425 @var{buffer-or-name} should be a buffer or the name of a buffer; if
1426 omitted or @code{nil}, it defaults to the current buffer. The
1427 optional argument @var{all-frames} specifies which windows to
1432 @code{t} means consider windows on all existing frames.
1434 @code{visible} means consider windows on all visible frames.
1436 0 means consider windows on all visible or iconified frames.
1438 A frame means consider windows on that frame only.
1440 Any other value means consider windows on the selected frame.
1443 Note that these meanings differ slightly from those of the
1444 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
1445 Ordering}). This function may be changed in a future version of Emacs
1446 to eliminate this discrepancy.
1449 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
1450 This function returns a list of all windows currently displaying
1451 @var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the
1452 name of an existing buffer. If omitted or @code{nil}, it defaults to
1455 The arguments @var{minibuf} and @var{all-frames} have the same
1456 meanings as in the function @code{next-window} (@pxref{Cyclic Window
1457 Ordering}). Note that the @var{all-frames} argument does @emph{not}
1458 behave exactly like in @code{get-buffer-window}.
1461 @deffn Command replace-buffer-in-windows &optional buffer-or-name
1462 This command replaces @var{buffer-or-name} with some other buffer, in
1463 all windows displaying it. @var{buffer-or-name} should be a buffer,
1464 or the name of an existing buffer; if omitted or @code{nil}, it
1465 defaults to the current buffer.
1467 The replacement buffer in each window is chosen via
1468 @code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated
1469 window displaying @var{buffer-or-name} is deleted (@pxref{Dedicated
1470 Windows}), unless it is the only window on its frame---if it is the
1471 only window, and that frame is not the only frame on its terminal, the
1472 frame is ``dismissed'' by calling the function specified by
1473 @code{frame-auto-hide-function} (@pxref{Quitting Windows}). If the
1474 dedicated window is the only window on the only frame on its terminal,
1475 the buffer is replaced anyway.
1478 @node Switching Buffers
1479 @section Switching to a Buffer in a Window
1480 @cindex switching to a buffer
1481 @cindex displaying a buffer
1483 This section describes high-level functions for switching to a
1484 specified buffer in some window.
1486 Do @emph{not} use these functions to make a buffer temporarily
1487 current just so a Lisp program can access or modify it. They have
1488 side-effects, such as changing window histories (@pxref{Window
1489 History}), which will surprise the user if used that way. If you want
1490 to make a buffer current to modify it in Lisp, use
1491 @code{with-current-buffer}, @code{save-current-buffer}, or
1492 @code{set-buffer}. @xref{Current Buffer}.
1494 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
1495 This command attempts to display @var{buffer-or-name} in the selected
1496 window, and makes it the current buffer. It is often used
1497 interactively (as the binding of @kbd{C-x b}), as well as in Lisp
1498 programs. The return value is the buffer switched to.
1500 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
1501 returned by @code{other-buffer} (@pxref{The Buffer List}). If
1502 @var{buffer-or-name} is a string that is not the name of any existing
1503 buffer, this function creates a new buffer with that name; the new
1504 buffer's major mode is determined by the variable @code{major-mode}
1505 (@pxref{Major Modes}).
1507 Normally, the specified buffer is put at the front of the buffer
1508 list---both the global buffer list and the selected frame's buffer
1509 list (@pxref{The Buffer List}). However, this is not done if the
1510 optional argument @var{norecord} is non-@code{nil}.
1512 Sometimes, @code{switch-to-buffer} may be unable to display the buffer
1513 in the selected window. This happens if the selected window is a
1514 minibuffer window, or if the selected window is strongly dedicated to
1515 its buffer (@pxref{Dedicated Windows}). In that case, the command
1516 normally tries to display the buffer in some other window, by invoking
1517 @code{pop-to-buffer} (see below). However, if the optional argument
1518 @var{force-same-window} is non-@code{nil}, it signals an error
1522 The next two functions are similar to @code{switch-to-buffer}, except
1523 for the described features.
1525 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
1526 This function makes the buffer specified by @var{buffer-or-name}
1527 current and displays it in some window other than the selected window.
1528 It uses the function @code{pop-to-buffer} internally (see below).
1530 If the selected window already displays the specified buffer, it
1531 continues to do so, but another window is nonetheless found to display
1534 The @var{buffer-or-name} and @var{norecord} arguments have the same
1535 meanings as in @code{switch-to-buffer}.
1538 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
1539 This function makes the buffer specified by @var{buffer-or-name}
1540 current and displays it, usually in a new frame. It uses the function
1541 @code{pop-to-buffer} (see below).
1543 If the specified buffer is already displayed in another window, in any
1544 frame on the current terminal, this switches to that window instead of
1545 creating a new frame. However, the selected window is never used for
1548 The @var{buffer-or-name} and @var{norecord} arguments have the same
1549 meanings as in @code{switch-to-buffer}.
1552 The above commands use the function @code{pop-to-buffer}, which
1553 flexibly displays a buffer in some window and selects that window for
1554 editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for
1555 displaying the buffer. Hence, all the variables affecting
1556 @code{display-buffer} will affect it as well. @xref{Choosing Window},
1557 for the documentation of @code{display-buffer}.
1559 @deffn Command pop-to-buffer buffer-or-name &optional action norecord
1560 This function makes @var{buffer-or-name} the current buffer and
1561 displays it in some window, preferably not the window previously
1562 selected. It then selects the displaying window. If that window is
1563 on a different graphical frame, that frame is given input focus if
1564 possible (@pxref{Input Focus}). The return value is the buffer that
1567 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
1568 returned by @code{other-buffer} (@pxref{The Buffer List}). If
1569 @var{buffer-or-name} is a string that is not the name of any existing
1570 buffer, this function creates a new buffer with that name; the new
1571 buffer's major mode is determined by the variable @code{major-mode}
1572 (@pxref{Major Modes}).
1574 If @var{action} is non-@code{nil}, it should be a display action to
1575 pass to @code{display-buffer} (@pxref{Choosing Window}).
1576 Alternatively, a non-@code{nil}, non-list value means to pop to a
1577 window other than the selected one---even if the buffer is already
1578 displayed in the selected window.
1580 Like @code{switch-to-buffer}, this function updates the buffer list
1581 unless @var{norecord} is non-@code{nil}.
1584 @node Choosing Window
1585 @section Choosing a Window for Display
1587 The command @code{display-buffer} flexibly chooses a window for
1588 display, and displays a specified buffer in that window. It can be
1589 called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
1590 used as a subroutine by many functions and commands, including
1591 @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
1594 @cindex display action
1595 @cindex action function, for @code{display-buffer}
1596 @cindex action alist, for @code{display-buffer}
1597 This command performs several complex steps to find a window to
1598 display in. These steps are described by means of @dfn{display
1599 actions}, which have the form @code{(@var{function} . @var{alist})}.
1600 Here, @var{function} is either a function or a list of functions,
1601 which we refer to as @dfn{action functions}; @var{alist} is an
1602 association list, which we refer to as @dfn{action alists}.
1604 An action function accepts two arguments: the buffer to display and
1605 an action alist. It attempts to display the buffer in some window,
1606 picking or creating a window according to its own criteria. If
1607 successful, it returns the window; otherwise, it returns @code{nil}.
1608 @xref{Display Action Functions}, for a list of predefined action
1611 @code{display-buffer} works by combining display actions from
1612 several sources, and calling the action functions in turn, until one
1613 of them manages to display the buffer and returns a non-@code{nil}
1616 @deffn Command display-buffer buffer-or-name &optional action frame
1617 This command makes @var{buffer-or-name} appear in some window, without
1618 selecting the window or making the buffer current. The argument
1619 @var{buffer-or-name} must be a buffer or the name of an existing
1620 buffer. The return value is the window chosen to display the buffer.
1622 The optional argument @var{action}, if non-@code{nil}, should normally
1623 be a display action (described above). @code{display-buffer} builds a
1624 list of action functions and an action alist, by consolidating display
1625 actions from the following sources (in order):
1629 The variable @code{display-buffer-overriding-action}.
1632 The user option @code{display-buffer-alist}.
1635 The @var{action} argument.
1638 The user option @code{display-buffer-base-action}.
1641 The constant @code{display-buffer-fallback-action}.
1645 Each action function is called in turn, passing the buffer as the
1646 first argument and the combined action alist as the second argument,
1647 until one of the functions returns non-@code{nil}.
1649 The argument @var{action} can also have a non-@code{nil}, non-list
1650 value. This has the special meaning that the buffer should be
1651 displayed in a window other than the selected one, even if the
1652 selected window is already displaying it. If called interactively
1653 with a prefix argument, @var{action} is @code{t}.
1655 The optional argument @var{frame}, if non-@code{nil}, specifies which
1656 frames to check when deciding whether the buffer is already displayed.
1657 It is equivalent to adding an element @code{(reusable-frames
1658 . @var{frame})} to the action alist of @var{action}. @xref{Display
1662 @defvar display-buffer-overriding-action
1663 The value of this variable should be a display action, which is
1664 treated with the highest priority by @code{display-buffer}. The
1665 default value is empty, i.e. @code{(nil . nil)}.
1668 @defopt display-buffer-alist
1669 The value of this option is an alist mapping regular expressions to
1670 display actions. If the name of the buffer passed to
1671 @code{display-buffer} matches a regular expression in this alist, then
1672 @code{display-buffer} uses the corresponding display action.
1675 @defopt display-buffer-base-action
1676 The value of this option should be a display action. This option can
1677 be used to define a ``standard'' display action for calls to
1678 @code{display-buffer}.
1681 @defvr Constant display-buffer-fallback-action
1682 This display action specifies the fallback behavior for
1683 @code{display-buffer} if no other display actions are given.
1686 @node Display Action Functions
1687 @section Action Functions for @code{display-buffer}
1689 The following basic action functions are defined in Emacs. Each of
1690 these functions takes two arguments: @var{buffer}, the buffer to
1691 display, and @var{alist}, an action alist. Each action function
1692 returns the window if it succeeds, and @code{nil} if it fails.
1694 @defun display-buffer-same-window buffer alist
1695 This function tries to display @var{buffer} in the selected window.
1696 It fails if the selected window is a minibuffer window or is dedicated
1697 to another buffer (@pxref{Dedicated Windows}). It also fails if
1698 @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
1701 @defun display-buffer-reuse-window buffer alist
1702 This function tries to ``display'' @var{buffer} by finding a window
1703 that is already displaying it.
1705 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
1706 the selected window is not eligible for reuse. If @var{alist}
1707 contains a @code{reusable-frames} entry, its value determines which
1708 frames to search for a reusable window:
1712 @code{nil} means consider windows on the selected frame.
1713 (Actually, the last non-minibuffer frame.)
1715 @code{t} means consider windows on all frames.
1717 @code{visible} means consider windows on all visible frames.
1719 0 means consider windows on all visible or iconified frames.
1721 A frame means consider windows on that frame only.
1724 If @var{alist} contains no @code{reusable-frames} entry, this function
1725 normally searches just the selected frame; however, if the variable
1726 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
1727 current terminal. @xref{Choosing Window Options}.
1729 If this function chooses a window on another frame, it makes that
1730 frame visible and raises it if necessary.
1733 @defun display-buffer-pop-up-frame buffer alist
1734 This function creates a new frame, and displays the buffer in that
1735 frame's window. It actually performs the frame creation by calling
1736 the function specified in @code{pop-up-frame-function}
1737 (@pxref{Choosing Window Options}).
1740 @defun display-buffer-pop-up-window buffer alist
1741 This function tries to display @var{buffer} by splitting the largest
1742 or least recently-used window (typically one on the selected frame).
1743 It actually performs the split by calling the function specified in
1744 @code{split-window-preferred-function} (@pxref{Choosing Window
1747 It can fail if no window splitting can be performed for some reason
1748 (e.g. if there is just one frame and it has an @code{unsplittable}
1749 frame parameter; @pxref{Buffer Parameters}).
1752 @defun display-buffer-use-some-window buffer alist
1753 This function tries to display @var{buffer} by choosing an existing
1754 window and displaying the buffer in that window. It can fail if all
1755 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
1758 @node Choosing Window Options
1759 @section Additional Options for Displaying Buffers
1761 The behavior of the standard display actions of @code{display-buffer}
1762 (@pxref{Choosing Window}) can be modified by a variety of user
1765 @defopt pop-up-windows
1766 If the value of this variable is non-@code{nil}, @code{display-buffer}
1767 is allowed to split an existing window to make a new window for
1768 displaying in. This is the default.
1770 This variable is provided mainly for backward compatibility. It is
1771 obeyed by @code{display-buffer} via a special mechanism in
1772 @code{display-buffer-fallback-action}, which only calls the action
1773 function @code{display-buffer-pop-up-window} (@pxref{Display Action
1774 Functions}) when the value is @code{nil}. It is not consulted by
1775 @code{display-buffer-pop-up-window} itself, which the user may specify
1776 directly in @code{display-buffer-alist} etc.
1779 @defopt split-window-preferred-function
1780 This variable specifies a function for splitting a window, in order to
1781 make a new window for displaying a buffer. It is used by the
1782 @code{display-buffer-pop-up-window} action function to actually split
1783 the window (@pxref{Display Action Functions}).
1785 The default value is @code{split-window-sensibly}, which is documented
1786 below. The value must be a function that takes one argument, a
1787 window, and return either a new window (which is used to display the
1788 desired buffer) or @code{nil} (which means the splitting failed).
1791 @defun split-window-sensibly window
1792 This function tries to split @var{window}, and return the newly
1793 created window. If @var{window} cannot be split, it returns
1796 This function obeys the usual rules that determine when a window may
1797 be split (@pxref{Splitting Windows}). It first tries to split by
1798 placing the new window below, subject to the restriction imposed by
1799 @code{split-height-threshold} (see below), in addition to any other
1800 restrictions. If that fails, it tries to split by placing the new
1801 window to the right, subject to @code{split-width-threshold} (see
1802 below). If that fails, and the window is the only window on its
1803 frame, this function again tries to split and place the new window
1804 below, disregarding @code{split-height-threshold}. If this fails as
1805 well, this function gives up and returns @code{nil}.
1808 @defopt split-height-threshold
1809 This variable, used by @code{split-window-sensibly}, specifies whether
1810 to split the window placing the new window below. If it is an
1811 integer, that means to split only if the original window has at least
1812 that many lines. If it is @code{nil}, that means not to split this
1816 @defopt split-width-threshold
1817 This variable, used by @code{split-window-sensibly}, specifies whether
1818 to split the window placing the new window to the right. If the value
1819 is an integer, that means to split only if the original window has at
1820 least that many columns. If the value is @code{nil}, that means not
1824 @defopt pop-up-frames
1825 If the value of this variable is non-@code{nil}, that means
1826 @code{display-buffer} may display buffers by making new frames. The
1827 default is @code{nil}.
1829 A non-@code{nil} value also means that when @code{display-buffer} is
1830 looking for a window already displaying @var{buffer-or-name}, it can
1831 search any visible or iconified frame, not just the selected frame.
1833 This variable is provided mainly for backward compatibility. It is
1834 obeyed by @code{display-buffer} via a special mechanism in
1835 @code{display-buffer-fallback-action}, which calls the action function
1836 @code{display-buffer-pop-up-frame} (@pxref{Display Action Functions})
1837 if the value is non-@code{nil}. (This is done before attempting to
1838 split a window.) This variable is not consulted by
1839 @code{display-buffer-pop-up-frame} itself, which the user may specify
1840 directly in @code{display-buffer-alist} etc.
1843 @defopt pop-up-frame-function
1844 This variable specifies a function for creating a new frame, in order
1845 to make a new window for displaying a buffer. It is used by the
1846 @code{display-buffer-pop-up-frame} action function (@pxref{Display
1849 The value should be a function that takes no arguments and returns a
1850 frame, or @code{nil} if no frame could be created. The default value
1851 is a function that creates a frame using the parameters specified by
1852 @code{pop-up-frame-alist} (see below).
1855 @defopt pop-up-frame-alist
1856 This variable holds an alist of frame parameters (@pxref{Frame
1857 Parameters}), which is used by the default function in
1858 @code{pop-up-frame-function} to make a new frame. The default is
1862 @defopt same-window-buffer-names
1863 A list of buffer names for buffers that should be displayed in the
1864 selected window. If a buffer's name is in this list,
1865 @code{display-buffer} handles the buffer by switching to it in the
1869 @defopt same-window-regexps
1870 A list of regular expressions that specify buffers that should be
1871 displayed in the selected window. If the buffer's name matches any of
1872 the regular expressions in this list, @code{display-buffer} handles the
1873 buffer by switching to it in the selected window.
1876 @defun same-window-p buffer-name
1877 This function returns @code{t} if displaying a buffer
1878 named @var{buffer-name} with @code{display-buffer} would
1879 put it in the selected window.
1882 @node Window History
1883 @section Window History
1884 @cindex window history
1886 Each window remembers the buffers it has previously displayed, and the order
1887 in which these buffers were removed from it. This history is used,
1888 for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and
1889 Windows}). This list is automatically maintained by Emacs, but you can
1890 use the following functions to explicitly inspect or alter it:
1892 @defun window-prev-buffers &optional window
1893 This function returns a list specifying the previous contents of
1894 @var{window}, which should be a live window and defaults to the
1897 Each list element has the form @code{(@var{buffer} @var{window-start}
1898 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
1899 the window, @var{window-start} is the window start position when that
1900 buffer was last shown, and @var{window-pos} is the point position when
1901 that buffer was last shown.
1903 The list is ordered so that earlier elements correspond to more
1904 recently-shown buffers, and the first element usually corresponds to the
1905 buffer most recently removed from the window.
1908 @defun set-window-prev-buffers window prev-buffers
1909 This function sets @var{window}'s previous buffers to the value of
1910 @var{prev-buffers}. The argument @var{window} must be a live window
1911 and defaults to the selected one. The argument @var{prev-buffers}
1912 should be a list of the same form as that returned by
1913 @code{window-prev-buffers}.
1916 In addition, each buffer maintains a list of @dfn{next buffers}, which
1917 is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
1918 below). This list is mainly used by @code{switch-to-prev-buffer} and
1919 @code{switch-to-next-buffer} for choosing buffers to switch to.
1921 @defun window-next-buffers &optional window
1922 This function returns the list of buffers recently re-shown in
1923 @var{window} via @code{switch-to-prev-buffer}. The @var{window}
1924 argument must denote a live window or @code{nil} (meaning the selected
1928 @defun set-window-next-buffers window next-buffers
1929 This function sets the next buffer list of @var{window} to
1930 @var{next-buffers}. The @var{window} argument should be a live window
1931 or @code{nil} (meaning the selected window). The argument
1932 @var{next-buffers} should be a list of buffers.
1935 The following commands can be used to cycle through the global buffer
1936 list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
1937 they cycle according to the specified window's history list, rather
1938 than the global buffer list. In addition, they restore
1939 window-specific window start and point positions, and may show a
1940 buffer even if it is already shown in another window. The
1941 @code{switch-to-prev-buffer} command, in particular, is used by
1942 @code{replace-buffer-in-windows}, @code{bury-buffer} and
1943 @code{quit-window} to find a replacement buffer for a window.
1945 @deffn Command switch-to-prev-buffer &optional window bury-or-kill
1946 This command displays the previous buffer in @var{window}. The
1947 argument @var{window} should be a live window or @code{nil} (meaning
1948 the selected window). If the optional argument @var{bury-or-kill} is
1949 non-@code{nil}, this means that the buffer currently shown in
1950 @var{window} is about to be buried or killed and consequently should
1951 not be switched to in future invocations of this command.
1953 The previous buffer is usually the buffer shown before the buffer
1954 currently shown in @var{window}. However, a buffer that has been buried
1955 or killed, or has been already shown by a recent invocation of
1956 @code{switch-to-prev-buffer}, does not qualify as previous buffer.
1958 If repeated invocations of this command have already shown all buffers
1959 previously shown in @var{window}, further invocations will show buffers
1960 from the buffer list of the frame @var{window} appears on (@pxref{The
1961 Buffer List}), trying to skip buffers that are already shown in another
1962 window on that frame.
1965 @deffn Command switch-to-next-buffer &optional window
1966 This command switches to the next buffer in @var{window}, thus undoing
1967 the effect of the last @code{switch-to-prev-buffer} command in
1968 @var{window}. The argument @var{window} must be a live window and
1969 defaults to the selected one.
1971 If there is no recent invocation of @code{switch-to-prev-buffer} that
1972 can be undone, this function tries to show a buffer from the buffer list
1973 of the frame @var{window} appears on (@pxref{The Buffer List}).
1976 By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
1977 can switch to a buffer that is already shown in another window on the
1978 same frame. The following option can be used to override this behavior.
1980 @defopt switch-to-visible-buffer
1981 If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
1982 @code{switch-to-next-buffer} may switch to a buffer that is already
1983 visible on the same frame, provided the buffer was shown in the relevant
1984 window before. If it is @code{nil}, @code{switch-to-prev-buffer} and
1985 @code{switch-to-next-buffer} always try to avoid switching to a buffer
1986 that is already visible in another window on the same frame.
1990 @node Dedicated Windows
1991 @section Dedicated Windows
1992 @cindex dedicated window
1994 Functions for displaying a buffer can be told to not use specific
1995 windows by marking these windows as @dfn{dedicated} to their buffers.
1996 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
1997 window for displaying another buffer in it. @code{get-lru-window} and
1998 @code{get-largest-window} (@pxref{Selecting Windows}) do not consider
1999 dedicated windows as candidates when their @var{dedicated} argument is
2000 non-@code{nil}. The behavior of @code{set-window-buffer}
2001 (@pxref{Buffers and Windows}) with respect to dedicated windows is
2002 slightly different, see below.
2004 When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
2005 delete a dedicated window and that window is the only window on its
2006 frame, it deletes the window's frame too, provided there are other
2007 frames left. @code{replace-buffer-in-windows} (@pxref{Switching
2008 Buffers}) tries to delete all dedicated windows showing its buffer
2009 argument. When such a window is the only window on its frame, that
2010 frame is deleted, provided there are other frames left. If there are
2011 no more frames left, some other buffer is displayed in the window, and
2012 the window is marked as non-dedicated.
2014 When you kill a buffer (@pxref{Killing Buffers}) displayed in a
2015 dedicated window, any such window usually gets deleted too, since
2016 @code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
2017 up windows. Burying a buffer (@pxref{The Buffer List}) deletes the
2018 selected window if it is dedicated to that buffer. If, however, that
2019 window is the only window on its frame, @code{bury-buffer} displays
2020 another buffer in it and iconifies the frame.
2022 @defun window-dedicated-p &optional window
2023 This function returns non-@code{nil} if @var{window} is dedicated to its
2024 buffer and @code{nil} otherwise. More precisely, the return value is
2025 the value assigned by the last call of @code{set-window-dedicated-p} for
2026 @var{window}, or @code{nil} if that function was never called with
2027 @var{window} as its argument. The default for @var{window} is the
2031 @defun set-window-dedicated-p window flag
2032 This function marks @var{window} as dedicated to its buffer if
2033 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
2035 As a special case, if @var{flag} is @code{t}, @var{window} becomes
2036 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
2037 signals an error when the window it acts upon is strongly dedicated to
2038 its buffer and does not already display the buffer it is asked to
2039 display. Other functions do not treat @code{t} differently from any
2040 non-@code{nil} value.
2044 @node Quitting Windows
2045 @section Quitting Windows
2047 When you want to get rid of a window used for displaying a buffer, you
2048 can call @code{delete-window} or @code{delete-windows-on}
2049 (@pxref{Deleting Windows}) to remove that window from its frame. If the
2050 buffer is shown on a separate frame, you might want to call
2051 @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
2052 hand, a window has been reused for displaying the buffer, you might
2053 prefer showing the buffer previously shown in that window, by calling the
2054 function @code{switch-to-prev-buffer} (@pxref{Window History}).
2055 Finally, you might want to either bury (@pxref{The Buffer List}) or kill
2056 (@pxref{Killing Buffers}) the window's buffer.
2058 The following function uses information on how the window for
2059 displaying the buffer was obtained in the first place, thus attempting to
2060 automate the above decisions for you.
2062 @deffn Command quit-window &optional kill window
2063 This command quits @var{window} and buries its buffer. The argument
2064 @var{window} must be a live window and defaults to the selected one.
2065 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
2066 instead of burying it.
2068 Quitting @var{window} means to proceed as follows: If @var{window} was
2069 created specially for displaying its current buffer, delete @var{window}
2070 provided its frame contains at least one other live window. If
2071 @var{window} is the only window on its frame and there are other frames
2072 on the frame's terminal, the value of @var{kill} determines how to
2073 proceed with the window. If @var{kill} is @code{nil}, the fate of the
2074 frame is determined by calling @code{frame-auto-hide-function} (see
2075 below) with that frame as sole argument. If @var{kill} is
2076 non-@code{nil}, the frame is deleted unconditionally.
2078 If @var{window} was reused for displaying its buffer, this command tries
2079 to display the buffer previously shown in it. It also tries to restore
2080 the window start (@pxref{Window Start and End}) and point (@pxref{Window
2081 Point}) positions of the previously shown buffer. If, in addition, the
2082 current buffer was temporarily resized, this command will also try to
2083 restore the original height of @var{window}.
2085 The three cases described so far require that the buffer shown in
2086 @var{window} is still the buffer displayed by the last buffer display
2087 function for this window. If another buffer has been shown in the
2088 meantime, or the buffer previously shown no longer exists, this command
2089 calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some
2090 other buffer instead.
2093 The function @code{quit-window} bases its decisions on information
2094 stored in @var{window}'s @code{quit-restore} window parameter
2095 (@pxref{Window Parameters}), and resets that parameter to @code{nil}
2098 The following option specifies how to deal with a frame containing just
2099 one window that should be either quit, or whose buffer should be buried.
2101 @defopt frame-auto-hide-function
2102 The function specified by this option is called to automatically hide
2103 frames. This function is called with one argument---a frame.
2105 The function specified here is called by @code{bury-buffer} (@pxref{The
2106 Buffer List}) when the selected window is dedicated and shows the buffer
2107 that should be buried. It is also called by @code{quit-window} (see
2108 above) when the frame of the window that should be quit has been
2109 specially created for displaying that window's buffer and the buffer
2112 The default is to call @code{iconify-frame} (@pxref{Visibility of
2113 Frames}). Alternatively, you may specify either @code{delete-frame}
2114 (@pxref{Deleting Frames}) to remove the frame from its display,
2115 @code{ignore} to leave the frame unchanged, or any other function that
2116 can take a frame as its sole argument.
2118 Note that the function specified by this option is called if and only if
2119 there is at least one other frame on the terminal of the frame it's
2120 supposed to handle, and that frame contains only one live window.
2125 @section Windows and Point
2126 @cindex window position
2127 @cindex window point
2128 @cindex position in window
2129 @cindex point in window
2131 Each window has its own value of point (@pxref{Point}), independent of
2132 the value of point in other windows displaying the same buffer. This
2133 makes it useful to have multiple windows showing one buffer.
2137 The window point is established when a window is first created; it is
2138 initialized from the buffer's point, or from the window point of another
2139 window opened on the buffer if such a window exists.
2142 Selecting a window sets the value of point in its buffer from the
2143 window's value of point. Conversely, deselecting a window sets the
2144 window's value of point from that of the buffer. Thus, when you switch
2145 between windows that display a given buffer, the point value for the
2146 selected window is in effect in the buffer, while the point values for
2147 the other windows are stored in those windows.
2150 As long as the selected window displays the current buffer, the window's
2151 point and the buffer's point always move together; they remain equal.
2155 As far as the user is concerned, point is where the cursor is, and
2156 when the user switches to another buffer, the cursor jumps to the
2157 position of point in that buffer.
2159 @defun window-point &optional window
2160 This function returns the current position of point in @var{window}.
2161 For a nonselected window, this is the value point would have (in that
2162 window's buffer) if that window were selected. The default for
2163 @var{window} is the selected window.
2165 When @var{window} is the selected window, the value returned is the
2166 value of point in that window's buffer. Strictly speaking, it would be
2167 more correct to return the ``top-level'' value of point, outside of any
2168 @code{save-excursion} forms. But that value is hard to find.
2171 @defun set-window-point window position
2172 This function positions point in @var{window} at position
2173 @var{position} in @var{window}'s buffer. It returns @var{position}.
2175 If @var{window} is selected, this simply does @code{goto-char} in
2176 @var{window}'s buffer.
2179 @defvar window-point-insertion-type
2180 This variable specifies the marker insertion type (@pxref{Marker
2181 Insertion Types}) of @code{window-point}. The default is @code{nil},
2182 so @code{window-point} will stay behind text inserted there.
2185 @node Window Start and End
2186 @section The Window Start and End Positions
2187 @cindex window start position
2189 Each window maintains a marker used to keep track of a buffer position
2190 that specifies where in the buffer display should start. This position
2191 is called the @dfn{display-start} position of the window (or just the
2192 @dfn{start}). The character after this position is the one that appears
2193 at the upper left corner of the window. It is usually, but not
2194 inevitably, at the beginning of a text line.
2196 After switching windows or buffers, and in some other cases, if the
2197 window start is in the middle of a line, Emacs adjusts the window
2198 start to the start of a line. This prevents certain operations from
2199 leaving the window start at a meaningless point within a line. This
2200 feature may interfere with testing some Lisp code by executing it
2201 using the commands of Lisp mode, because they trigger this
2202 readjustment. To test such code, put it into a command and bind the
2205 @defun window-start &optional window
2206 @cindex window top line
2207 This function returns the display-start position of window
2208 @var{window}. If @var{window} is @code{nil}, the selected window is
2211 When you create a window, or display a different buffer in it, the
2212 display-start position is set to a display-start position recently used
2213 for the same buffer, or to @code{point-min} if the buffer doesn't have
2216 Redisplay updates the window-start position (if you have not specified
2217 it explicitly since the previous redisplay)---to make sure point appears
2218 on the screen. Nothing except redisplay automatically changes the
2219 window-start position; if you move point, do not expect the window-start
2220 position to change in response until after the next redisplay.
2223 @cindex window end position
2224 @defun window-end &optional window update
2225 This function returns the position where display of its buffer ends in
2226 @var{window}. The default for @var{window} is the selected window.
2228 Simply changing the buffer text or moving point does not update the
2229 value that @code{window-end} returns. The value is updated only when
2230 Emacs redisplays and redisplay completes without being preempted.
2232 If the last redisplay of @var{window} was preempted, and did not finish,
2233 Emacs does not know the position of the end of display in that window.
2234 In that case, this function returns @code{nil}.
2236 If @var{update} is non-@code{nil}, @code{window-end} always returns an
2237 up-to-date value for where display ends, based on the current
2238 @code{window-start} value. If a previously saved value of that position
2239 is still valid, @code{window-end} returns that value; otherwise it
2240 computes the correct value by scanning the buffer text.
2242 Even if @var{update} is non-@code{nil}, @code{window-end} does not
2243 attempt to scroll the display if point has moved off the screen, the
2244 way real redisplay would do. It does not alter the
2245 @code{window-start} value. In effect, it reports where the displayed
2246 text will end if scrolling is not required.
2249 @defun set-window-start window position &optional noforce
2250 This function sets the display-start position of @var{window} to
2251 @var{position} in @var{window}'s buffer. It returns @var{position}.
2253 The display routines insist that the position of point be visible when a
2254 buffer is displayed. Normally, they change the display-start position
2255 (that is, scroll the window) whenever necessary to make point visible.
2256 However, if you specify the start position with this function using
2257 @code{nil} for @var{noforce}, it means you want display to start at
2258 @var{position} even if that would put the location of point off the
2259 screen. If this does place point off screen, the display routines move
2260 point to the left margin on the middle line in the window.
2262 For example, if point @w{is 1} and you set the start of the window
2263 @w{to 37}, the start of the next line, point will be ``above'' the top
2264 of the window. The display routines will automatically move point if
2265 it is still 1 when redisplay occurs. Here is an example:
2269 ;; @r{Here is what @samp{foo} looks like before executing}
2270 ;; @r{the @code{set-window-start} expression.}
2274 ---------- Buffer: foo ----------
2275 @point{}This is the contents of buffer foo.
2281 ---------- Buffer: foo ----------
2295 ;; @r{Here is what @samp{foo} looks like after executing}
2296 ;; @r{the @code{set-window-start} expression.}
2297 ---------- Buffer: foo ----------
2303 ---------- Buffer: foo ----------
2307 If @var{noforce} is non-@code{nil}, and @var{position} would place point
2308 off screen at the next redisplay, then redisplay computes a new window-start
2309 position that works well with point, and thus @var{position} is not used.
2312 @defun pos-visible-in-window-p &optional position window partially
2313 This function returns non-@code{nil} if @var{position} is within the
2314 range of text currently visible on the screen in @var{window}. It
2315 returns @code{nil} if @var{position} is scrolled vertically out of view.
2316 Locations that are partially obscured are not considered visible unless
2317 @var{partially} is non-@code{nil}. The argument @var{position} defaults
2318 to the current position of point in @var{window}; @var{window}, to the
2319 selected window. If @var{position} is @code{t}, that means to check the
2320 last visible position in @var{window}.
2322 This function considers only vertical scrolling. If @var{position} is
2323 out of view only because @var{window} has been scrolled horizontally,
2324 @code{pos-visible-in-window-p} returns non-@code{nil} anyway.
2325 @xref{Horizontal Scrolling}.
2327 If @var{position} is visible, @code{pos-visible-in-window-p} returns
2328 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
2329 non-@code{nil}, and the character following @var{position} is fully
2330 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
2331 @var{x} and @var{y} are the pixel coordinates relative to the top left
2332 corner of the window; otherwise it returns an extended list of the form
2333 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
2334 where @var{rtop} and @var{rbot} specify the number of off-window pixels
2335 at the top and bottom of the row at @var{position}, @var{rowh} specifies
2336 the visible height of that row, and @var{vpos} specifies the vertical
2337 position (zero-based row number) of that row.
2343 ;; @r{If point is off the screen now, recenter it now.}
2344 (or (pos-visible-in-window-p
2345 (point) (selected-window))
2351 @defun window-line-height &optional line window
2352 This function returns the height of text line @var{line} in
2353 @var{window}. If @var{line} is one of @code{header-line} or
2354 @code{mode-line}, @code{window-line-height} returns information about
2355 the corresponding line of the window. Otherwise, @var{line} is a text
2356 line number starting from 0. A negative number counts from the end of
2357 the window. The default for @var{line} is the current line in
2358 @var{window}; the default for @var{window} is the selected window.
2360 If the display is not up to date, @code{window-line-height} returns
2361 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
2362 to obtain related information.
2364 If there is no line corresponding to the specified @var{line},
2365 @code{window-line-height} returns @code{nil}. Otherwise, it returns
2366 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
2367 where @var{height} is the height in pixels of the visible part of the
2368 line, @var{vpos} and @var{ypos} are the vertical position in lines and
2369 pixels of the line relative to the top of the first text line, and
2370 @var{offbot} is the number of off-window pixels at the bottom of the
2371 text line. If there are off-window pixels at the top of the (first)
2372 text line, @var{ypos} is negative.
2375 @node Textual Scrolling
2376 @section Textual Scrolling
2377 @cindex textual scrolling
2378 @cindex scrolling textually
2380 @dfn{Textual scrolling} means moving the text up or down through a
2381 window. It works by changing the window's display-start location. It
2382 may also change the value of @code{window-point} to keep point on the
2383 screen (@pxref{Window Point}).
2385 The basic textual scrolling functions are @code{scroll-up} (which
2386 scrolls forward) and @code{scroll-down} (which scrolls backward). In
2387 these function names, ``up'' and ``down'' refer to the direction of
2388 motion of the buffer text relative to the window. Imagine that the
2389 text is written on a long roll of paper and that the scrolling
2390 commands move the paper up and down. Thus, if you are looking at the
2391 middle of a buffer and repeatedly call @code{scroll-down}, you will
2392 eventually see the beginning of the buffer.
2394 Unfortunately, this sometimes causes confusion, because some people
2395 tend to think in terms of the opposite convention: they
2396 imagine the window moving over text that remains in place, so that
2397 ``down'' commands take you to the end of the buffer. This convention
2398 is consistent with fact that such a command is bound to a key named
2399 @key{PageDown} on modern keyboards.
2401 We have not switched to this convention as that is likely to break
2402 existing Emacs Lisp code.
2405 Textual scrolling functions (aside from @code{scroll-other-window})
2406 have unpredictable results if the current buffer is not the one
2407 displayed in the selected window. @xref{Current Buffer}.
2409 If the window contains a row taller than the height of the window
2410 (for example in the presence of a large image), the scroll functions
2411 will adjust the window's vertical scroll position to scroll the
2412 partially visible row. Lisp callers can disable this feature by
2413 binding the variable @code{auto-window-vscroll} to @code{nil}
2414 (@pxref{Vertical Scrolling}).
2416 @deffn Command scroll-up &optional count
2417 This function scrolls forward by @var{count} lines in the selected
2420 If @var{count} is negative, it scrolls backward instead. If
2421 @var{count} is @code{nil} (or omitted), the distance scrolled is
2422 @code{next-screen-context-lines} lines less than the height of the
2425 If the selected window cannot be scrolled any further, this function
2426 signals an error. Otherwise, it returns @code{nil}.
2429 @deffn Command scroll-down &optional count
2430 This function scrolls backward by @var{count} lines in the selected
2433 If @var{count} is negative, it scrolls forward instead. In other
2434 respects, it behaves the same way as @code{scroll-up} does.
2437 @deffn Command scroll-up-command &optional count
2438 This behaves like @code{scroll-up}, except that if the selected window
2439 cannot be scrolled any further and the value of the variable
2440 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
2441 end of the buffer instead. If point is already there, it signals an
2445 @deffn Command scroll-down-command &optional count
2446 This behaves like @code{scroll-down}, except that if the selected
2447 window cannot be scrolled any further and the value of the variable
2448 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
2449 beginning of the buffer instead. If point is already there, it
2453 @deffn Command scroll-other-window &optional count
2454 This function scrolls the text in another window upward @var{count}
2455 lines. Negative values of @var{count}, or @code{nil}, are handled
2456 as in @code{scroll-up}.
2458 You can specify which buffer to scroll by setting the variable
2459 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
2460 already displayed, @code{scroll-other-window} displays it in some
2463 When the selected window is the minibuffer, the next window is normally
2464 the leftmost one immediately above it. You can specify a different
2465 window to scroll, when the minibuffer is selected, by setting the variable
2466 @code{minibuffer-scroll-window}. This variable has no effect when any
2467 other window is selected. When it is non-@code{nil} and the
2468 minibuffer is selected, it takes precedence over
2469 @code{other-window-scroll-buffer}. @xref{Definition of
2470 minibuffer-scroll-window}.
2472 When the minibuffer is active, it is the next window if the selected
2473 window is the one at the bottom right corner. In this case,
2474 @code{scroll-other-window} attempts to scroll the minibuffer. If the
2475 minibuffer contains just one line, it has nowhere to scroll to, so the
2476 line reappears after the echo area momentarily displays the message
2477 @samp{End of buffer}.
2480 @defvar other-window-scroll-buffer
2481 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
2482 which buffer's window to scroll.
2485 @defopt scroll-margin
2486 This option specifies the size of the scroll margin---a minimum number
2487 of lines between point and the top or bottom of a window. Whenever
2488 point gets within this many lines of the top or bottom of the window,
2489 redisplay scrolls the text automatically (if possible) to move point
2490 out of the margin, closer to the center of the window.
2493 @defopt scroll-conservatively
2494 This variable controls how scrolling is done automatically when point
2495 moves off the screen (or into the scroll margin). If the value is a
2496 positive integer @var{n}, then redisplay scrolls the text up to
2497 @var{n} lines in either direction, if that will bring point back into
2498 proper view. This behavior is called @dfn{conservative scrolling}.
2499 Otherwise, scrolling happens in the usual way, under the control of
2500 other variables such as @code{scroll-up-aggressively} and
2501 @code{scroll-down-aggressively}.
2503 The default value is zero, which means that conservative scrolling
2507 @defopt scroll-down-aggressively
2508 The value of this variable should be either @code{nil} or a fraction
2509 @var{f} between 0 and 1. If it is a fraction, that specifies where on
2510 the screen to put point when scrolling down. More precisely, when a
2511 window scrolls down because point is above the window start, the new
2512 start position is chosen to put point @var{f} part of the window
2513 height from the top. The larger @var{f}, the more aggressive the
2516 A value of @code{nil} is equivalent to .5, since its effect is to center
2517 point. This variable automatically becomes buffer-local when set in any
2521 @defopt scroll-up-aggressively
2522 Likewise, for scrolling up. The value, @var{f}, specifies how far
2523 point should be placed from the bottom of the window; thus, as with
2524 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
2528 This variable is an older variant of @code{scroll-conservatively}.
2529 The difference is that if its value is @var{n}, that permits scrolling
2530 only by precisely @var{n} lines, not a smaller number. This feature
2531 does not work with @code{scroll-margin}. The default value is zero.
2534 @cindex @code{scroll-command} property
2535 @defopt scroll-preserve-screen-position
2536 If this option is @code{t}, whenever a scrolling command moves point
2537 off-window, Emacs tries to adjust point to keep the cursor at its old
2538 vertical position in the window, rather than the window edge.
2540 If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
2541 to keep the cursor at the same vertical position, even if the
2542 scrolling command didn't move point off-window.
2544 This option affects all scroll commands that have a non-@code{nil}
2545 @code{scroll-command} symbol property.
2548 @defopt next-screen-context-lines
2549 The value of this variable is the number of lines of continuity to
2550 retain when scrolling by full screens. For example, @code{scroll-up}
2551 with an argument of @code{nil} scrolls so that this many lines at the
2552 bottom of the window appear instead at the top. The default value is
2556 @defopt scroll-error-top-bottom
2557 If this option is @code{nil} (the default), @code{scroll-up-command}
2558 and @code{scroll-down-command} simply signal an error when no more
2559 scrolling is possible.
2561 If the value is @code{t}, these commands instead move point to the
2562 beginning or end of the buffer (depending on scrolling direction);
2563 only if point is already on that position do they signal an error.
2566 @deffn Command recenter &optional count
2567 @cindex centering point
2568 This function scrolls the text in the selected window so that point is
2569 displayed at a specified vertical position within the window. It does
2570 not ``move point'' with respect to the text.
2572 If @var{count} is a non-negative number, that puts the line containing
2573 point @var{count} lines down from the top of the window. If
2574 @var{count} is a negative number, then it counts upward from the
2575 bottom of the window, so that @minus{}1 stands for the last usable
2578 If @var{count} is @code{nil} (or a non-@code{nil} list),
2579 @code{recenter} puts the line containing point in the middle of the
2580 window. If @var{count} is @code{nil}, this function may redraw the
2581 frame, according to the value of @code{recenter-redisplay}.
2583 When @code{recenter} is called interactively, @var{count} is the raw
2584 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
2585 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
2586 @var{count} to 4, which positions the current line four lines from the
2589 With an argument of zero, @code{recenter} positions the current line at
2590 the top of the window. The command @code{recenter-top-bottom} offers
2591 a more convenient way to achieve this.
2594 @defopt recenter-redisplay
2595 If this variable is non-@code{nil}, calling @code{recenter} with a
2596 @code{nil} argument redraws the frame. The default value is
2597 @code{tty}, which means only redraw the frame if it is a tty frame.
2600 @deffn Command recenter-top-bottom &optional count
2601 This command, which is the default binding for @kbd{C-l}, acts like
2602 @code{recenter}, except if called with no argument. In that case,
2603 successive calls place point according to the cycling order defined
2604 by the variable @code{recenter-positions}.
2607 @defopt recenter-positions
2608 This variable controls how @code{recenter-top-bottom} behaves when
2609 called with no argument. The default value is @code{(middle top
2610 bottom)}, which means that successive calls of
2611 @code{recenter-top-bottom} with no argument cycle between placing
2612 point at the middle, top, and bottom of the window.
2616 @node Vertical Scrolling
2617 @section Vertical Fractional Scrolling
2618 @cindex vertical fractional scrolling
2619 @cindex vertical scroll position
2621 @dfn{Vertical fractional scrolling} means shifting text in a window
2622 up or down by a specified multiple or fraction of a line. Each window
2623 has a @dfn{vertical scroll position}, which is a number, never less than
2624 zero. It specifies how far to raise the contents of the window.
2625 Raising the window contents generally makes all or part of some lines
2626 disappear off the top, and all or part of some other lines appear at the
2627 bottom. The usual value is zero.
2629 The vertical scroll position is measured in units of the normal line
2630 height, which is the height of the default font. Thus, if the value is
2631 .5, that means the window contents are scrolled up half the normal line
2632 height. If it is 3.3, that means the window contents are scrolled up
2633 somewhat over three times the normal line height.
2635 What fraction of a line the vertical scrolling covers, or how many
2636 lines, depends on what the lines contain. A value of .5 could scroll a
2637 line whose height is very short off the screen, while a value of 3.3
2638 could scroll just part of the way through a tall line or an image.
2640 @defun window-vscroll &optional window pixels-p
2641 This function returns the current vertical scroll position of
2642 @var{window}. The default for @var{window} is the selected window.
2643 If @var{pixels-p} is non-@code{nil}, the return value is measured in
2644 pixels, rather than in units of the normal line height.
2654 @defun set-window-vscroll window lines &optional pixels-p
2655 This function sets @var{window}'s vertical scroll position to
2656 @var{lines}. If @var{window} is @code{nil}, the selected window is
2657 used. The argument @var{lines} should be zero or positive; if not, it
2661 The actual vertical scroll position must always correspond
2662 to an integral number of pixels, so the value you specify
2663 is rounded accordingly.
2665 The return value is the result of this rounding.
2669 (set-window-vscroll (selected-window) 1.2)
2674 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
2675 pixels. In this case, the return value is @var{lines}.
2678 @defvar auto-window-vscroll
2679 If this variable is non-@code{nil}, the line-move, scroll-up, and
2680 scroll-down functions will automatically modify the vertical scroll
2681 position to scroll through display rows that are taller than the height
2682 of the window, for example in the presence of large images.
2685 @node Horizontal Scrolling
2686 @section Horizontal Scrolling
2687 @cindex horizontal scrolling
2689 @dfn{Horizontal scrolling} means shifting the image in the window left
2690 or right by a specified multiple of the normal character width. Each
2691 window has a @dfn{horizontal scroll position}, which is a number, never
2692 less than zero. It specifies how far to shift the contents left.
2693 Shifting the window contents left generally makes all or part of some
2694 characters disappear off the left, and all or part of some other
2695 characters appear at the right. The usual value is zero.
2697 The horizontal scroll position is measured in units of the normal
2698 character width, which is the width of space in the default font. Thus,
2699 if the value is 5, that means the window contents are scrolled left by 5
2700 times the normal character width. How many characters actually
2701 disappear off to the left depends on their width, and could vary from
2704 Because we read from side to side in the ``inner loop'', and from top
2705 to bottom in the ``outer loop'', the effect of horizontal scrolling is
2706 not like that of textual or vertical scrolling. Textual scrolling
2707 involves selection of a portion of text to display, and vertical
2708 scrolling moves the window contents contiguously; but horizontal
2709 scrolling causes part of @emph{each line} to go off screen.
2711 Usually, no horizontal scrolling is in effect; then the leftmost
2712 column is at the left edge of the window. In this state, scrolling to
2713 the right is meaningless, since there is no data to the left of the edge
2714 to be revealed by it; so this is not allowed. Scrolling to the left is
2715 allowed; it scrolls the first columns of text off the edge of the window
2716 and can reveal additional columns on the right that were truncated
2717 before. Once a window has a nonzero amount of leftward horizontal
2718 scrolling, you can scroll it back to the right, but only so far as to
2719 reduce the net horizontal scroll to zero. There is no limit to how far
2720 left you can scroll, but eventually all the text will disappear off the
2723 @vindex auto-hscroll-mode
2724 If @code{auto-hscroll-mode} is set, redisplay automatically alters
2725 the horizontal scrolling of a window as necessary to ensure that point
2726 is always visible. However, you can still set the horizontal
2727 scrolling value explicitly. The value you specify serves as a lower
2728 bound for automatic scrolling, i.e. automatic scrolling will not
2729 scroll a window to a column less than the specified one.
2731 @deffn Command scroll-left &optional count set-minimum
2732 This function scrolls the selected window @var{count} columns to the
2733 left (or to the right if @var{count} is negative). The default
2734 for @var{count} is the window width, minus 2.
2736 The return value is the total amount of leftward horizontal scrolling in
2737 effect after the change---just like the value returned by
2738 @code{window-hscroll} (below).
2740 Once you scroll a window as far right as it can go, back to its normal
2741 position where the total leftward scrolling is zero, attempts to scroll
2742 any farther right have no effect.
2744 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
2745 the lower bound for automatic scrolling; that is, automatic scrolling
2746 will not scroll a window to a column less than the value returned by
2747 this function. Interactive calls pass non-@code{nil} for
2751 @deffn Command scroll-right &optional count set-minimum
2752 This function scrolls the selected window @var{count} columns to the
2753 right (or to the left if @var{count} is negative). The default
2754 for @var{count} is the window width, minus 2. Aside from the direction
2755 of scrolling, this works just like @code{scroll-left}.
2758 @defun window-hscroll &optional window
2759 This function returns the total leftward horizontal scrolling of
2760 @var{window}---the number of columns by which the text in @var{window}
2761 is scrolled left past the left margin. The default for
2762 @var{window} is the selected window.
2764 The return value is never negative. It is zero when no horizontal
2765 scrolling has been done in @var{window} (which is usually the case).
2784 @defun set-window-hscroll window columns
2785 This function sets horizontal scrolling of @var{window}. The value of
2786 @var{columns} specifies the amount of scrolling, in terms of columns
2787 from the left margin. The argument @var{columns} should be zero or
2788 positive; if not, it is taken as zero. Fractional values of
2789 @var{columns} are not supported at present.
2791 Note that @code{set-window-hscroll} may appear not to work if you test
2792 it by evaluating a call with @kbd{M-:} in a simple way. What happens
2793 is that the function sets the horizontal scroll value and returns, but
2794 then redisplay adjusts the horizontal scrolling to make point visible,
2795 and this overrides what the function did. You can observe the
2796 function's effect if you call it while point is sufficiently far from
2797 the left margin that it will remain visible.
2799 The value returned is @var{columns}.
2803 (set-window-hscroll (selected-window) 10)
2809 Here is how you can determine whether a given position @var{position}
2810 is off the screen due to horizontal scrolling:
2814 (defun hscroll-on-screen (window position)
2816 (goto-char position)
2818 (>= (- (current-column) (window-hscroll window)) 0)
2819 (< (- (current-column) (window-hscroll window))
2820 (window-width window)))))
2824 @node Coordinates and Windows
2825 @section Coordinates and Windows
2826 @cindex frame-relative coordinate
2827 @cindex coordinate, relative to frame
2828 @cindex window position
2830 This section describes functions that report the position of a
2831 window. Most of these functions report positions relative to the
2832 window's frame. In this case, the coordinate origin @samp{(0,0)} lies
2833 near the upper left corner of the frame. For technical reasons, on
2834 graphical displays the origin is not located at the exact corner of
2835 the graphical window as it appears on the screen. If Emacs is built
2836 with the GTK+ toolkit, the origin is at the upper left corner of the
2837 frame area used for displaying Emacs windows, below the title-bar,
2838 GTK+ menu bar, and tool bar (since these are drawn by the window
2839 manager and/or GTK+, not by Emacs). But if Emacs is not built with
2840 GTK+, the origin is at the upper left corner of the tool bar (since in
2841 this case Emacs itself draws the tool bar). In both cases, the X and
2842 Y coordinates increase rightward and downward respectively.
2844 Except where noted, X and Y coordinates are reported in integer
2845 character units, i.e. numbers of lines and columns respectively. On a
2846 graphical display, each ``line'' and ``column'' corresponds to the
2847 height and width of a default character specified by the frame's
2850 @defun window-edges &optional window
2851 This function returns a list of the edge coordinates of @var{window}.
2852 If @var{window} is omitted or @code{nil}, it defaults to the selected
2855 The return value has the form @code{(@var{left} @var{top} @var{right}
2856 @var{bottom})}. These list elements are, respectively, the X
2857 coordinate of the leftmost column occupied by the window, the Y
2858 coordinate of the topmost row, the X coordinate one column to the
2859 right of the rightmost column, and the Y coordinate one row down from
2862 Note that these are the actual outer edges of the window, including
2863 any header line, mode line, scroll bar, fringes, and display margins.
2864 On a text terminal, if the window has a neighbor on its right, its
2865 right edge includes the separator line between the window and its
2869 @defun window-inside-edges &optional window
2870 This function is similar to @code{window-edges}, but the returned edge
2871 values are for the text area of the window. They exclude any header
2872 line, mode line, scroll bar, fringes, display margins, and vertical
2876 @defun window-top-line &optional window
2877 This function returns the Y coordinate of the topmost row of
2878 @var{window}, equivalent to the @var{top} entry in the list returned
2879 by @code{window-edges}.
2882 @defun window-left-column &optional window
2883 This function returns the X coordinate of the leftmost column of
2884 @var{window}, equivalent to the @var{left} entry in the list returned
2885 by @code{window-edges}.
2888 The following functions can be used to relate a set of
2889 frame-relative coordinates to a window:
2891 @defun window-at x y &optional frame
2892 This function returns the live window at the frame-relative
2893 coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no
2894 window at that position, the return value is @code{nil}. If
2895 @var{frame} is omitted or @code{nil}, it defaults to the selected
2899 @defun coordinates-in-window-p coordinates window
2900 This function checks whether a window @var{window} occupies the
2901 frame-relative coordinates @var{coordinates}, and if so, which part of
2902 the window that is. @var{window} should be a live window.
2903 @var{coordinates} should be a cons cell of the form @code{(@var{x}
2904 . @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
2906 If there is no window at the specified position, the return value is
2907 @code{nil} . Otherwise, the return value is one of the following:
2910 @item (@var{relx} . @var{rely})
2911 The coordinates are inside @var{window}. The numbers @var{relx} and
2912 @var{rely} are the equivalent window-relative coordinates for the
2913 specified position, counting from 0 at the top left corner of the
2917 The coordinates are in the mode line of @var{window}.
2920 The coordinates are in the header line of @var{window}.
2923 The coordinates are in the vertical line between @var{window} and its
2924 neighbor to the right. This value occurs only if the window doesn't
2925 have a scroll bar; positions in a scroll bar are considered outside the
2926 window for these purposes.
2930 The coordinates are in the left or right fringe of the window.
2934 The coordinates are in the left or right margin of the window.
2937 The coordinates are not in any part of @var{window}.
2940 The function @code{coordinates-in-window-p} does not require a frame as
2941 argument because it always uses the frame that @var{window} is on.
2944 The following functions return window positions in pixels, rather
2945 than character units. Though mostly useful on graphical displays,
2946 they can also be called on text terminals, where the screen area of
2947 each text character is taken to be ``one pixel''.
2949 @defun window-pixel-edges &optional window
2950 This function returns a list of pixel coordinates for the edges of
2951 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
2952 to the selected window.
2954 The return value has the form @code{(@var{left} @var{top} @var{right}
2955 @var{bottom})}. The list elements are, respectively, the X pixel
2956 coordinate of the left window edge, the Y pixel coordinate of the top
2957 edge, one more than the X pixel coordinate of the right edge, and one
2958 more than the Y pixel coordinate of the bottom edge.
2961 @defun window-inside-pixel-edges &optional window
2962 This function is like @code{window-pixel-edges}, except that it
2963 returns the pixel coordinates for the edges of the window's text area,
2964 rather than the pixel coordinates for the edges of the window itself.
2965 @var{window} must specify a live window.
2968 The following functions return window positions in pixels, relative
2969 to the display screen rather than the frame:
2971 @defun window-absolute-pixel-edges &optional window
2972 This function is like @code{window-pixel-edges}, except that it
2973 returns the edge pixel coordinates relative to the top left corner of
2977 @defun window-inside-absolute-pixel-edges &optional window
2978 This function is like @code{window-inside-pixel-edges}, except that it
2979 returns the edge pixel coordinates relative to the top left corner of
2980 the display screen. @var{window} must specify a live window.
2983 @node Window Configurations
2984 @section Window Configurations
2985 @cindex window configurations
2986 @cindex saving window information
2988 A @dfn{window configuration} records the entire layout of one
2989 frame---all windows, their sizes, which buffers they contain, how those
2990 buffers are scrolled, and their values of point and the mark; also their
2991 fringes, margins, and scroll bar settings. It also includes the value
2992 of @code{minibuffer-scroll-window}. As a special exception, the window
2993 configuration does not record the value of point in the selected window
2994 for the current buffer.
2996 You can bring back an entire frame layout by restoring a previously
2997 saved window configuration. If you want to record the layout of all
2998 frames instead of just one, use a frame configuration instead of a
2999 window configuration. @xref{Frame Configurations}.
3001 @defun current-window-configuration &optional frame
3002 This function returns a new object representing @var{frame}'s current
3003 window configuration. The default for @var{frame} is the selected
3004 frame. The variable @code{window-persistent-parameters} specifies
3005 which window parameters (if any) are saved by this function.
3006 @xref{Window Parameters}.
3009 @defun set-window-configuration configuration
3010 This function restores the configuration of windows and buffers as
3011 specified by @var{configuration}, for the frame that @var{configuration}
3014 The argument @var{configuration} must be a value that was previously
3015 returned by @code{current-window-configuration}. The configuration is
3016 restored in the frame from which @var{configuration} was made, whether
3017 that frame is selected or not. This always counts as a window size
3018 change and triggers execution of the @code{window-size-change-functions}
3019 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
3020 know how to tell whether the new configuration actually differs from the
3023 If the frame from which @var{configuration} was saved is dead, all this
3024 function does is restore the three variables @code{window-min-height},
3025 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
3026 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
3028 Here is a way of using this function to get the same effect
3029 as @code{save-window-excursion}:
3033 (let ((config (current-window-configuration)))
3035 (progn (split-window-below nil)
3037 (set-window-configuration config)))
3042 @defmac save-window-excursion forms@dots{}
3043 This macro records the window configuration of the selected frame,
3044 executes @var{forms} in sequence, then restores the earlier window
3045 configuration. The return value is the value of the final form in
3048 Most Lisp code should not use this macro; @code{save-selected-window}
3049 is typically sufficient. In particular, this macro cannot reliably
3050 prevent the code in @var{forms} from opening new windows, because new
3051 windows might be opened in other frames (@pxref{Choosing Window}), and
3052 @code{save-window-excursion} only saves and restores the window
3053 configuration on the current frame.
3055 Do not use this macro in @code{window-size-change-functions}; exiting
3056 the macro triggers execution of @code{window-size-change-functions},
3057 leading to an endless loop.
3060 @defun window-configuration-p object
3061 This function returns @code{t} if @var{object} is a window configuration.
3064 @defun compare-window-configurations config1 config2
3065 This function compares two window configurations as regards the
3066 structure of windows, but ignores the values of point and mark and the
3067 saved scrolling positions---it can return @code{t} even if those
3070 The function @code{equal} can also compare two window configurations; it
3071 regards configurations as unequal if they differ in any respect, even a
3072 saved point or mark.
3075 @defun window-configuration-frame config
3076 This function returns the frame for which the window configuration
3077 @var{config} was made.
3080 Other primitives to look inside of window configurations would make
3081 sense, but are not implemented because we did not need them. See the
3082 file @file{winner.el} for some more operations on windows
3085 The objects returned by @code{current-window-configuration} die
3086 together with the Emacs process. In order to store a window
3087 configuration on disk and read it back in another Emacs session, you
3088 can use the functions described next. These functions are also useful
3089 to clone the state of a frame into an arbitrary live window
3090 (@code{set-window-configuration} effectively clones the windows of a
3091 frame into the root window of that very frame only).
3093 @defun window-state-get &optional window writable
3094 This function returns the state of @var{window} as a Lisp object. The
3095 argument @var{window} can be any window and defaults to the root window
3096 of the selected frame.
3098 If the optional argument @var{writable} is non-@code{nil}, this means to
3099 not use markers for sampling positions like @code{window-point} or
3100 @code{window-start}. This argument should be non-@code{nil} when the
3101 state will be written to disk and read back in another session.
3103 Together, the argument @var{writable} and the variable
3104 @code{window-persistent-parameters} specify which window parameters are
3105 saved by this function. @xref{Window Parameters}.
3108 The value returned by @code{window-state-get} can be used in the same
3109 session to make a clone of a window in another window. It can be also
3110 written to disk and read back in another session. In either case, use
3111 the following function to restore the state of the window.
3113 @defun window-state-put state &optional window ignore
3114 This function puts the window state @var{state} into @var{window}. The
3115 argument @var{state} should be the state of a window returned by an
3116 earlier invocation of @code{window-state-get}, see above. The optional
3117 argument @var{window} must specify a live window and defaults to the
3120 If the optional argument @var{ignore} is non-@code{nil}, it means to ignore
3121 minimum window sizes and fixed-size restrictions. If @var{ignore}
3122 is @code{safe}, this means windows can get as small as one line
3127 @node Window Parameters
3128 @section Window Parameters
3129 @cindex window parameters
3131 This section describes how window parameters can be used to associate
3132 additional information with windows.
3134 @defun window-parameter window parameter
3135 This function returns @var{window}'s value for @var{parameter}. The
3136 default for @var{window} is the selected window. If @var{window} has no
3137 setting for @var{parameter}, this function returns @code{nil}.
3140 @defun window-parameters &optional window
3141 This function returns all parameters of @var{window} and their values.
3142 The default for @var{window} is the selected window. The return value
3143 is either @code{nil}, or an association list whose elements have the form
3144 @code{(@var{parameter} . @var{value})}.
3147 @defun set-window-parameter window parameter value
3148 This function sets @var{window}'s value of @var{parameter} to
3149 @var{value} and returns @var{value}. The default for @var{window}
3150 is the selected window.
3153 By default, the functions that save and restore window configurations or the
3154 states of windows (@pxref{Window Configurations}) do not care about
3155 window parameters. This means that when you change the value of a
3156 parameter within the body of a @code{save-window-excursion}, the
3157 previous value is not restored when that macro exits. It also means
3158 that when you restore via @code{window-state-put} a window state saved
3159 earlier by @code{window-state-get}, all cloned windows have their
3160 parameters reset to @code{nil}. The following variable allows you to
3161 override the standard behavior:
3163 @defvar window-persistent-parameters
3164 This variable is an alist specifying which parameters get saved by
3165 @code{current-window-configuration} and @code{window-state-get}, and
3166 subsequently restored by @code{set-window-configuration} and
3167 @code{window-state-put}. @xref{Window Configurations}.
3169 The @sc{car} of each entry of this alist is a symbol specifying the
3170 parameter. The @sc{cdr} should be one of the following:
3174 This value means the parameter is saved neither by
3175 @code{window-state-get} nor by @code{current-window-configuration}.
3178 This value specifies that the parameter is saved by
3179 @code{current-window-configuration} and (provided its @var{writable}
3180 argument is @code{nil}) by @code{window-state-get}.
3182 @item @code{writable}
3183 This means that the parameter is saved unconditionally by both
3184 @code{current-window-configuration} and @code{window-state-get}. This
3185 value should not be used for parameters whose values do not have a read
3186 syntax. Otherwise, invoking @code{window-state-put} in another session
3187 may fail with an @code{invalid-read-syntax} error.
3191 Some functions (notably @code{delete-window},
3192 @code{delete-other-windows} and @code{split-window}), may behave specially
3193 when their @var{window} argument has a parameter set. You can override
3194 such special behavior by binding the following variable to a
3195 non-@code{nil} value:
3197 @defvar ignore-window-parameters
3198 If this variable is non-@code{nil}, some standard functions do not
3199 process window parameters. The functions currently affected by this are
3200 @code{split-window}, @code{delete-window}, @code{delete-other-windows},
3201 and @code{other-window}.
3203 An application can bind this variable to a non-@code{nil} value around
3204 calls to these functions. If it does so, the application is fully
3205 responsible for correctly assigning the parameters of all involved
3206 windows when exiting that function.
3209 The following parameters are currently used by the window management
3213 @item @code{delete-window}
3214 This parameter affects the execution of @code{delete-window}
3215 (@pxref{Deleting Windows}).
3217 @item @code{delete-other-windows}
3218 This parameter affects the execution of @code{delete-other-windows}
3219 (@pxref{Deleting Windows}).
3221 @item @code{split-window}
3222 This parameter affects the execution of @code{split-window}
3223 (@pxref{Splitting Windows}).
3225 @item @code{other-window}
3226 This parameter affects the execution of @code{other-window}
3227 (@pxref{Cyclic Window Ordering}).
3229 @item @code{no-other-window}
3230 This parameter marks the window as not selectable by @code{other-window}
3231 (@pxref{Cyclic Window Ordering}).
3233 @item @code{clone-of}
3234 This parameter specifies the window that this one has been cloned
3235 from. It is installed by @code{window-state-get} (@pxref{Window
3238 @item @code{quit-restore}
3239 This parameter specifies what to do with a window when the buffer it
3240 shows is not needed any more. It is installed by the buffer display
3241 functions (@pxref{Choosing Window}), and consulted by the function
3242 @code{quit-window} (@pxref{Quitting Windows}).
3245 There are additional parameters @code{window-atom} and @code{window-side};
3246 these are reserved and should not be used by applications.
3250 @section Hooks for Window Scrolling and Changes
3251 @cindex hooks for window operations
3253 This section describes how a Lisp program can take action whenever a
3254 window displays a different part of its buffer or a different buffer.
3255 There are three actions that can change this: scrolling the window,
3256 switching buffers in the window, and changing the size of the window.
3257 The first two actions run @code{window-scroll-functions}; the last runs
3258 @code{window-size-change-functions}.
3260 @defvar window-scroll-functions
3261 This variable holds a list of functions that Emacs should call before
3262 redisplaying a window with scrolling. Displaying a different buffer in
3263 the window also runs these functions.
3265 This variable is not a normal hook, because each function is called with
3266 two arguments: the window, and its new display-start position.
3268 These functions must take care when using @code{window-end}
3269 (@pxref{Window Start and End}); if you need an up-to-date value, you
3270 must use the @var{update} argument to ensure you get it.
3272 @strong{Warning:} don't use this feature to alter the way the window
3273 is scrolled. It's not designed for that, and such use probably won't
3277 @defvar window-size-change-functions
3278 This variable holds a list of functions to be called if the size of any
3279 window changes for any reason. The functions are called just once per
3280 redisplay, and just once for each frame on which size changes have
3283 Each function receives the frame as its sole argument. There is no
3284 direct way to find out which windows on that frame have changed size, or
3285 precisely how. However, if a size-change function records, at each
3286 call, the existing windows and their sizes, it can also compare the
3287 present sizes and the previous sizes.
3289 Creating or deleting windows counts as a size change, and therefore
3290 causes these functions to be called. Changing the frame size also
3291 counts, because it changes the sizes of the existing windows.
3293 You may use @code{save-selected-window} in these functions
3294 (@pxref{Selecting Windows}). However, do not use
3295 @code{save-window-excursion} (@pxref{Window Configurations}); exiting
3296 that macro counts as a size change, which would cause these functions
3297 to be called over and over.
3300 @defvar window-configuration-change-hook
3301 A normal hook that is run every time you change the window configuration
3302 of an existing frame. This includes splitting or deleting windows,
3303 changing the sizes of windows, or displaying a different buffer in a
3306 The buffer-local part of this hook is run once for each window on the
3307 affected frame, with the relevant window selected and its buffer
3308 current. The global part is run once for the modified frame, with that
3312 In addition, you can use @code{jit-lock-register} to register a Font
3313 Lock fontification function, which will be called whenever parts of a
3314 buffer are (re)fontified because a window was scrolled or its size
3315 changed. @xref{Other Font Lock Variables}.