2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
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 * Preserving Window Sizes:: Preserving the size of windows.
20 * Splitting Windows:: Creating a new window.
21 * Deleting Windows:: Removing a window from its frame.
22 * Recombining Windows:: Preserving the frame layout when splitting and
24 * Selecting Windows:: The selected window is the one that you edit in.
25 * Cyclic Window Ordering:: Moving around the existing windows.
26 * Buffers and Windows:: Each window displays the contents of a buffer.
27 * Switching Buffers:: Higher-level functions for switching to a buffer.
28 * Choosing Window:: How to choose a window for displaying a buffer.
29 * Display Action Functions:: Subroutines for @code{display-buffer}.
30 * Choosing Window Options:: Extra options affecting how buffers are displayed.
31 * Window History:: Each window remembers the buffers displayed in it.
32 * Dedicated Windows:: How to avoid displaying another buffer in
34 * Quitting Windows:: How to restore the state prior to displaying a
36 * Window Point:: Each window has its own location of point.
37 * Window Start and End:: Buffer positions indicating which text is
38 on-screen in a window.
39 * Textual Scrolling:: Moving text up and down through the window.
40 * Vertical Scrolling:: Moving the contents up and down on the window.
41 * Horizontal Scrolling:: Moving the contents sideways on the window.
42 * Coordinates and Windows:: Converting coordinates to windows.
43 * Window Configurations:: Saving and restoring the state of the screen.
44 * Window Parameters:: Associating additional information with windows.
45 * Window Hooks:: Hooks for scrolling, window size changes,
46 redisplay going past a certain point,
47 or window configuration changes.
52 @section Basic Concepts of Emacs Windows
55 A @dfn{window} is an area of the screen that is used to display a buffer
56 (@pxref{Buffers}). In Emacs Lisp, windows are represented by a special
59 @cindex multiple windows
60 Windows are grouped into frames (@pxref{Frames}). Each frame
61 contains at least one window; the user can subdivide it into multiple,
62 non-overlapping windows to view several buffers at once. Lisp
63 programs can use multiple windows for a variety of purposes. In
64 Rmail, for example, you can view a summary of message titles in one
65 window, and the contents of the selected message in another window.
67 @cindex terminal screen
68 @cindex screen of terminal
69 Emacs uses the word ``window'' with a different meaning than in
70 graphical desktop environments and window systems, such as the X
71 Window System. When Emacs is run on X, each of its graphical X
72 windows is an Emacs frame (containing one or more Emacs windows).
73 When Emacs is run on a text terminal, the frame fills the entire
77 Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
78 within the area of the frame. When a window is created, resized, or
79 deleted, the change in window space is taken from or given to the
80 adjacent windows, so that the total area of the frame is unchanged.
83 This function returns @code{t} if @var{object} is a window (whether or
84 not it displays a buffer). Otherwise, it returns @code{nil}.
88 A @dfn{live window} is one that is actually displaying a buffer in a
91 @defun window-live-p object
92 This function returns @code{t} if @var{object} is a live window and
93 @code{nil} otherwise. A live window is one that displays a buffer.
96 @cindex internal windows
97 The windows in each frame are organized into a @dfn{window tree}.
98 @xref{Windows and Frames}. The leaf nodes of each window tree are live
99 windows---the ones actually displaying buffers. The internal nodes of
100 the window tree are @dfn{internal windows}, which are not live.
102 @cindex valid windows
103 A @dfn{valid window} is one that is either live or internal. A valid
104 window can be @dfn{deleted}, i.e., removed from its frame
105 (@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
106 object representing it might be still referenced from other Lisp
107 objects. A deleted window may be made valid again by restoring a saved
108 window configuration (@pxref{Window Configurations}).
110 You can distinguish valid windows from deleted windows with
111 @code{window-valid-p}.
113 @defun window-valid-p object
114 This function returns @code{t} if @var{object} is a live window, or an
115 internal window in a window tree. Otherwise, it returns @code{nil},
116 including for the case where @var{object} is a deleted window.
119 @cindex selected window
120 @cindex window selected within a frame
121 In each frame, at any time, exactly one Emacs window is designated
122 as @dfn{selected within the frame}. For the selected frame, that
123 window is called the @dfn{selected window}---the one in which most
124 editing takes place, and in which the cursor for selected windows
125 appears (@pxref{Cursor Parameters}). The selected window's buffer is
126 usually also the current buffer, except when @code{set-buffer} has
127 been used (@pxref{Current Buffer}). As for non-selected frames, the
128 window selected within the frame becomes the selected window if the
129 frame is ever selected. @xref{Selecting Windows}.
131 @defun selected-window
132 This function returns the selected window (which is always a live
136 @anchor{Window Group}Sometimes several windows collectively and
137 cooperatively display a buffer, for example, under the management of
138 Follow Mode (@pxref{Follow Mode,,, emacs}), where the windows together
139 display a bigger portion of the buffer than one window could alone.
140 It is often useful to consider such a @dfn{window group} as a single
141 entity. Several functions such as @code{window-group-start}
142 (@pxref{Window Start and End}) allow you to do this by supplying, as
143 an argument, one of the windows as a stand in for the whole group.
145 @defun selected-window-group
146 @vindex selected-window-group-function
147 When the selected window is a member of a group of windows, this
148 function returns a list of the windows in the group, ordered such that
149 the first window in the list is displaying the earliest part of the
150 buffer, and so on. Otherwise the function returns a list containing
151 just the selected window.
153 The selected window is considered part of a group when the buffer
154 local variable @code{selected-window-group-function} is set to a
155 function. In this case, @code{selected-window-group} calls it with no
156 arguments and returns its result (which should be the list of windows
160 @node Windows and Frames
161 @section Windows and Frames
163 Each window belongs to exactly one frame (@pxref{Frames}).
165 @defun window-frame &optional window
166 This function returns the frame that the window @var{window} belongs
167 to. If @var{window} is @code{nil}, it defaults to the selected
171 @defun window-list &optional frame minibuffer window
172 This function returns a list of live windows belonging to the frame
173 @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
176 The optional argument @var{minibuffer} specifies whether to include
177 the minibuffer window in the returned list. If @var{minibuffer} is
178 @code{t}, the minibuffer window is included. If @var{minibuffer} is
179 @code{nil} or omitted, the minibuffer window is included only if it is
180 active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the
181 minibuffer window is never included.
183 The optional argument @var{window}, if non-@code{nil}, should be a live
184 window on the specified frame; then @var{window} will be the first
185 element in the returned list. If @var{window} is omitted or @code{nil},
186 the window selected within the frame is the first element.
191 Windows in the same frame are organized into a @dfn{window tree},
192 whose leaf nodes are the live windows. The internal nodes of a window
193 tree are not live; they exist for the purpose of organizing the
194 relationships between live windows. The root node of a window tree is
195 called the @dfn{root window}. It can be either a live window (if the
196 frame has just one window), or an internal window.
198 A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
199 frame's window tree unless the frame is a minibuffer-only frame.
200 Nonetheless, most of the functions in this section accept the
201 minibuffer window as an argument. Also, the function
202 @code{window-tree} described at the end of this section lists the
203 minibuffer window alongside the actual window tree.
205 @defun frame-root-window &optional frame-or-window
206 This function returns the root window for @var{frame-or-window}. The
207 argument @var{frame-or-window} should be either a window or a frame;
208 if omitted or @code{nil}, it defaults to the selected frame. If
209 @var{frame-or-window} is a window, the return value is the root window
210 of that window's frame.
213 @cindex parent window
215 @cindex sibling window
216 When a window is split, there are two live windows where previously
217 there was one. One of these is represented by the same Lisp window
218 object as the original window, and the other is represented by a
219 newly-created Lisp window object. Both of these live windows become
220 leaf nodes of the window tree, as @dfn{child windows} of a single
221 internal window. If necessary, Emacs automatically creates this
222 internal window, which is also called the @dfn{parent window}, and
223 assigns it to the appropriate position in the window tree. A set of
224 windows that share the same parent are called @dfn{siblings}.
226 @cindex parent window
227 @defun window-parent &optional window
228 This function returns the parent window of @var{window}. If
229 @var{window} is omitted or @code{nil}, it defaults to the selected
230 window. The return value is @code{nil} if @var{window} has no parent
231 (i.e., it is a minibuffer window or the root window of its frame).
234 Each internal window always has at least two child windows. If this
235 number falls to one as a result of window deletion, Emacs
236 automatically deletes the internal window, and its sole remaining
237 child window takes its place in the window tree.
239 Each child window can be either a live window, or an internal window
240 (which in turn would have its own child windows). Therefore, each
241 internal window can be thought of as occupying a certain rectangular
242 @dfn{screen area}---the union of the areas occupied by the live
243 windows that are ultimately descended from it.
245 @cindex window combination
246 @cindex vertical combination
247 @cindex horizontal combination
248 For each internal window, the screen areas of the immediate children
249 are arranged either vertically or horizontally (never both). If the
250 child windows are arranged one above the other, they are said to form
251 a @dfn{vertical combination}; if they are arranged side by side, they
252 are said to form a @dfn{horizontal combination}. Consider the
257 ______________________________________
258 | ______ ____________________________ |
259 || || __________________________ ||
263 || |||____________W4____________|||
264 || || __________________________ ||
267 || |||____________W5____________|||
268 ||__W2__||_____________W3_____________ |
269 |__________________W1__________________|
275 The root window of this frame is an internal window, @var{W1}. Its
276 child windows form a horizontal combination, consisting of the live
277 window @var{W2} and the internal window @var{W3}. The child windows
278 of @var{W3} form a vertical combination, consisting of the live
279 windows @var{W4} and @var{W5}. Hence, the live windows in this
280 window tree are @var{W2}, @var{W4}, and @var{W5}.
282 The following functions can be used to retrieve a child window of an
283 internal window, and the siblings of a child window.
285 @defun window-top-child &optional window
286 This function returns the topmost child window of @var{window}, if
287 @var{window} is an internal window whose children form a vertical
288 combination. For any other type of window, the return value is
292 @defun window-left-child &optional window
293 This function returns the leftmost child window of @var{window}, if
294 @var{window} is an internal window whose children form a horizontal
295 combination. For any other type of window, the return value is
299 @defun window-child window
300 This function returns the first child window of the internal window
301 @var{window}---the topmost child window for a vertical combination, or
302 the leftmost child window for a horizontal combination. If
303 @var{window} is a live window, the return value is @code{nil}.
306 @defun window-combined-p &optional window horizontal
307 This function returns a non-@code{nil} value if and only if
308 @var{window} is part of a vertical combination. If @var{window} is
309 omitted or @code{nil}, it defaults to the selected one.
311 If the optional argument @var{horizontal} is non-@code{nil}, this
312 means to return non-@code{nil} if and only if @var{window} is part of
313 a horizontal combination.
316 @defun window-next-sibling &optional window
317 This function returns the next sibling of the window @var{window}. If
318 omitted or @code{nil}, @var{window} defaults to the selected window.
319 The return value is @code{nil} if @var{window} is the last child of
323 @defun window-prev-sibling &optional window
324 This function returns the previous sibling of the window @var{window}.
325 If omitted or @code{nil}, @var{window} defaults to the selected
326 window. The return value is @code{nil} if @var{window} is the first
330 The functions @code{window-next-sibling} and
331 @code{window-prev-sibling} should not be confused with the functions
332 @code{next-window} and @code{previous-window}, which return the next
333 and previous window, respectively, in the cyclic ordering of windows
334 (@pxref{Cyclic Window Ordering}).
336 You can use the following functions to find the first live window on a
337 frame and the window nearest to a given window.
339 @defun frame-first-window &optional frame-or-window
340 This function returns the live window at the upper left corner of the
341 frame specified by @var{frame-or-window}. The argument
342 @var{frame-or-window} must denote a window or a live frame and defaults
343 to the selected frame. If @var{frame-or-window} specifies a window,
344 this function returns the first window on that window's frame. Under
345 the assumption that the frame from our canonical example is selected
346 @code{(frame-first-window)} returns @var{W2}.
349 @cindex window in direction
350 @defun window-in-direction direction &optional window ignore sign wrap mini
351 This function returns the nearest live window in direction
352 @var{direction} as seen from the position of @code{window-point} in
353 window @var{window}. The argument @var{direction} must be one of
354 @code{above}, @code{below}, @code{left} or @code{right}. The optional
355 argument @var{window} must denote a live window and defaults to the
358 This function does not return a window whose @code{no-other-window}
359 parameter is non-@code{nil} (@pxref{Window Parameters}). If the nearest
360 window's @code{no-other-window} parameter is non-@code{nil}, this
361 function tries to find another window in the indicated direction whose
362 @code{no-other-window} parameter is @code{nil}. If the optional
363 argument @var{ignore} is non-@code{nil}, a window may be returned even
364 if its @code{no-other-window} parameter is non-@code{nil}.
366 If the optional argument @var{sign} is a negative number, it means to
367 use the right or bottom edge of @var{window} as reference position
368 instead of @code{window-point}. If @var{sign} is a positive number, it
369 means to use the left or top edge of @var{window} as reference position.
371 If the optional argument @var{wrap} is non-@code{nil}, this means to
372 wrap @var{direction} around frame borders. For example, if @var{window}
373 is at the top of the frame and @var{direction} is @code{above}, then
374 this function usually returns the frame's minibuffer window if it's
375 active and a window at the bottom of the frame otherwise.
377 If the optional argument @var{mini} is @code{nil}, this means to return
378 the minibuffer window if and only if it is currently active. If
379 @var{mini} is non-@code{nil}, this function may return the minibuffer
380 window even when it's not active. However, if @var{wrap} is
381 non-@code{nil}, it always acts as if @var{mini} were @code{nil}.
383 If it doesn't find a suitable window, this function returns @code{nil}.
386 The following function allows the entire window tree of a frame to be
389 @defun window-tree &optional frame
390 This function returns a list representing the window tree for frame
391 @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
394 The return value is a list of the form @code{(@var{root} @var{mini})},
395 where @var{root} represents the window tree of the frame's root
396 window, and @var{mini} is the frame's minibuffer window.
398 If the root window is live, @var{root} is that window itself.
399 Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
400 @var{w2} ...)} where @var{dir} is @code{nil} for a horizontal
401 combination and @code{t} for a vertical combination, @var{edges} gives
402 the size and position of the combination, and the remaining elements
403 are the child windows. Each child window may again be a window object
404 (for a live window) or a list with the same format as above (for an
405 internal window). The @var{edges} element is a list @code{(@var{left}
406 @var{top} @var{right} @var{bottom})}, similar to the value returned by
407 @code{window-edges} (@pxref{Coordinates and Windows}).
412 @section Window Sizes
414 @cindex size of window
416 The following schematic shows the structure of a live window:
420 ____________________________________________
421 |______________ Header Line ______________|RD| ^
422 ^ |LS|LM|LF| |RF|RM|RS| | |
423 | | | | | | | | | | |
424 Window | | | | Text Area | | | | | Window
425 Body | | | | | (Window Body) | | | | | Total
426 Height | | | | | | | | | Height
427 | | | | |<- Window Body Width ->| | | | | |
428 v |__|__|__|_______________________|__|__|__| | |
429 |_________ Horizontal Scroll Bar _________| | |
430 |_______________ Mode Line _______________|__| |
431 |_____________ Bottom Divider _______________| v
432 <---------- Window Total Width ------------>
438 @cindex text area of a window
439 @cindex body of a window
440 At the center of the window is the @dfn{text area}, or @dfn{body},
441 where the buffer text is displayed. The text area can be surrounded by
442 a series of optional areas. On the left and right, from innermost to
443 outermost, these are the left and right fringes, denoted by LF and RF
444 (@pxref{Fringes}); the left and right margins, denoted by LM and RM in
445 the schematic (@pxref{Display Margins}); the left or right vertical
446 scroll bar, only one of which is present at any time, denoted by LS and
447 RS (@pxref{Scroll Bars}); and the right divider, denoted by RD
448 (@pxref{Window Dividers}). At the top of the window is the header line
449 (@pxref{Header Lines}). At the bottom of the window are the horizontal
450 scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
451 Format}); and the bottom divider (@pxref{Window Dividers}).
453 Emacs provides miscellaneous functions for finding the height and
454 width of a window. The return value of many of these functions can be
455 specified either in units of pixels or in units of lines and columns.
456 On a graphical display, the latter actually correspond to the height and
457 width of a default character specified by the frame's default font
458 as returned by @code{frame-char-height} and @code{frame-char-width}
459 (@pxref{Frame Font}). Thus, if a window is displaying text with a
460 different font or size, the reported line height and column width for
461 that window may differ from the actual number of text lines or columns
464 @cindex window height
465 @cindex height of a window
466 @cindex total height of a window
467 The @dfn{total height} of a window is the number of lines comprising
468 the window's body, the header line, the horizontal scroll bar, the mode
469 line and the bottom divider (if any).
471 @defun window-total-height &optional window round
472 This function returns the total height, in lines, of the window
473 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
474 the selected window. If @var{window} is an internal window, the return
475 value is the total height occupied by its descendant windows.
477 If a window's pixel height is not an integral multiple of its frame's
478 default character height, the number of lines occupied by the window is
479 rounded internally. This is done in a way such that, if the window is a
480 parent window, the sum of the total heights of all its child windows
481 internally equals the total height of their parent. This means that
482 although two windows have the same pixel height, their internal total
483 heights may differ by one line. This means also, that if window is
484 vertically combined and has a next sibling, the topmost row of that
485 sibling can be calculated as the sum of this window's topmost row and
486 total height (@pxref{Coordinates and Windows})
488 If the optional argument @var{round} is @code{ceiling}, this
489 function returns the smallest integer larger than @var{window}'s pixel
490 height divided by the character height of its frame; if it is
491 @code{floor}, it returns the largest integer smaller than said value;
492 with any other @var{round} it returns the internal value of
493 @var{windows}'s total height.
497 @cindex width of a window
498 @cindex total width of a window
499 The @dfn{total width} of a window is the number of lines comprising the
500 window's body, its margins, fringes, scroll bars and a right divider (if
503 @defun window-total-width &optional window round
504 This function returns the total width, in columns, of the window
505 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
506 the selected window. If @var{window} is internal, the return value is
507 the total width occupied by its descendant windows.
509 If a window's pixel width is not an integral multiple of its frame's
510 character width, the number of lines occupied by the window is rounded
511 internally. This is done in a way such that, if the window is a parent
512 window, the sum of the total widths of all its children internally
513 equals the total width of their parent. This means that although two
514 windows have the same pixel width, their internal total widths may
515 differ by one column. This means also, that if this window is
516 horizontally combined and has a next sibling, the leftmost column of
517 that sibling can be calculated as the sum of this window's leftmost
518 column and total width (@pxref{Coordinates and Windows}). The optional
519 argument @var{round} behaves as it does for @code{window-total-height}.
522 @defun window-total-size &optional window horizontal round
523 This function returns either the total height in lines or the total
524 width in columns of the window @var{window}. If @var{horizontal} is
525 omitted or @code{nil}, this is equivalent to calling
526 @code{window-total-height} for @var{window}; otherwise it is equivalent
527 to calling @code{window-total-width} for @var{window}. The optional
528 argument @var{round} behaves as it does for @code{window-total-height}.
531 The following two functions can be used to return the total size of a
532 window in units of pixels.
534 @cindex window pixel height
535 @cindex pixel height of a window
536 @cindex total pixel height of a window
538 @defun window-pixel-height &optional window
539 This function returns the total height of window @var{window} in pixels.
540 @var{window} must be a valid window and defaults to the selected one.
542 The return value includes mode and header line, a horizontal scroll bar
543 and a bottom divider, if any. If @var{window} is an internal window,
544 its pixel height is the pixel height of the screen areas spanned by its
548 @defun window-pixel-height-before-size-change &optional Lisp_Object &optional window
549 This function returns the height of window @var{window} in pixels at the
550 time @code{window-size-change-functions} was run for the last time on
551 @var{window}'s frame (@pxref{Window Hooks}).
554 @cindex window pixel width
555 @cindex pixel width of a window
556 @cindex total pixel width of a window
558 @defun window-pixel-width &optional Lisp_Object &optional window
559 This function returns the width of window @var{window} in pixels.
560 @var{window} must be a valid window and defaults to the selected one.
562 The return value includes the fringes and margins of @var{window} as
563 well as any vertical dividers or scroll bars belonging to @var{window}.
564 If @var{window} is an internal window, its pixel width is the width of
565 the screen areas spanned by its children.
568 @defun window-pixel-width-before-size-change &optional Lisp_Object &optional window
569 This function returns the width of window @var{window} in pixels at the
570 time @code{window-size-change-functions} was run for the last time on
571 @var{window}'s frame (@pxref{Window Hooks}).
574 @cindex full-width window
575 @cindex full-height window
576 The following functions can be used to determine whether a given
577 window has any adjacent windows.
579 @defun window-full-height-p &optional window
580 This function returns non-@code{nil} if @var{window} has no other window
581 above or below it in its frame. More precisely, this means that the
582 total height of @var{window} equals the total height of the root window
583 on that frame. The minibuffer window does not count in this regard. If
584 @var{window} is omitted or @code{nil}, it defaults to the selected
588 @defun window-full-width-p &optional window
589 This function returns non-@code{nil} if @var{window} has no other
590 window to the left or right in its frame, i.e., its total width equals
591 that of the root window on that frame. If @var{window} is omitted or
592 @code{nil}, it defaults to the selected window.
595 @cindex window body height
596 @cindex body height of a window
597 The @dfn{body height} of a window is the height of its text area, which
598 does not include a mode or header line, a horizontal scroll bar, or a
601 @defun window-body-height &optional window pixelwise
602 This function returns the height, in lines, of the body of window
603 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
604 the selected window; otherwise it must be a live window.
606 If the optional argument @var{pixelwise} is non-@code{nil}, this
607 function returns the body height of @var{window} counted in pixels.
609 If @var{pixelwise} is @code{nil}, the return value is rounded down to
610 the nearest integer, if necessary. This means that if a line at the
611 bottom of the text area is only partially visible, that line is not
612 counted. It also means that the height of a window's body can never
613 exceed its total height as returned by @code{window-total-height}.
616 @cindex window body width
617 @cindex body width of a window
618 The @dfn{body width} of a window is the width of its text area, which
619 does not include the scroll bar, fringes, margins or a right divider.
621 @defun window-body-width &optional window pixelwise
622 This function returns the width, in columns, of the body of window
623 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
624 the selected window; otherwise it must be a live window.
626 If the optional argument @var{pixelwise} is non-@code{nil}, this
627 function returns the body width of @var{window} in units of pixels.
629 If @var{pixelwise} is @code{nil}, the return value is rounded down to
630 the nearest integer, if necessary. This means that if a column on the
631 right of the text area is only partially visible, that column is not
632 counted. It also means that the width of a window's body can never
633 exceed its total width as returned by @code{window-total-width}.
636 @cindex window body size
637 @cindex body size of a window
638 @defun window-body-size &optional window horizontal pixelwise
639 This function returns the body height or body width of @var{window}. If
640 @var{horizontal} is omitted or @code{nil}, it is equivalent to calling
641 @code{window-body-height} for @var{window}; otherwise it is equivalent
642 to calling @code{window-body-width}. In either case, the optional
643 argument @var{pixelwise} is passed to the function called.
646 For compatibility with previous versions of Emacs,
647 @code{window-height} is an alias for @code{window-total-height}, and
648 @code{window-width} is an alias for @code{window-body-width}. These
649 aliases are considered obsolete and will be removed in the future.
651 The pixel heights of a window's mode and header line can be retrieved
652 with the functions given below. Their return value is usually accurate
653 unless the window has not been displayed before: In that case, the
654 return value is based on an estimate of the font used for the window's
657 @defun window-mode-line-height &optional window
658 This function returns the height in pixels of @var{window}'s mode line.
659 @var{window} must be a live window and defaults to the selected one. If
660 @var{window} has no mode line, the return value is zero.
663 @defun window-header-line-height &optional window
664 This function returns the height in pixels of @var{window}'s header
665 line. @var{window} must be a live window and defaults to the selected
666 one. If @var{window} has no header line, the return value is zero.
669 Functions for retrieving the height and/or width of window dividers
670 (@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
671 (@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
672 described in the corresponding sections.
674 If your Lisp program needs to make layout decisions, you will find the
675 following function useful:
677 @defun window-max-chars-per-line &optional window face
678 This function returns the number of characters displayed in the
679 specified face @var{face} in the specified window @var{window} (which
680 must be a live window). If @var{face} was remapped (@pxref{Face
681 Remapping}), the information is returned for the remapped face. If
682 omitted or @code{nil}, @var{face} defaults to the default face, and
683 @var{window} defaults to the selected window.
685 Unlike @code{window-body-width}, this function accounts for the actual
686 size of @var{face}'s font, instead of working in units of the canonical
687 character width of @var{window}'s frame (@pxref{Frame Font}). It also
688 accounts for space used by the continuation glyph, if @var{window} lacks
689 one or both of its fringes.
692 @cindex fixed-size window
693 @vindex window-min-height
694 @vindex window-min-width
695 Commands that change the size of windows (@pxref{Resizing Windows}),
696 or split them (@pxref{Splitting Windows}), obey the variables
697 @code{window-min-height} and @code{window-min-width}, which specify the
698 smallest allowable window height and width. They also obey the variable
699 @code{window-size-fixed}, with which a window can be @dfn{fixed} in
700 size (@pxref{Preserving Window Sizes}).
702 @defopt window-min-height
703 This option specifies the minimum total height, in lines, of any window.
704 Its value has to accommodate at least one text line as well as a mode
705 and header line, a horizontal scroll bar and a bottom divider, if
709 @defopt window-min-width
710 This option specifies the minimum total width, in columns, of any
711 window. Its value has to accommodate two text columns as well as
712 margins, fringes, a scroll bar and a right divider, if present.
715 The following function tells how small a specific window can get taking
716 into account the sizes of its areas and the values of
717 @code{window-min-height}, @code{window-min-width} and
718 @code{window-size-fixed} (@pxref{Preserving Window Sizes}).
720 @defun window-min-size &optional window horizontal ignore pixelwise
721 This function returns the minimum size of @var{window}. @var{window}
722 must be a valid window and defaults to the selected one. The optional
723 argument @var{horizontal} non-@code{nil} means to return the minimum
724 number of columns of @var{window}; otherwise return the minimum number
725 of @var{window}'s lines.
727 The return value makes sure that all components of @var{window} remain
728 fully visible if @var{window}'s size were actually set to it. With
729 @var{horizontal} @code{nil} it includes the mode and header line, the
730 horizontal scroll bar and the bottom divider, if present. With
731 @var{horizontal} non-@code{nil} it includes the margins and fringes, the
732 vertical scroll bar and the right divider, if present.
734 The optional argument @var{ignore}, if non-@code{nil}, means ignore
735 restrictions imposed by fixed size windows, @code{window-min-height} or
736 @code{window-min-width} settings. If @var{ignore} equals @code{safe},
737 live windows may get as small as @code{window-safe-min-height} lines and
738 @code{window-safe-min-width} columns. If @var{ignore} is a window,
739 ignore restrictions for that window only. Any other non-@code{nil}
740 value means ignore all of the above restrictions for all windows.
742 The optional argument @var{pixelwise} non-@code{nil} means to return the
743 minimum size of @var{window} counted in pixels.
746 @node Resizing Windows
747 @section Resizing Windows
748 @cindex window resizing
749 @cindex resize window
750 @cindex changing window size
751 @cindex window size, changing
753 This section describes functions for resizing a window without
754 changing the size of its frame. Because live windows do not overlap,
755 these functions are meaningful only on frames that contain two or more
756 windows: resizing a window also changes the size of a neighboring
757 window. If there is just one window on a frame, its size cannot be
758 changed except by resizing the frame (@pxref{Size and Position}).
760 Except where noted, these functions also accept internal windows as
761 arguments. Resizing an internal window causes its child windows to be
762 resized to fit the same space.
764 @defun window-resizable window delta &optional horizontal ignore pixelwise
765 This function returns @var{delta} if the size of @var{window} can be
766 changed vertically by @var{delta} lines. If the optional argument
767 @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
768 @var{window} can be resized horizontally by @var{delta} columns. It
769 does not actually change the window size.
771 If @var{window} is @code{nil}, it defaults to the selected window.
773 A positive value of @var{delta} means to check whether the window can be
774 enlarged by that number of lines or columns; a negative value of
775 @var{delta} means to check whether the window can be shrunk by that many
776 lines or columns. If @var{delta} is non-zero, a return value of 0 means
777 that the window cannot be resized.
779 Normally, the variables @code{window-min-height} and
780 @code{window-min-width} specify the smallest allowable window size
781 (@pxref{Window Sizes}). However, if the optional argument @var{ignore}
782 is non-@code{nil}, this function ignores @code{window-min-height} and
783 @code{window-min-width}, as well as @code{window-size-fixed}. Instead,
784 it considers the minimum-height window to be one consisting of a header
785 and a mode line, a horizontal scrollbar and a bottom divider (if any),
786 plus a text area one line tall; and a minimum-width window as one
787 consisting of fringes, margins, a scroll bar and a right divider (if
788 any), plus a text area two columns wide.
790 If the optional argument @var{pixelwise} is non-@code{nil},
791 @var{delta} is interpreted as pixels.
794 @defun window-resize window delta &optional horizontal ignore pixelwise
795 This function resizes @var{window} by @var{delta} increments. If
796 @var{horizontal} is @code{nil}, it changes the height by @var{delta}
797 lines; otherwise, it changes the width by @var{delta} columns. A
798 positive @var{delta} means to enlarge the window, and a negative
799 @var{delta} means to shrink it.
801 If @var{window} is @code{nil}, it defaults to the selected window. If
802 the window cannot be resized as demanded, an error is signaled.
804 The optional argument @var{ignore} has the same meaning as for the
805 function @code{window-resizable} above.
807 If the optional argument @var{pixelwise} is non-@code{nil},
808 @var{delta} will be interpreted as pixels.
810 The choice of which window edges this function alters depends on the
811 values of the option @code{window-combination-resize} and the
812 combination limits of the involved windows; in some cases, it may alter
813 both edges. @xref{Recombining Windows}. To resize by moving only the
814 bottom or right edge of a window, use the function
815 @code{adjust-window-trailing-edge}.
818 @c The commands enlarge-window, enlarge-window-horizontally,
819 @c shrink-window, and shrink-window-horizontally are documented in the
820 @c Emacs manual. They are not preferred for calling from Lisp.
822 @defun adjust-window-trailing-edge window delta &optional horizontal pixelwise
823 This function moves @var{window}'s bottom edge by @var{delta} lines.
824 If optional argument @var{horizontal} is non-@code{nil}, it instead
825 moves the right edge by @var{delta} columns. If @var{window} is
826 @code{nil}, it defaults to the selected window.
828 If the optional argument @var{pixelwise} is non-@code{nil},
829 @var{delta} is interpreted as pixels.
831 A positive @var{delta} moves the edge downwards or to the right; a
832 negative @var{delta} moves it upwards or to the left. If the edge
833 cannot be moved as far as specified by @var{delta}, this function
834 moves it as far as possible but does not signal a error.
836 This function tries to resize windows adjacent to the edge that is
837 moved. If this is not possible for some reason (e.g., if that adjacent
838 window is fixed-size), it may resize other windows.
841 @cindex pixelwise, resizing windows
842 @defopt window-resize-pixelwise
843 If the value of this option is non-@code{nil}, Emacs resizes windows in
844 units of pixels. This currently affects functions like
845 @code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
846 @code{minimize-window}, @code{fit-window-to-buffer},
847 @code{fit-frame-to-buffer} and
848 @code{shrink-window-if-larger-than-buffer} (all listed below).
850 Note that when a frame's pixel size is not a multiple of its character
851 size, at least one window may get resized pixelwise even if this
852 option is @code{nil}. The default value is @code{nil}.
855 The following commands resize windows in more specific ways. When
856 called interactively, they act on the selected window.
858 @deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size
859 This command adjusts the height or width of @var{window} to fit the text
860 in it. It returns non-@code{nil} if it was able to resize @var{window},
861 and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
862 defaults to the selected window. Otherwise, it should be a live window.
864 If @var{window} is part of a vertical combination, this function adjusts
865 @var{window}'s height. The new height is calculated from the actual
866 height of the accessible portion of its buffer. The optional argument
867 @var{max-height}, if non-@code{nil}, specifies the maximum total height
868 that this function can give @var{window}. The optional argument
869 @var{min-height}, if non-@code{nil}, specifies the minimum total height
870 that it can give, which overrides the variable @code{window-min-height}.
871 Both @var{max-height} and @var{min-height} are specified in lines and
872 include mode and header line and a bottom divider, if any.
874 If @var{window} is part of a horizontal combination and the value of the
875 option @code{fit-window-to-buffer-horizontally} (see below) is
876 non-@code{nil}, this function adjusts @var{window}'s height. The new
877 width of @var{window} is calculated from the maximum length of its
878 buffer's lines that follow the current start position of @var{window}.
879 The optional argument @var{max-width} specifies a maximum width and
880 defaults to the width of @var{window}'s frame. The optional argument
881 @var{min-width} specifies a minimum width and defaults to
882 @code{window-min-width}. Both @var{max-width} and @var{min-width} are
883 specified in columns and include fringes, margins and scrollbars, if
886 The optional argument @var{preserve-size}, if non-@code{nil}, will
887 install a parameter to preserve the size of @var{window} during future
888 resize operations (@pxref{Preserving Window Sizes}).
890 If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
891 this function will try to resize the frame of @var{window} to fit its
892 contents by calling @code{fit-frame-to-buffer} (see below).
895 @defopt fit-window-to-buffer-horizontally
896 If this is non-@code{nil}, @code{fit-window-to-buffer} can resize
897 windows horizontally. If this is @code{nil} (the default)
898 @code{fit-window-to-buffer} never resizes windows horizontally. If this
899 is @code{only}, it can resize windows horizontally only. Any other
900 value means @code{fit-window-to-buffer} can resize windows in both
904 @defopt fit-frame-to-buffer
905 If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a
906 frame to its buffer. A frame is fit if and only if its root window is a
907 live window and this option is non-@code{nil}. If this is
908 @code{horizontally}, frames are fit horizontally only. If this is
909 @code{vertically}, frames are fit vertically only. Any other
910 non-@code{nil} value means frames can be resized in both dimensions.
913 If you have a frame that displays only one window, you can fit that
914 frame to its buffer using the command @code{fit-frame-to-buffer}.
916 @deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
917 This command adjusts the size of @var{frame} to display the contents of
918 its buffer exactly. @var{frame} can be any live frame and defaults to
919 the selected one. Fitting is done only if @var{frame}'s root window is
920 live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
921 and @var{min-width} specify bounds on the new total size of
922 @var{frame}'s root window. @var{min-height} and @var{min-width} default
923 to the values of @code{window-min-height} and @code{window-min-width}
926 If the optional argument @var{only} is @code{vertically}, this function
927 may resize the frame vertically only. If @var{only} is
928 @code{horizontally}, it may resize the frame horizontally only.
931 The behavior of @code{fit-frame-to-buffer} can be controlled with the
932 help of the two options listed next.
934 @defopt fit-frame-to-buffer-margins
935 This option can be used to specify margins around frames to be fit by
936 @code{fit-frame-to-buffer}. Such margins can be useful to avoid, for
937 example, that such frames overlap the taskbar.
939 It specifies the numbers of pixels to be left free on the left, above,
940 the right, and below a frame that shall be fit. The default specifies
941 @code{nil} for each which means to use no margins. The value specified
942 here can be overridden for a specific frame by that frame's
943 @code{fit-frame-to-buffer-margins} parameter, if present.
946 @defopt fit-frame-to-buffer-sizes
947 This option specifies size boundaries for @code{fit-frame-to-buffer}.
948 It specifies the total maximum and minimum lines and maximum and minimum
949 columns of the root window of any frame that shall be fit to its buffer.
950 If any of these values is non-@code{nil}, it overrides the corresponding
951 argument of @code{fit-frame-to-buffer}.
954 @deffn Command shrink-window-if-larger-than-buffer &optional window
955 This command attempts to reduce @var{window}'s height as much as
956 possible while still showing its full buffer, but no less than
957 @code{window-min-height} lines. The return value is non-@code{nil} if
958 the window was resized, and @code{nil} otherwise. If @var{window} is
959 omitted or @code{nil}, it defaults to the selected window. Otherwise,
960 it should be a live window.
962 This command does nothing if the window is already too short to
963 display all of its buffer, or if any of the buffer is scrolled
964 off-screen, or if the window is the only live window in its frame.
966 This command calls @code{fit-window-to-buffer} (see above) to do its
971 @cindex balancing window sizes
972 @deffn Command balance-windows &optional window-or-frame
973 This function balances windows in a way that gives more space to
974 full-width and/or full-height windows. If @var{window-or-frame}
975 specifies a frame, it balances all windows on that frame. If
976 @var{window-or-frame} specifies a window, it balances only that window
977 and its siblings (@pxref{Windows and Frames}).
980 @deffn Command balance-windows-area
981 This function attempts to give all windows on the selected frame
982 approximately the same share of the screen area. Full-width or
983 full-height windows are not given more space than other windows.
986 @cindex maximizing windows
987 @deffn Command maximize-window &optional window
988 This function attempts to make @var{window} as large as possible, in
989 both dimensions, without resizing its frame or deleting other windows.
990 If @var{window} is omitted or @code{nil}, it defaults to the selected
994 @cindex minimizing windows
995 @deffn Command minimize-window &optional window
996 This function attempts to make @var{window} as small as possible, in
997 both dimensions, without deleting it or resizing its frame. If
998 @var{window} is omitted or @code{nil}, it defaults to the selected
1003 @node Preserving Window Sizes
1004 @section Preserving Window Sizes
1005 @cindex preserving window sizes
1007 A window can get resized explicitly by using one of the functions from
1008 the preceding section or implicitly, for example, when resizing an
1009 adjacent window, when splitting or deleting a window (@pxref{Splitting
1010 Windows}, @pxref{Deleting Windows}) or when resizing the window's frame
1011 (@pxref{Size and Position}).
1013 It is possible to avoid implicit resizing of a specific window when
1014 there are one or more other resizable windows on the same frame. For
1015 this purpose, Emacs must be advised to @dfn{preserve} the size of that
1016 window. There are two basic ways to do that.
1018 @defvar window-size-fixed
1019 If this buffer-local variable is non-@code{nil}, the size of any window
1020 displaying the buffer cannot normally be changed. Deleting a window or
1021 changing the frame's size may still change the window's size, if there
1024 If the value is @code{height}, then only the window's height is fixed;
1025 if the value is @code{width}, then only the window's width is fixed.
1026 Any other non-@code{nil} value fixes both the width and the height.
1028 If this variable is @code{nil}, this does not necessarily mean that any
1029 window showing the buffer can be resized in the desired direction. To
1030 determine that, use the function @code{window-resizable}.
1031 @xref{Resizing Windows}.
1034 Often @code{window-size-fixed} is overly aggressive because it inhibits
1035 any attempt to explicitly resize or split an affected window as well.
1036 This may even happen after the window has been resized implicitly, for
1037 example, when deleting an adjacent window or resizing the window's
1038 frame. The following function tries hard to never disallow resizing
1039 such a window explicitly:
1041 @defun window-preserve-size &optional window horizontal preserve
1042 This function (un-)marks the height of window @var{window} as preserved
1043 for future resize operations. @var{window} must be a live window and
1044 defaults to the selected one. If the optional argument @var{horizontal}
1045 is non-@code{nil}, it (un-)marks the width of @var{window} as preserved.
1047 If the optional argument @var{preserve} is @code{t}, this means to
1048 preserve the current height/width of @var{window}'s body. The
1049 height/width of @var{window} will change only if Emacs has no better
1050 choice. Resizing a window whose height/width is preserved by this
1051 function never throws an error.
1053 If @var{preserve} is @code{nil}, this means to stop preserving the
1054 height/width of @var{window}, lifting any respective restraint induced
1055 by a previous call of this function for @var{window}. Calling
1056 @code{enlarge-window}, @code{shrink-window} or
1057 @code{fit-window-to-buffer} with @var{window} as argument may also
1058 remove the respective restraint.
1061 @code{window-preserve-size} is currently invoked by the following
1065 @item fit-window-to-buffer
1066 If the optional argument @var{preserve-size} of that function
1067 (@pxref{Resizing Windows}) is non-@code{nil}, the size established by
1068 that function is preserved.
1070 @item display-buffer
1071 If the @var{alist} argument of that function (@pxref{Choosing Window})
1072 contains a @code{preserve-size} entry, the size of the window produced
1073 by that function is preserved.
1076 @code{window-preserve-size} installs a window parameter (@pxref{Window
1077 Parameters}) called @code{preserved-size} which is consulted by the
1078 window resizing functions. This parameter will not prevent resizing the
1079 window when the window shows another buffer than the one when
1080 @code{window-preserve-size} was invoked or if its size has changed since
1083 The following function can be used to check whether the height of a
1084 particular window is preserved:
1086 @defun window-preserved-size &optional window horizontal
1087 This function returns the preserved height of window @var{window} in
1088 pixels. @var{window} must be a live window and defaults to the selected
1089 one. If the optional argument @var{horizontal} is non-@code{nil}, it
1090 returns the preserved width of @var{window}. It returns @code{nil} if
1091 the size of @var{window} is not preserved.
1095 @node Splitting Windows
1096 @section Splitting Windows
1097 @cindex splitting windows
1098 @cindex window splitting
1100 This section describes functions for creating a new window by
1101 @dfn{splitting} an existing one.
1103 @defun split-window &optional window size side pixelwise
1104 This function creates a new live window next to the window
1105 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
1106 to the selected window. That window is split, and reduced in
1107 size. The space is taken up by the new window, which is returned.
1109 The optional second argument @var{size} determines the sizes of
1110 @var{window} and/or the new window. If it is omitted or @code{nil},
1111 both windows are given equal sizes; if there is an odd line, it is
1112 allocated to the new window. If @var{size} is a positive number,
1113 @var{window} is given @var{size} lines (or columns, depending on the
1114 value of @var{side}). If @var{size} is a negative number, the new
1115 window is given @minus{}@var{size} lines (or columns).
1117 If @var{size} is @code{nil}, this function obeys the variables
1118 @code{window-min-height} and @code{window-min-width} (@pxref{Window
1119 Sizes}). Thus, it signals an error if splitting would result in making
1120 a window smaller than those variables specify. However, a
1121 non-@code{nil} value for @var{size} causes those variables to be
1122 ignored; in that case, the smallest allowable window is considered to be
1123 one that has space for a text area one line tall and/or two columns
1126 Hence, if @var{size} is specified, it's the caller's responsibility to
1127 check whether the emanating windows are large enough to encompass all
1128 areas like a mode line or a scroll bar. The function
1129 @code{window-min-size} (@pxref{Window Sizes}) can be used to determine
1130 the minimum requirements of @var{window} in this regard. Since the new
1131 window usually inherits areas like the mode line or the scroll bar
1132 from @var{window}, that function is also a good guess for the minimum
1133 size of the new window. The caller should specify a smaller size only
1134 if it correspondingly removes an inherited area before the next
1137 The optional third argument @var{side} determines the position of the
1138 new window relative to @var{window}. If it is @code{nil} or
1139 @code{below}, the new window is placed below @var{window}. If it is
1140 @code{above}, the new window is placed above @var{window}. In both
1141 these cases, @var{size} specifies a total window height, in lines.
1143 If @var{side} is @code{t} or @code{right}, the new window is placed on
1144 the right of @var{window}. If @var{side} is @code{left}, the new
1145 window is placed on the left of @var{window}. In both these cases,
1146 @var{size} specifies a total window width, in columns.
1148 The optional fourth argument @var{pixelwise}, if non-@code{nil}, means
1149 to interpret @var{size} in units of pixels, instead of lines and
1152 If @var{window} is a live window, the new window inherits various
1153 properties from it, including margins and scroll bars. If
1154 @var{window} is an internal window, the new window inherits the
1155 properties of the window selected within @var{window}'s frame.
1157 The behavior of this function may be altered by the window parameters
1158 of @var{window}, so long as the variable
1159 @code{ignore-window-parameters} is @code{nil}. If the value of
1160 the @code{split-window} window parameter is @code{t}, this function
1161 ignores all other window parameters. Otherwise, if the value of the
1162 @code{split-window} window parameter is a function, that function is
1163 called with the arguments @var{window}, @var{size}, and @var{side}, in
1164 lieu of the usual action of @code{split-window}. Otherwise, this
1165 function obeys the @code{window-atom} or @code{window-side} window
1166 parameter, if any. @xref{Window Parameters}.
1169 As an example, here is a sequence of @code{split-window} calls that
1170 yields the window configuration discussed in @ref{Windows and Frames}.
1171 This example demonstrates splitting a live window as well as splitting
1172 an internal window. We begin with a frame containing a single window
1173 (a live root window), which we denote by @var{W4}. Calling
1174 @code{(split-window W4)} yields this window configuration:
1178 ______________________________________
1179 | ____________________________________ |
1183 ||_________________W4_________________||
1184 | ____________________________________ |
1188 ||_________________W5_________________||
1189 |__________________W3__________________|
1195 The @code{split-window} call has created a new live window, denoted by
1196 @var{W5}. It has also created a new internal window, denoted by
1197 @var{W3}, which becomes the root window and the parent of both
1198 @var{W4} and @var{W5}.
1200 Next, we call @code{(split-window W3 nil 'left)}, passing the
1201 internal window @var{W3} as the argument. The result:
1205 ______________________________________
1206 | ______ ____________________________ |
1207 || || __________________________ ||
1211 || |||____________W4____________|||
1212 || || __________________________ ||
1215 || |||____________W5____________|||
1216 ||__W2__||_____________W3_____________ |
1217 |__________________W1__________________|
1222 A new live window @var{W2} is created, to the left of the internal
1223 window @var{W3}. A new internal window @var{W1} is created, becoming
1224 the new root window.
1226 For interactive use, Emacs provides two commands which always split
1227 the selected window. These call @code{split-window} internally.
1229 @deffn Command split-window-right &optional size
1230 This function splits the selected window into two side-by-side
1231 windows, putting the selected window on the left. If @var{size} is
1232 positive, the left window gets @var{size} columns; if @var{size} is
1233 negative, the right window gets @minus{}@var{size} columns.
1236 @deffn Command split-window-below &optional size
1237 This function splits the selected window into two windows, one above
1238 the other, leaving the upper window selected. If @var{size} is
1239 positive, the upper window gets @var{size} lines; if @var{size} is
1240 negative, the lower window gets @minus{}@var{size} lines.
1243 @defopt split-window-keep-point
1244 If the value of this variable is non-@code{nil} (the default),
1245 @code{split-window-below} behaves as described above.
1247 If it is @code{nil}, @code{split-window-below} adjusts point in each
1248 of the two windows to minimize redisplay. (This is useful on slow
1249 terminals.) It selects whichever window contains the screen line that
1250 point was previously on. Note that this only affects
1251 @code{split-window-below}, not the lower-level @code{split-window}
1256 @node Deleting Windows
1257 @section Deleting Windows
1258 @cindex deleting windows
1260 @dfn{Deleting} a window removes it from the frame's window tree. If
1261 the window is a live window, it disappears from the screen. If the
1262 window is an internal window, its child windows are deleted too.
1264 Even after a window is deleted, it continues to exist as a Lisp
1265 object, until there are no more references to it. Window deletion can
1266 be reversed, by restoring a saved window configuration (@pxref{Window
1269 @deffn Command delete-window &optional window
1270 This function removes @var{window} from display and returns
1271 @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
1272 the selected window. If deleting the window would leave no more
1273 windows in the window tree (e.g., if it is the only live window in the
1274 frame), an error is signaled.
1276 By default, the space taken up by @var{window} is given to one of its
1277 adjacent sibling windows, if any. However, if the variable
1278 @code{window-combination-resize} is non-@code{nil}, the space is
1279 proportionally distributed among any remaining windows in the same
1280 window combination. @xref{Recombining Windows}.
1282 The behavior of this function may be altered by the window parameters
1283 of @var{window}, so long as the variable
1284 @code{ignore-window-parameters} is @code{nil}. If the value of
1285 the @code{delete-window} window parameter is @code{t}, this function
1286 ignores all other window parameters. Otherwise, if the value of the
1287 @code{delete-window} window parameter is a function, that function is
1288 called with the argument @var{window}, in lieu of the usual action of
1289 @code{delete-window}. Otherwise, this function obeys the
1290 @code{window-atom} or @code{window-side} window parameter, if any.
1291 @xref{Window Parameters}.
1294 @deffn Command delete-other-windows &optional window
1295 This function makes @var{window} fill its frame, by deleting other
1296 windows as necessary. If @var{window} is omitted or @code{nil}, it
1297 defaults to the selected window. The return value is @code{nil}.
1299 The behavior of this function may be altered by the window parameters
1300 of @var{window}, so long as the variable
1301 @code{ignore-window-parameters} is @code{nil}. If the value of
1302 the @code{delete-other-windows} window parameter is @code{t}, this
1303 function ignores all other window parameters. Otherwise, if the value
1304 of the @code{delete-other-windows} window parameter is a function,
1305 that function is called with the argument @var{window}, in lieu of the
1306 usual action of @code{delete-other-windows}. Otherwise, this function
1307 obeys the @code{window-atom} or @code{window-side} window parameter,
1308 if any. @xref{Window Parameters}.
1311 @deffn Command delete-windows-on &optional buffer-or-name frame
1312 This function deletes all windows showing @var{buffer-or-name}, by
1313 calling @code{delete-window} on those windows. @var{buffer-or-name}
1314 should be a buffer, or the name of a buffer; if omitted or @code{nil},
1315 it defaults to the current buffer. If there are no windows showing
1316 the specified buffer, this function does nothing. If the specified
1317 buffer is a minibuffer, an error is signaled.
1319 If there is a dedicated window showing the buffer, and that window is
1320 the only one on its frame, this function also deletes that frame if it
1321 is not the only frame on the terminal.
1323 The optional argument @var{frame} specifies which frames to operate
1328 means operate on all frames.
1330 means operate on the selected frame.
1331 @item @code{visible}
1332 means operate on all visible frames.
1334 means operate on all visible or iconified frames.
1336 means operate on that frame.
1339 Note that this argument does not have the same meaning as in other
1340 functions which scan all live windows (@pxref{Cyclic Window
1341 Ordering}). Specifically, the meanings of @code{t} and @code{nil} here
1342 are the opposite of what they are in those other functions.
1346 @node Recombining Windows
1347 @section Recombining Windows
1348 @cindex recombining windows
1349 @cindex windows, recombining
1351 When deleting the last sibling of a window @var{W}, its parent window
1352 is deleted too, with @var{W} replacing it in the window tree. This
1353 means that @var{W} must be recombined with its parent's siblings to
1354 form a new window combination (@pxref{Windows and Frames}). In some
1355 occasions, deleting a live window may even entail the deletion of two
1360 ______________________________________
1361 | ______ ____________________________ |
1362 || || __________________________ ||
1363 || ||| ___________ ___________ |||
1365 || ||||____W6_____||_____W7____||||
1366 || |||____________W4____________|||
1367 || || __________________________ ||
1370 || |||____________W5____________|||
1371 ||__W2__||_____________W3_____________ |
1372 |__________________W1__________________|
1378 Deleting @var{W5} in this configuration normally causes the deletion of
1379 @var{W3} and @var{W4}. The remaining live windows @var{W2},
1380 @var{W6} and @var{W7} are recombined to form a new horizontal
1381 combination with parent @var{W1}.
1383 Sometimes, however, it makes sense to not delete a parent window like
1384 @var{W4}. In particular, a parent window should not be removed when it
1385 was used to preserve a combination embedded in a combination of the same
1386 type. Such embeddings make sense to assure that when you split a window
1387 and subsequently delete the new window, Emacs reestablishes the layout
1388 of the associated frame as it existed before the splitting.
1390 Consider a scenario starting with two live windows @var{W2} and
1391 @var{W3} and their parent @var{W1}.
1395 ______________________________________
1396 | ____________________________________ |
1403 ||_________________W2_________________||
1404 | ____________________________________ |
1407 ||_________________W3_________________||
1408 |__________________W1__________________|
1414 Split @var{W2} to make a new window @var{W4} as follows.
1418 ______________________________________
1419 | ____________________________________ |
1422 ||_________________W2_________________||
1423 | ____________________________________ |
1426 ||_________________W4_________________||
1427 | ____________________________________ |
1430 ||_________________W3_________________||
1431 |__________________W1__________________|
1437 Now, when enlarging a window vertically, Emacs tries to obtain the
1438 corresponding space from its lower sibling, provided such a window
1439 exists. In our scenario, enlarging @var{W4} will steal space from
1444 ______________________________________
1445 | ____________________________________ |
1448 ||_________________W2_________________||
1449 | ____________________________________ |
1454 ||_________________W4_________________||
1455 | ____________________________________ |
1456 ||_________________W3_________________||
1457 |__________________W1__________________|
1463 Deleting @var{W4} will now give its entire space to @var{W2},
1464 including the space earlier stolen from @var{W3}.
1468 ______________________________________
1469 | ____________________________________ |
1478 ||_________________W2_________________||
1479 | ____________________________________ |
1480 ||_________________W3_________________||
1481 |__________________W1__________________|
1487 This can be counterintuitive, in particular if @var{W4} were used for
1488 displaying a buffer only temporarily (@pxref{Temporary Displays}), and
1489 you want to continue working with the initial layout.
1491 The behavior can be fixed by making a new parent window when splitting
1492 @var{W2}. The variable described next allows that to be done.
1494 @defopt window-combination-limit
1495 This variable controls whether splitting a window shall make a new
1496 parent window. The following values are recognized:
1500 This means that the new live window is allowed to share the existing
1501 parent window, if one exists, provided the split occurs in the same
1502 direction as the existing window combination (otherwise, a new internal
1503 window is created anyway).
1506 In this case @code{display-buffer} makes a new parent window if it is
1507 passed a @code{window-height} or @code{window-width} entry in the
1508 @var{alist} argument (@pxref{Display Action Functions}).
1511 This value causes the creation of a new parent window when a window is
1512 split for showing a temporary buffer (@pxref{Temporary Displays}) only.
1514 @item display-buffer
1515 This means that when @code{display-buffer} (@pxref{Choosing Window})
1516 splits a window it always makes a new parent window.
1519 In this case a new parent window is always created when splitting a
1520 window. Thus, if the value of this variable is at all times @code{t},
1521 then at all times every window tree is a binary tree (a tree where each
1522 window except the root window has exactly one sibling).
1525 The default is @code{nil}. Other values are reserved for future use.
1527 If, as a consequence of this variable's setting, @code{split-window}
1528 makes a new parent window, it also calls
1529 @code{set-window-combination-limit} (see below) on the newly-created
1530 internal window. This affects how the window tree is rearranged when
1531 the child windows are deleted (see below).
1534 If @code{window-combination-limit} is @code{t}, splitting @var{W2} in
1535 the initial configuration of our scenario would have produced this:
1539 ______________________________________
1540 | ____________________________________ |
1541 || __________________________________ ||
1543 |||________________W2________________|||
1544 || __________________________________ ||
1546 |||________________W4________________|||
1547 ||_________________W5_________________||
1548 | ____________________________________ |
1551 ||_________________W3_________________||
1552 |__________________W1__________________|
1558 A new internal window @var{W5} has been created; its children are
1559 @var{W2} and the new live window @var{W4}. Now, @var{W2} is the only
1560 sibling of @var{W4}, so enlarging @var{W4} will try to shrink
1561 @var{W2}, leaving @var{W3} unaffected. Observe that @var{W5}
1562 represents a vertical combination of two windows embedded in the
1563 vertical combination @var{W1}.
1565 @cindex window combination limit
1566 @defun set-window-combination-limit window limit
1567 This function sets the @dfn{combination limit} of the window
1568 @var{window} to @var{limit}. This value can be retrieved via the
1569 function @code{window-combination-limit}. See below for its effects;
1570 note that it is only meaningful for internal windows. The
1571 @code{split-window} function automatically calls this function, passing
1572 it @code{t} as @var{limit}, provided the value of the variable
1573 @code{window-combination-limit} is @code{t} when it is called.
1576 @defun window-combination-limit window
1577 This function returns the combination limit for @var{window}.
1579 The combination limit is meaningful only for an internal window. If it
1580 is @code{nil}, then Emacs is allowed to automatically delete
1581 @var{window}, in response to a window deletion, in order to group the
1582 child windows of @var{window} with its sibling windows to form a new
1583 window combination. If the combination limit is @code{t}, the child
1584 windows of @var{window} are never automatically recombined with its
1587 If, in the configuration shown at the beginning of this section, the
1588 combination limit of @var{W4} (the parent window of @var{W6} and
1589 @var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete
1593 Alternatively, the problems sketched above can be avoided by always
1594 resizing all windows in the same combination whenever one of its windows
1595 is split or deleted. This also permits splitting windows that would be
1596 otherwise too small for such an operation.
1598 @defopt window-combination-resize
1599 If this variable is @code{nil}, @code{split-window} can only split a
1600 window (denoted by @var{window}) if @var{window}'s screen area is large
1601 enough to accommodate both itself and the new window.
1603 If this variable is @code{t}, @code{split-window} tries to resize all
1604 windows that are part of the same combination as @var{window}, in order
1605 to accommodate the new window. In particular, this may allow
1606 @code{split-window} to succeed even if @var{window} is a fixed-size
1607 window or too small to ordinarily split. Furthermore, subsequently
1608 resizing or deleting @var{window} may resize all other windows in its
1611 The default is @code{nil}. Other values are reserved for future use.
1612 The value of this variable is ignored when
1613 @code{window-combination-limit} is non-@code{nil}.
1616 To illustrate the effect of @code{window-combination-resize}, consider
1617 the following frame layout.
1621 ______________________________________
1622 | ____________________________________ |
1627 ||_________________W2_________________||
1628 | ____________________________________ |
1633 ||_________________W3_________________||
1634 |__________________W1__________________|
1640 If @code{window-combination-resize} is @code{nil}, splitting window
1641 @var{W3} leaves the size of @var{W2} unchanged:
1645 ______________________________________
1646 | ____________________________________ |
1651 ||_________________W2_________________||
1652 | ____________________________________ |
1654 ||_________________W3_________________||
1655 | ____________________________________ |
1657 ||_________________W4_________________||
1658 |__________________W1__________________|
1664 If @code{window-combination-resize} is @code{t}, splitting @var{W3}
1665 instead leaves all three live windows with approximately the same
1670 ______________________________________
1671 | ____________________________________ |
1674 ||_________________W2_________________||
1675 | ____________________________________ |
1678 ||_________________W3_________________||
1679 | ____________________________________ |
1682 ||_________________W4_________________||
1683 |__________________W1__________________|
1689 Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will
1690 distribute its space proportionally among the two remaining live
1694 @node Selecting Windows
1695 @section Selecting Windows
1696 @cindex selecting a window
1698 @defun select-window window &optional norecord
1699 This function makes @var{window} the selected window and the window
1700 selected within its frame (@pxref{Basic Windows}) and selects that
1701 frame. It also makes @var{window}'s buffer (@pxref{Buffers and
1702 Windows}) current and sets that buffer's value of @code{point} to the
1703 value of @code{window-point} (@pxref{Window Point}) in @var{window}.
1704 @var{window} must be a live window. The return value is @var{window}.
1706 By default, this function also moves @var{window}'s buffer to the front
1707 of the buffer list (@pxref{Buffer List}), and makes @var{window} the
1708 most recently selected window. However, if the optional argument
1709 @var{norecord} is non-@code{nil}, these additional actions are omitted.
1711 This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
1712 unless @var{norecord} is non-@code{nil}. Note that applications and
1713 internal routines often temporarily select a window in order to simplify
1714 coding. As a rule, such selections (including those made by the macros
1715 @code{save-selected-window} and @code{with-selected-window} below) are
1716 not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
1717 Selections that really count are those causing a visible change in
1718 the next redisplay of @var{window}'s frame and should be always
1719 recorded. This also means that to run a function each time a window
1720 gets selected, putting it on @code{buffer-list-update-hook} should be
1724 @cindex most recently selected windows
1725 The sequence of calls to @code{select-window} with a non-@code{nil}
1726 @var{norecord} argument determines an ordering of windows by their
1727 selection time. The function @code{get-lru-window} can be used to
1728 retrieve the least recently selected live window (@pxref{Cyclic Window
1731 @defmac save-selected-window forms@dots{}
1732 This macro records the selected frame, as well as the selected window
1733 of each frame, executes @var{forms} in sequence, then restores the
1734 earlier selected frame and windows. It also saves and restores the
1735 current buffer. It returns the value of the last form in @var{forms}.
1737 This macro does not save or restore anything about the sizes,
1738 arrangement or contents of windows; therefore, if @var{forms} change
1739 them, the change persists. If the previously selected window of some
1740 frame is no longer live at the time of exit from @var{forms}, that
1741 frame's selected window is left alone. If the previously selected
1742 window is no longer live, then whatever window is selected at the end of
1743 @var{forms} remains selected. The current buffer is restored if and
1744 only if it is still live when exiting @var{forms}.
1746 This macro changes neither the ordering of recently selected windows nor
1750 @defmac with-selected-window window forms@dots{}
1751 This macro selects @var{window}, executes @var{forms} in sequence, then
1752 restores the previously selected window and current buffer. The ordering
1753 of recently selected windows and the buffer list remain unchanged unless
1754 you deliberately change them within @var{forms}; for example, by calling
1755 @code{select-window} with argument @var{norecord} @code{nil}.
1757 This macro does not change the order of recently selected windows or
1761 @defun frame-selected-window &optional frame
1762 This function returns the window on @var{frame} that is selected
1763 within that frame. @var{frame} should be a live frame; if omitted or
1764 @code{nil}, it defaults to the selected frame.
1767 @defun set-frame-selected-window frame window &optional norecord
1768 This function makes @var{window} the window selected within the frame
1769 @var{frame}. @var{frame} should be a live frame; if @code{nil}, it
1770 defaults to the selected frame. @var{window} should be a live window;
1771 if @code{nil}, it defaults to the selected window.
1773 If @var{frame} is the selected frame, this makes @var{window} the
1776 If the optional argument @var{norecord} is non-@code{nil}, this
1777 function does not alter the list of most recently selected windows,
1778 nor the buffer list.
1781 @cindex window use time
1782 @cindex use time of window
1783 @cindex window order by time of last use
1784 @defun window-use-time &optional window
1785 This functions returns the use time of window @var{window}.
1786 @var{window} must be a live window and defaults to the selected one.
1788 The @dfn{use time} of a window is not really a time value, but an
1789 integer that does increase monotonically with each call of
1790 @code{select-window} with a @code{nil} @var{norecord} argument. The
1791 window with the lowest use time is usually called the least recently
1792 used window while the window with the highest use time is called the
1793 most recently used one (@pxref{Cyclic Window Ordering}).
1797 @node Cyclic Window Ordering
1798 @section Cyclic Ordering of Windows
1799 @cindex cyclic ordering of windows
1800 @cindex ordering of windows, cyclic
1801 @cindex window ordering, cyclic
1803 When you use the command @kbd{C-x o} (@code{other-window}) to select
1804 some other window, it moves through live windows in a specific order.
1805 For any given configuration of windows, this order never varies. It
1806 is called the @dfn{cyclic ordering of windows}.
1808 The ordering is determined by a depth-first traversal of each frame's
1809 window tree, retrieving the live windows which are the leaf nodes of the
1810 tree (@pxref{Windows and Frames}). If the minibuffer is active, the
1811 minibuffer window is included too. The ordering is cyclic, so the last
1812 window in the sequence is followed by the first one.
1814 @defun next-window &optional window minibuf all-frames
1815 @cindex minibuffer window, and @code{next-window}
1816 This function returns a live window, the one following @var{window} in
1817 the cyclic ordering of windows. @var{window} should be a live window;
1818 if omitted or @code{nil}, it defaults to the selected window.
1820 The optional argument @var{minibuf} specifies whether minibuffer windows
1821 should be included in the cyclic ordering. Normally, when @var{minibuf}
1822 is @code{nil}, a minibuffer window is included only if it is currently
1823 active; this matches the behavior of @kbd{C-x o}. (Note that a
1824 minibuffer window is active as long as its minibuffer is in use; see
1827 If @var{minibuf} is @code{t}, the cyclic ordering includes all
1828 minibuffer windows. If @var{minibuf} is neither @code{t} nor
1829 @code{nil}, minibuffer windows are not included even if they are active.
1831 The optional argument @var{all-frames} specifies which frames to
1836 means to consider windows on @var{window}'s frame. If the minibuffer
1837 window is considered (as specified by the @var{minibuf} argument),
1838 then frames that share the minibuffer window are considered too.
1841 means to consider windows on all existing frames.
1843 @item @code{visible}
1844 means to consider windows on all visible frames.
1847 means to consider windows on all visible or iconified frames.
1850 means to consider windows on that specific frame.
1853 means to consider windows on @var{window}'s frame, and no others.
1856 If more than one frame is considered, the cyclic ordering is obtained
1857 by appending the orderings for those frames, in the same order as the
1858 list of all live frames (@pxref{Finding All Frames}).
1861 @defun previous-window &optional window minibuf all-frames
1862 This function returns a live window, the one preceding @var{window} in
1863 the cyclic ordering of windows. The other arguments are handled like
1864 in @code{next-window}.
1867 @deffn Command other-window count &optional all-frames
1868 This function selects a live window, one @var{count} places from the
1869 selected window in the cyclic ordering of windows. If @var{count} is
1870 a positive number, it skips @var{count} windows forwards; if
1871 @var{count} is negative, it skips @minus{}@var{count} windows
1872 backwards; if @var{count} is zero, that simply re-selects the selected
1873 window. When called interactively, @var{count} is the numeric prefix
1876 The optional argument @var{all-frames} has the same meaning as in
1877 @code{next-window}, like a @code{nil} @var{minibuf} argument to
1880 This function does not select a window that has a non-@code{nil}
1881 @code{no-other-window} window parameter (@pxref{Window Parameters}).
1884 @defun walk-windows fun &optional minibuf all-frames
1885 This function calls the function @var{fun} once for each live window,
1886 with the window as the argument.
1888 It follows the cyclic ordering of windows. The optional arguments
1889 @var{minibuf} and @var{all-frames} specify the set of windows
1890 included; these have the same arguments as in @code{next-window}. If
1891 @var{all-frames} specifies a frame, the first window walked is the
1892 first window on that frame (the one returned by
1893 @code{frame-first-window}), not necessarily the selected window.
1895 If @var{fun} changes the window configuration by splitting or deleting
1896 windows, that does not alter the set of windows walked, which is
1897 determined prior to calling @var{fun} for the first time.
1900 @defun one-window-p &optional no-mini all-frames
1901 This function returns @code{t} if the selected window is the only live
1902 window, and @code{nil} otherwise.
1904 If the minibuffer window is active, it is normally considered (so that
1905 this function returns @code{nil}). However, if the optional argument
1906 @var{no-mini} is non-@code{nil}, the minibuffer window is ignored even
1907 if active. The optional argument @var{all-frames} has the same
1908 meaning as for @code{next-window}.
1911 @cindex finding windows
1912 The following functions return a window which satisfies some
1913 criterion, without selecting it:
1915 @cindex least recently used window
1916 @defun get-lru-window &optional all-frames dedicated not-selected
1917 This function returns a live window which is heuristically the least
1918 recently used. The optional argument @var{all-frames} has
1919 the same meaning as in @code{next-window}.
1921 If any full-width windows are present, only those windows are
1922 considered. A minibuffer window is never a candidate. A dedicated
1923 window (@pxref{Dedicated Windows}) is never a candidate unless the
1924 optional argument @var{dedicated} is non-@code{nil}. The selected
1925 window is never returned, unless it is the only candidate. However, if
1926 the optional argument @var{not-selected} is non-@code{nil}, this
1927 function returns @code{nil} in that case.
1930 @cindex most recently used window
1931 @defun get-mru-window &optional all-frames dedicated not-selected
1932 This function is like @code{get-lru-window}, but it returns the most
1933 recently used window instead. The meaning of the arguments is the
1934 same as described for @code{get-lru-window}.
1937 @cindex largest window
1938 @defun get-largest-window &optional all-frames dedicated not-selected
1939 This function returns the window with the largest area (height times
1940 width). The optional argument @var{all-frames} specifies the windows to
1941 search, and has the same meaning as in @code{next-window}.
1943 A minibuffer window is never a candidate. A dedicated window
1944 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1945 argument @var{dedicated} is non-@code{nil}. The selected window is not
1946 a candidate if the optional argument @var{not-selected} is
1947 non-@code{nil}. If the optional argument @var{not-selected} is
1948 non-@code{nil} and the selected window is the only candidate, this
1949 function returns @code{nil}.
1951 If there are two candidate windows of the same size, this function
1952 prefers the one that comes first in the cyclic ordering of windows,
1953 starting from the selected window.
1956 @cindex window that satisfies a predicate
1957 @cindex conditional selection of windows
1958 @defun get-window-with-predicate predicate &optional minibuf all-frames default
1959 This function calls the function @var{predicate} for each of the
1960 windows in the cyclic order of windows in turn, passing it the window
1961 as an argument. If the predicate returns non-@code{nil} for any
1962 window, this function stops and returns that window. If no such
1963 window is found, the return value is @var{default} (which defaults to
1966 The optional arguments @var{minibuf} and @var{all-frames} specify the
1967 windows to search, and have the same meanings as in
1972 @node Buffers and Windows
1973 @section Buffers and Windows
1974 @cindex examining windows
1975 @cindex windows, controlling precisely
1976 @cindex buffers, controlled in windows
1978 This section describes low-level functions for examining and setting
1979 the contents of windows. @xref{Switching Buffers}, for higher-level
1980 functions for displaying a specific buffer in a window.
1982 @defun window-buffer &optional window
1983 This function returns the buffer that @var{window} is displaying. If
1984 @var{window} is omitted or @code{nil} it defaults to the selected
1985 window. If @var{window} is an internal window, this function returns
1989 @defun set-window-buffer window buffer-or-name &optional keep-margins
1990 This function makes @var{window} display @var{buffer-or-name}.
1991 @var{window} should be a live window; if @code{nil}, it defaults to
1992 the selected window. @var{buffer-or-name} should be a buffer, or the
1993 name of an existing buffer. This function does not change which
1994 window is selected, nor does it directly change which buffer is
1995 current (@pxref{Current Buffer}). Its return value is @code{nil}.
1997 If @var{window} is @dfn{strongly dedicated} to a buffer and
1998 @var{buffer-or-name} does not specify that buffer, this function
1999 signals an error. @xref{Dedicated Windows}.
2001 By default, this function resets @var{window}'s position, display
2002 margins, fringe widths, and scroll bar settings, based on the local
2003 variables in the specified buffer. However, if the optional argument
2004 @var{keep-margins} is non-@code{nil}, it leaves the display margins
2005 and fringe widths unchanged.
2007 When writing an application, you should normally use the higher-level
2008 functions described in @ref{Switching Buffers}, instead of calling
2009 @code{set-window-buffer} directly.
2011 This runs @code{window-scroll-functions}, followed by
2012 @code{window-configuration-change-hook}. @xref{Window Hooks}.
2015 @defvar buffer-display-count
2016 This buffer-local variable records the number of times a buffer has been
2017 displayed in a window. It is incremented each time
2018 @code{set-window-buffer} is called for the buffer.
2021 @defvar buffer-display-time
2022 This buffer-local variable records the time at which a buffer was last
2023 displayed in a window. The value is @code{nil} if the buffer has
2024 never been displayed. It is updated each time
2025 @code{set-window-buffer} is called for the buffer, with the value
2026 returned by @code{current-time} (@pxref{Time of Day}).
2029 @defun get-buffer-window &optional buffer-or-name all-frames
2030 This function returns the first window displaying @var{buffer-or-name}
2031 in the cyclic ordering of windows, starting from the selected window
2032 (@pxref{Cyclic Window Ordering}). If no such window exists, the
2033 return value is @code{nil}.
2035 @var{buffer-or-name} should be a buffer or the name of a buffer; if
2036 omitted or @code{nil}, it defaults to the current buffer. The
2037 optional argument @var{all-frames} specifies which windows to
2042 @code{t} means consider windows on all existing frames.
2044 @code{visible} means consider windows on all visible frames.
2046 0 means consider windows on all visible or iconified frames.
2048 A frame means consider windows on that frame only.
2050 Any other value means consider windows on the selected frame.
2053 Note that these meanings differ slightly from those of the
2054 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
2055 Ordering}). This function may be changed in a future version of Emacs
2056 to eliminate this discrepancy.
2059 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
2060 This function returns a list of all windows currently displaying
2061 @var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the
2062 name of an existing buffer. If omitted or @code{nil}, it defaults to
2063 the current buffer. If the currently selected window displays
2064 @var{buffer-or-name}, it will be the first in the list returned by
2067 The arguments @var{minibuf} and @var{all-frames} have the same
2068 meanings as in the function @code{next-window} (@pxref{Cyclic Window
2069 Ordering}). Note that the @var{all-frames} argument does @emph{not}
2070 behave exactly like in @code{get-buffer-window}.
2073 @deffn Command replace-buffer-in-windows &optional buffer-or-name
2074 This command replaces @var{buffer-or-name} with some other buffer, in
2075 all windows displaying it. @var{buffer-or-name} should be a buffer, or
2076 the name of an existing buffer; if omitted or @code{nil}, it defaults to
2079 The replacement buffer in each window is chosen via
2080 @code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated
2081 window displaying @var{buffer-or-name} is deleted if possible
2082 (@pxref{Dedicated Windows}). If such a window is the only window on its
2083 frame and there are other frames on the same terminal, the frame is
2084 deleted as well. If the dedicated window is the only window on the only
2085 frame on its terminal, the buffer is replaced anyway.
2089 @node Switching Buffers
2090 @section Switching to a Buffer in a Window
2091 @cindex switching to a buffer
2092 @cindex displaying a buffer
2094 This section describes high-level functions for switching to a specified
2095 buffer in some window. In general, ``switching to a buffer'' means to
2096 (1) show the buffer in some window, (2) make that window the selected
2097 window (and its frame the selected frame), and (3) make the buffer the
2100 Do @emph{not} use these functions to make a buffer temporarily
2101 current just so a Lisp program can access or modify it. They have
2102 side-effects, such as changing window histories (@pxref{Window
2103 History}), which will surprise the user if used that way. If you want
2104 to make a buffer current to modify it in Lisp, use
2105 @code{with-current-buffer}, @code{save-current-buffer}, or
2106 @code{set-buffer}. @xref{Current Buffer}.
2108 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
2109 This command attempts to display @var{buffer-or-name} in the selected
2110 window and make it the current buffer. It is often used interactively
2111 (as the binding of @kbd{C-x b}), as well as in Lisp programs. The
2112 return value is the buffer switched to.
2114 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2115 returned by @code{other-buffer} (@pxref{Buffer List}). If
2116 @var{buffer-or-name} is a string that is not the name of any existing
2117 buffer, this function creates a new buffer with that name; the new
2118 buffer's major mode is determined by the variable @code{major-mode}
2119 (@pxref{Major Modes}).
2121 Normally, the specified buffer is put at the front of the buffer
2122 list---both the global buffer list and the selected frame's buffer
2123 list (@pxref{Buffer List}). However, this is not done if the
2124 optional argument @var{norecord} is non-@code{nil}.
2126 Sometimes, the selected window may not be suitable for displaying the
2127 buffer. This happens if the selected window is a minibuffer window, or
2128 if the selected window is strongly dedicated to its buffer
2129 (@pxref{Dedicated Windows}). In such cases, the command normally tries
2130 to display the buffer in some other window, by invoking
2131 @code{pop-to-buffer} (see below).
2133 If the optional argument @var{force-same-window} is non-@code{nil} and
2134 the selected window is not suitable for displaying the buffer, this
2135 function always signals an error when called non-interactively. In
2136 interactive use, if the selected window is a minibuffer window, this
2137 function will try to use some other window instead. If the selected
2138 window is strongly dedicated to its buffer, the option
2139 @code{switch-to-buffer-in-dedicated-window} described next can be used
2143 @defopt switch-to-buffer-in-dedicated-window
2144 This option, if non-@code{nil}, allows @code{switch-to-buffer} to
2145 proceed when called interactively and the selected window is strongly
2146 dedicated to its buffer.
2148 The following values are respected:
2152 Disallows switching and signals an error as in non-interactive use.
2155 Prompts the user whether to allow switching.
2158 Invokes @code{pop-to-buffer} to proceed.
2161 Marks the selected window as non-dedicated and proceeds.
2164 This option does not affect non-interactive calls of
2165 @code{switch-to-buffer}.
2168 By default, @code{switch-to-buffer} shows the buffer at its position of
2169 @code{point}. This behavior can be tuned using the following option.
2171 @defopt switch-to-buffer-preserve-window-point
2172 If this variable is @code{nil}, @code{switch-to-buffer} displays the
2173 buffer specified by @var{buffer-or-name} at the position of that
2174 buffer's @code{point}. If this variable is @code{already-displayed}, it
2175 tries to display the buffer at its previous position in the selected
2176 window, provided the buffer is currently displayed in some other window
2177 on any visible or iconified frame. If this variable is @code{t},
2178 @code{switch-to-buffer} unconditionally tries to display the buffer at
2179 its previous position in the selected window.
2181 This variable is ignored if the buffer is already displayed in the
2182 selected window or never appeared in it before, or if
2183 @code{switch-to-buffer} calls @code{pop-to-buffer} to display the
2187 The next two commands are similar to @code{switch-to-buffer}, except for
2188 the described features.
2190 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
2191 This function displays the buffer specified by @var{buffer-or-name} in
2192 some window other than the selected window. It uses the function
2193 @code{pop-to-buffer} internally (see below).
2195 If the selected window already displays the specified buffer, it
2196 continues to do so, but another window is nonetheless found to display
2199 The @var{buffer-or-name} and @var{norecord} arguments have the same
2200 meanings as in @code{switch-to-buffer}.
2203 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
2204 This function displays the buffer specified by @var{buffer-or-name} in a
2205 new frame. It uses the function @code{pop-to-buffer} internally (see
2208 If the specified buffer is already displayed in another window, in any
2209 frame on the current terminal, this switches to that window instead of
2210 creating a new frame. However, the selected window is never used for
2213 The @var{buffer-or-name} and @var{norecord} arguments have the same
2214 meanings as in @code{switch-to-buffer}.
2217 The above commands use the function @code{pop-to-buffer}, which
2218 flexibly displays a buffer in some window and selects that window for
2219 editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for
2220 displaying the buffer. Hence, all the variables affecting
2221 @code{display-buffer} will affect it as well. @xref{Choosing Window},
2222 for the documentation of @code{display-buffer}.
2224 @deffn Command pop-to-buffer buffer-or-name &optional action norecord
2225 This function makes @var{buffer-or-name} the current buffer and
2226 displays it in some window, preferably not the window currently
2227 selected. It then selects the displaying window. If that window is
2228 on a different graphical frame, that frame is given input focus if
2229 possible (@pxref{Input Focus}). The return value is the buffer that
2232 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2233 returned by @code{other-buffer} (@pxref{Buffer List}). If
2234 @var{buffer-or-name} is a string that is not the name of any existing
2235 buffer, this function creates a new buffer with that name; the new
2236 buffer's major mode is determined by the variable @code{major-mode}
2237 (@pxref{Major Modes}).
2239 If @var{action} is non-@code{nil}, it should be a display action to
2240 pass to @code{display-buffer} (@pxref{Choosing Window}).
2241 Alternatively, a non-@code{nil}, non-list value means to pop to a
2242 window other than the selected one---even if the buffer is already
2243 displayed in the selected window.
2245 Like @code{switch-to-buffer}, this function updates the buffer list
2246 unless @var{norecord} is non-@code{nil}.
2250 @node Choosing Window
2251 @section Choosing a Window for Display
2253 The command @code{display-buffer} flexibly chooses a window for
2254 display, and displays a specified buffer in that window. It can be
2255 called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
2256 used as a subroutine by many functions and commands, including
2257 @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
2260 @cindex display action
2261 @cindex action function, for @code{display-buffer}
2262 @cindex action alist, for @code{display-buffer}
2263 This command performs several complex steps to find a window to
2264 display in. These steps are described by means of @dfn{display
2265 actions}, which have the form @code{(@var{function} . @var{alist})}.
2266 Here, @var{function} is either a function or a list of functions,
2267 which we refer to as @dfn{action functions}; @var{alist} is an
2268 association list, which we refer to as @dfn{action alists}.
2270 An action function accepts two arguments: the buffer to display and
2271 an action alist. It attempts to display the buffer in some window,
2272 picking or creating a window according to its own criteria. If
2273 successful, it returns the window; otherwise, it returns @code{nil}.
2274 @xref{Display Action Functions}, for a list of predefined action
2277 @code{display-buffer} works by combining display actions from
2278 several sources, and calling the action functions in turn, until one
2279 of them manages to display the buffer and returns a non-@code{nil}
2282 @deffn Command display-buffer buffer-or-name &optional action frame
2283 This command makes @var{buffer-or-name} appear in some window, without
2284 selecting the window or making the buffer current. The argument
2285 @var{buffer-or-name} must be a buffer or the name of an existing
2286 buffer. The return value is the window chosen to display the buffer.
2288 The optional argument @var{action}, if non-@code{nil}, should normally
2289 be a display action (described above). @code{display-buffer} builds a
2290 list of action functions and an action alist, by consolidating display
2291 actions from the following sources (in order):
2295 The variable @code{display-buffer-overriding-action}.
2298 The user option @code{display-buffer-alist}.
2301 The @var{action} argument.
2304 The user option @code{display-buffer-base-action}.
2307 The constant @code{display-buffer-fallback-action}.
2311 Each action function is called in turn, passing the buffer as the
2312 first argument and the combined action alist as the second argument,
2313 until one of the functions returns non-@code{nil}. The caller can
2314 pass @code{(allow-no-window . t)} as an element of the action alist to
2315 indicate its readiness to handle the case of not displaying the
2318 The argument @var{action} can also have a non-@code{nil}, non-list
2319 value. This has the special meaning that the buffer should be
2320 displayed in a window other than the selected one, even if the
2321 selected window is already displaying it. If called interactively
2322 with a prefix argument, @var{action} is @code{t}.
2324 The optional argument @var{frame}, if non-@code{nil}, specifies which
2325 frames to check when deciding whether the buffer is already displayed.
2326 It is equivalent to adding an element @code{(reusable-frames
2327 . @var{frame})} to the action alist of @var{action}. @xref{Display
2331 @defvar display-buffer-overriding-action
2332 The value of this variable should be a display action, which is
2333 treated with the highest priority by @code{display-buffer}. The
2334 default value is empty, i.e., @code{(nil . nil)}.
2337 @defopt display-buffer-alist
2338 The value of this option is an alist mapping conditions to display
2339 actions. Each condition may be either a regular expression matching a
2340 buffer name or a function that takes two arguments: a buffer name and
2341 the @var{action} argument passed to @code{display-buffer}. If the name
2342 of the buffer passed to @code{display-buffer} either matches a regular
2343 expression in this alist or the function specified by a condition
2344 returns non-@code{nil}, then @code{display-buffer} uses the
2345 corresponding display action to display the buffer.
2348 @defopt display-buffer-base-action
2349 The value of this option should be a display action. This option can
2350 be used to define a standard display action for calls to
2351 @code{display-buffer}.
2354 @defvr Constant display-buffer-fallback-action
2355 This display action specifies the fallback behavior for
2356 @code{display-buffer} if no other display actions are given.
2360 @node Display Action Functions
2361 @section Action Functions for @code{display-buffer}
2363 The following basic action functions are defined in Emacs. Each of
2364 these functions takes two arguments: @var{buffer}, the buffer to
2365 display, and @var{alist}, an action alist. Each action function
2366 returns the window if it succeeds, and @code{nil} if it fails.
2368 @defun display-buffer-same-window buffer alist
2369 This function tries to display @var{buffer} in the selected window.
2370 It fails if the selected window is a minibuffer window or is dedicated
2371 to another buffer (@pxref{Dedicated Windows}). It also fails if
2372 @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
2375 @defun display-buffer-reuse-window buffer alist
2376 This function tries to display @var{buffer} by finding a window
2377 that is already displaying it.
2379 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2380 the selected window is not eligible for reuse. If @var{alist}
2381 contains a @code{reusable-frames} entry, its value determines which
2382 frames to search for a reusable window:
2386 @code{nil} means consider windows on the selected frame.
2387 (Actually, the last non-minibuffer frame.)
2389 @code{t} means consider windows on all frames.
2391 @code{visible} means consider windows on all visible frames.
2393 0 means consider windows on all visible or iconified frames.
2395 A frame means consider windows on that frame only.
2398 Note that these meanings differ slightly from those of the
2399 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
2402 If @var{alist} contains no @code{reusable-frames} entry, this function
2403 normally searches just the selected frame; however, if the variable
2404 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
2405 current terminal. @xref{Choosing Window Options}.
2407 If this function chooses a window on another frame, it makes that frame
2408 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
2409 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
2412 @defun display-buffer-reuse-mode-window buffer alist
2413 This function tries to display @var{buffer} by finding a window
2414 that is displaying a buffer in a given mode.
2416 If @var{alist} contains a @code{mode} entry, its value is a major mode
2417 (a symbol) or a list of major modes. If @var{alist} contains no
2418 @code{mode} entry, the current major mode of @var{buffer} is used. A
2419 window is a candidate if it displays a buffer that derives from one of
2422 The behaviour is also controlled by entries for
2423 @code{inhibit-same-window}, @code{reusable-frames} and
2424 @code{inhibit-switch-frame} as is done in the function
2425 @code{display-buffer-reuse-window}.
2429 @defun display-buffer-pop-up-frame buffer alist
2430 This function creates a new frame, and displays the buffer in that
2431 frame's window. It actually performs the frame creation by calling
2432 the function specified in @code{pop-up-frame-function}
2433 (@pxref{Choosing Window Options}). If @var{alist} contains a
2434 @code{pop-up-frame-parameters} entry, the associated value
2435 is added to the newly created frame's parameters.
2438 @defun display-buffer-use-some-frame buffer alist
2439 This function tries to display @var{buffer} by trying to find a
2440 frame that meets a predicate (by default any frame other than the
2443 If this function chooses a window on another frame, it makes that frame
2444 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
2445 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
2447 If @var{alist} has a non-@code{nil} @code{frame-predicate} entry, its
2448 value is a function taking one argument (a frame), returning
2449 non-@code{nil} if the frame is a candidate; this function replaces the
2452 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2453 the selected window is used; thus if the selected frame has a single
2454 window, it is not used.
2457 @defun display-buffer-pop-up-window buffer alist
2458 This function tries to display @var{buffer} by splitting the largest
2459 or least recently-used window (typically one on the selected frame).
2460 It actually performs the split by calling the function specified in
2461 @code{split-window-preferred-function} (@pxref{Choosing Window
2464 The size of the new window can be adjusted by supplying
2465 @code{window-height} and @code{window-width} entries in @var{alist}. To
2466 adjust the window's height, use an entry whose @sc{car} is
2467 @code{window-height} and whose @sc{cdr} is one of:
2471 @code{nil} means to leave the height of the new window alone.
2474 A number specifies the desired height of the new window. An integer
2475 specifies the number of lines of the window. A floating-point
2476 number gives the fraction of the window's height with respect to the
2477 height of the frame's root window.
2480 If the @sc{cdr} specifies a function, that function is called with one
2481 argument: the new window. The function is supposed to adjust the
2482 height of the window; its return value is ignored. Suitable functions
2483 are @code{shrink-window-if-larger-than-buffer} and
2484 @code{fit-window-to-buffer}, see @ref{Resizing Windows}.
2487 To adjust the window's width, use an entry whose @sc{car} is
2488 @code{window-width} and whose @sc{cdr} is one of:
2492 @code{nil} means to leave the width of the new window alone.
2495 A number specifies the desired width of the new window. An integer
2496 specifies the number of columns of the window. A floating-point
2497 number gives the fraction of the window's width with respect to the
2498 width of the frame's root window.
2501 If the @sc{cdr} specifies a function, that function is called with one
2502 argument: the new window. The function is supposed to adjust the width
2503 of the window; its return value is ignored.
2506 If @var{alist} contains a @code{preserve-size} entry, Emacs will try to
2507 preserve the size of the new window during future resize operations
2508 (@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a
2509 cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width
2510 of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve
2511 the height of the window.
2513 This function can fail if no window splitting can be performed for some
2514 reason (e.g., if the selected frame has an @code{unsplittable} frame
2515 parameter; @pxref{Buffer Parameters}).
2518 @defun display-buffer-below-selected buffer alist
2519 This function tries to display @var{buffer} in a window below the
2520 selected window. This means to either split the selected window or use
2521 the window below the selected one. If it does create a new window, it
2522 will also adjust its size provided @var{alist} contains a suitable
2523 @code{window-height} or @code{window-width} entry, see above.
2526 @defun display-buffer-in-previous-window buffer alist
2527 This function tries to display @var{buffer} in a window previously
2528 showing it. If @var{alist} has a non-@code{nil}
2529 @code{inhibit-same-window} entry, the selected window is not eligible
2530 for reuse. If @var{alist} contains a @code{reusable-frames} entry, its
2531 value determines which frames to search for a suitable window as with
2532 @code{display-buffer-reuse-window}.
2534 If @var{alist} has a @code{previous-window} entry, the window
2535 specified by that entry will override any other window found by the
2536 methods above, even if that window never showed @var{buffer} before.
2539 @defun display-buffer-at-bottom buffer alist
2540 This function tries to display @var{buffer} in a window at the bottom
2541 of the selected frame.
2543 This either splits the window at the bottom of the frame or the
2544 frame's root window, or reuses an existing window at the bottom of the
2548 @defun display-buffer-use-some-window buffer alist
2549 This function tries to display @var{buffer} by choosing an existing
2550 window and displaying the buffer in that window. It can fail if all
2551 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
2554 @defun display-buffer-no-window buffer alist
2555 If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then
2556 this function does not display @code{buffer}. This allows you to
2557 override the default action and avoid displaying the buffer. It is
2558 assumed that when the caller specifies a non-@code{nil}
2559 @code{allow-no-window} value it can handle a @code{nil} value returned
2560 from @code{display-buffer} in this case.
2563 To illustrate the use of action functions, consider the following
2569 (get-buffer-create "*foo*")
2570 '((display-buffer-reuse-window
2571 display-buffer-pop-up-window
2572 display-buffer-pop-up-frame)
2573 (reusable-frames . 0)
2574 (window-height . 10) (window-width . 40)))
2579 Evaluating the form above will cause @code{display-buffer} to proceed as
2580 follows: If a buffer called *foo* already appears on a visible or
2581 iconified frame, it will reuse its window. Otherwise, it will try to
2582 pop up a new window or, if that is impossible, a new frame and show the
2583 buffer there. If all these steps fail, it will proceed using whatever
2584 @code{display-buffer-base-action} and
2585 @code{display-buffer-fallback-action} prescribe.
2587 Furthermore, @code{display-buffer} will try to adjust a reused window
2588 (provided *foo* was put by @code{display-buffer} there before) or a
2589 popped-up window as follows: If the window is part of a vertical
2590 combination, it will set its height to ten lines. Note that if, instead
2591 of the number 10, we specified the function
2592 @code{fit-window-to-buffer}, @code{display-buffer} would come up with a
2593 one-line window to fit the empty buffer. If the window is part of a
2594 horizontal combination, it sets its width to 40 columns. Whether a new
2595 window is vertically or horizontally combined depends on the shape of
2596 the window split and the values of
2597 @code{split-window-preferred-function}, @code{split-height-threshold}
2598 and @code{split-width-threshold} (@pxref{Choosing Window Options}).
2600 Now suppose we combine this call with a preexisting setup for
2601 @code{display-buffer-alist} as follows.
2605 (let ((display-buffer-alist
2608 (display-buffer-reuse-window display-buffer-below-selected)
2610 (window-height . 5))
2611 display-buffer-alist)))
2613 (get-buffer-create "*foo*")
2614 '((display-buffer-reuse-window
2615 display-buffer-pop-up-window
2616 display-buffer-pop-up-frame)
2617 (reusable-frames . 0)
2618 (window-height . 10) (window-width . 40))))
2623 This form will have @code{display-buffer} first try reusing a window
2624 that shows *foo* on the selected frame. If there's no such window, it
2625 will try to split the selected window or, if that is impossible, use the
2626 window below the selected window.
2628 If there's no window below the selected one, or the window below the
2629 selected one is dedicated to its buffer, @code{display-buffer} will
2630 proceed as described in the previous example. Note, however, that when
2631 it tries to adjust the height of any reused or popped-up window, it will
2632 in any case try to set its number of lines to 5 since that value
2633 overrides the corresponding specification in the @var{action} argument
2634 of @code{display-buffer}.
2637 @node Choosing Window Options
2638 @section Additional Options for Displaying Buffers
2640 The behavior of the standard display actions of @code{display-buffer}
2641 (@pxref{Choosing Window}) can be modified by a variety of user
2644 @defopt pop-up-windows
2645 If the value of this variable is non-@code{nil}, @code{display-buffer}
2646 is allowed to split an existing window to make a new window for
2647 displaying in. This is the default.
2649 This variable is provided mainly for backward compatibility. It is
2650 obeyed by @code{display-buffer} via a special mechanism in
2651 @code{display-buffer-fallback-action}, which only calls the action
2652 function @code{display-buffer-pop-up-window} (@pxref{Display Action
2653 Functions}) when the value is @code{nil}. It is not consulted by
2654 @code{display-buffer-pop-up-window} itself, which the user may specify
2655 directly in @code{display-buffer-alist} etc.
2658 @defopt split-window-preferred-function
2659 This variable specifies a function for splitting a window, in order to
2660 make a new window for displaying a buffer. It is used by the
2661 @code{display-buffer-pop-up-window} action function to actually split
2662 the window (@pxref{Display Action Functions}).
2664 The default value is @code{split-window-sensibly}, which is documented
2665 below. The value must be a function that takes one argument, a window,
2666 and return either a new window (which will be used to display the
2667 desired buffer) or @code{nil} (which means the splitting failed).
2670 @defun split-window-sensibly &optional window
2671 This function tries to split @var{window}, and return the newly created
2672 window. If @var{window} cannot be split, it returns @code{nil}. If
2673 @var{window} is omitted or @code{nil}, it defaults to the selected
2676 This function obeys the usual rules that determine when a window may
2677 be split (@pxref{Splitting Windows}). It first tries to split by
2678 placing the new window below, subject to the restriction imposed by
2679 @code{split-height-threshold} (see below), in addition to any other
2680 restrictions. If that fails, it tries to split by placing the new
2681 window to the right, subject to @code{split-width-threshold} (see
2682 below). If that fails, and the window is the only window on its
2683 frame, this function again tries to split and place the new window
2684 below, disregarding @code{split-height-threshold}. If this fails as
2685 well, this function gives up and returns @code{nil}.
2688 @defopt split-height-threshold
2689 This variable, used by @code{split-window-sensibly}, specifies whether
2690 to split the window placing the new window below. If it is an
2691 integer, that means to split only if the original window has at least
2692 that many lines. If it is @code{nil}, that means not to split this
2696 @defopt split-width-threshold
2697 This variable, used by @code{split-window-sensibly}, specifies whether
2698 to split the window placing the new window to the right. If the value
2699 is an integer, that means to split only if the original window has at
2700 least that many columns. If the value is @code{nil}, that means not
2704 @defopt even-window-sizes
2705 This variable, if non-@code{nil}, causes @code{display-buffer} to even
2706 window sizes whenever it reuses an existing window and that window is
2707 adjacent to the selected one.
2709 If its value is @code{width-only}, sizes are evened only if the reused
2710 window is on the left or right of the selected one and the selected
2711 window is wider than the reused one. If its value is @code{height-only}
2712 sizes are evened only if the reused window is above or beneath the
2713 selected window and the selected window is higher than the reused one.
2714 Any other non-@code{nil} value means to even sizes in any of these cases
2715 provided the selected window is larger than the reused one in the sense
2716 of their combination.
2719 @defopt pop-up-frames
2720 If the value of this variable is non-@code{nil}, that means
2721 @code{display-buffer} may display buffers by making new frames. The
2722 default is @code{nil}.
2724 A non-@code{nil} value also means that when @code{display-buffer} is
2725 looking for a window already displaying @var{buffer-or-name}, it can
2726 search any visible or iconified frame, not just the selected frame.
2728 This variable is provided mainly for backward compatibility. It is
2729 obeyed by @code{display-buffer} via a special mechanism in
2730 @code{display-buffer-fallback-action}, which calls the action function
2731 @code{display-buffer-pop-up-frame} (@pxref{Display Action Functions})
2732 if the value is non-@code{nil}. (This is done before attempting to
2733 split a window.) This variable is not consulted by
2734 @code{display-buffer-pop-up-frame} itself, which the user may specify
2735 directly in @code{display-buffer-alist} etc.
2738 @defopt pop-up-frame-function
2739 This variable specifies a function for creating a new frame, in order
2740 to make a new window for displaying a buffer. It is used by the
2741 @code{display-buffer-pop-up-frame} action function (@pxref{Display
2744 The value should be a function that takes no arguments and returns a
2745 frame, or @code{nil} if no frame could be created. The default value
2746 is a function that creates a frame using the parameters specified by
2747 @code{pop-up-frame-alist} (see below).
2750 @defopt pop-up-frame-alist
2751 This variable holds an alist of frame parameters (@pxref{Frame
2752 Parameters}), which is used by the default function in
2753 @code{pop-up-frame-function} to make a new frame. The default is
2757 @defopt same-window-buffer-names
2758 A list of buffer names for buffers that should be displayed in the
2759 selected window. If a buffer's name is in this list,
2760 @code{display-buffer} handles the buffer by showing it in the selected
2764 @defopt same-window-regexps
2765 A list of regular expressions that specify buffers that should be
2766 displayed in the selected window. If the buffer's name matches any of
2767 the regular expressions in this list, @code{display-buffer} handles the
2768 buffer by showing it in the selected window.
2771 @defun same-window-p buffer-name
2772 This function returns @code{t} if displaying a buffer
2773 named @var{buffer-name} with @code{display-buffer} would
2774 put it in the selected window.
2777 @node Window History
2778 @section Window History
2779 @cindex window history
2781 Each window remembers in a list the buffers it has previously displayed,
2782 and the order in which these buffers were removed from it. This history
2783 is used, for example, by @code{replace-buffer-in-windows}
2784 (@pxref{Buffers and Windows}). The list is automatically maintained by
2785 Emacs, but you can use the following functions to explicitly inspect or
2788 @defun window-prev-buffers &optional window
2789 This function returns a list specifying the previous contents of
2790 @var{window}. The optional argument @var{window} should be a live
2791 window and defaults to the selected one.
2793 Each list element has the form @code{(@var{buffer} @var{window-start}
2794 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
2795 the window, @var{window-start} is the window start position
2796 (@pxref{Window Start and End}) when that buffer was last shown, and
2797 @var{window-pos} is the point position (@pxref{Window Point}) when
2798 that buffer was last shown in @var{window}.
2800 The list is ordered so that earlier elements correspond to more
2801 recently-shown buffers, and the first element usually corresponds to the
2802 buffer most recently removed from the window.
2805 @defun set-window-prev-buffers window prev-buffers
2806 This function sets @var{window}'s previous buffers to the value of
2807 @var{prev-buffers}. The argument @var{window} must be a live window
2808 and defaults to the selected one. The argument @var{prev-buffers}
2809 should be a list of the same form as that returned by
2810 @code{window-prev-buffers}.
2813 In addition, each buffer maintains a list of @dfn{next buffers}, which
2814 is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
2815 below). This list is mainly used by @code{switch-to-prev-buffer} and
2816 @code{switch-to-next-buffer} for choosing buffers to switch to.
2818 @defun window-next-buffers &optional window
2819 This function returns the list of buffers recently re-shown in
2820 @var{window} via @code{switch-to-prev-buffer}. The @var{window}
2821 argument must denote a live window or @code{nil} (meaning the selected
2825 @defun set-window-next-buffers window next-buffers
2826 This function sets the next buffer list of @var{window} to
2827 @var{next-buffers}. The @var{window} argument should be a live window
2828 or @code{nil} (meaning the selected window). The argument
2829 @var{next-buffers} should be a list of buffers.
2832 The following commands can be used to cycle through the global buffer
2833 list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
2834 they cycle according to the specified window's history list, rather
2835 than the global buffer list. In addition, they restore
2836 window-specific window start and point positions, and may show a
2837 buffer even if it is already shown in another window. The
2838 @code{switch-to-prev-buffer} command, in particular, is used by
2839 @code{replace-buffer-in-windows}, @code{bury-buffer} and
2840 @code{quit-window} to find a replacement buffer for a window.
2842 @deffn Command switch-to-prev-buffer &optional window bury-or-kill
2843 This command displays the previous buffer in @var{window}. The
2844 argument @var{window} should be a live window or @code{nil} (meaning
2845 the selected window). If the optional argument @var{bury-or-kill} is
2846 non-@code{nil}, this means that the buffer currently shown in
2847 @var{window} is about to be buried or killed and consequently should
2848 not be switched to in future invocations of this command.
2850 The previous buffer is usually the buffer shown before the buffer
2851 currently shown in @var{window}. However, a buffer that has been buried
2852 or killed, or has been already shown by a recent invocation of
2853 @code{switch-to-prev-buffer}, does not qualify as previous buffer.
2855 If repeated invocations of this command have already shown all buffers
2856 previously shown in @var{window}, further invocations will show buffers
2857 from the buffer list of the frame @var{window} appears on (@pxref{Buffer
2858 List}), trying to skip buffers that are already shown in another window
2862 @deffn Command switch-to-next-buffer &optional window
2863 This command switches to the next buffer in @var{window}, thus undoing
2864 the effect of the last @code{switch-to-prev-buffer} command in
2865 @var{window}. The argument @var{window} must be a live window and
2866 defaults to the selected one.
2868 If there is no recent invocation of @code{switch-to-prev-buffer} that
2869 can be undone, this function tries to show a buffer from the buffer list
2870 of the frame @var{window} appears on (@pxref{Buffer List}).
2873 By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
2874 can switch to a buffer that is already shown in another window on the
2875 same frame. The following option can be used to override this behavior.
2877 @defopt switch-to-visible-buffer
2878 If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
2879 @code{switch-to-next-buffer} may switch to a buffer that is already
2880 visible on the same frame, provided the buffer was shown in the
2881 relevant window before. If it is @code{nil},
2882 @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always
2883 try to avoid switching to a buffer that is already visible in another
2884 window on the same frame. The default is @code{t}.
2888 @node Dedicated Windows
2889 @section Dedicated Windows
2890 @cindex dedicated window
2892 Functions for displaying a buffer can be told to not use specific
2893 windows by marking these windows as @dfn{dedicated} to their buffers.
2894 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
2895 window for displaying another buffer in it. @code{get-lru-window} and
2896 @code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not
2897 consider dedicated windows as candidates when their @var{dedicated}
2898 argument is non-@code{nil}. The behavior of @code{set-window-buffer}
2899 (@pxref{Buffers and Windows}) with respect to dedicated windows is
2900 slightly different, see below.
2902 Functions supposed to remove a buffer from a window or a window from
2903 a frame can behave specially when a window they operate on is dedicated.
2904 We will distinguish three basic cases, namely where (1) the window is
2905 not the only window on its frame, (2) the window is the only window on
2906 its frame but there are other frames on the same terminal left, and (3)
2907 the window is the only window on the only frame on the same terminal.
2909 In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
2910 handles case (2) by deleting the associated frame and case (3) by
2911 showing another buffer in that frame's only window. The function
2912 @code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
2913 called when a buffer gets killed, deletes the window in case (1) and
2914 behaves like @code{delete-windows-on} otherwise.
2915 @c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
2917 When @code{bury-buffer} (@pxref{Buffer List}) operates on the
2918 selected window (which shows the buffer that shall be buried), it
2919 handles case (2) by calling @code{frame-auto-hide-function}
2920 (@pxref{Quitting Windows}) to deal with the selected frame. The other
2921 two cases are handled as with @code{replace-buffer-in-windows}.
2923 @defun window-dedicated-p &optional window
2924 This function returns non-@code{nil} if @var{window} is dedicated to its
2925 buffer and @code{nil} otherwise. More precisely, the return value is
2926 the value assigned by the last call of @code{set-window-dedicated-p} for
2927 @var{window}, or @code{nil} if that function was never called with
2928 @var{window} as its argument. The default for @var{window} is the
2932 @defun set-window-dedicated-p window flag
2933 This function marks @var{window} as dedicated to its buffer if
2934 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
2936 As a special case, if @var{flag} is @code{t}, @var{window} becomes
2937 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
2938 signals an error when the window it acts upon is strongly dedicated to
2939 its buffer and does not already display the buffer it is asked to
2940 display. Other functions do not treat @code{t} differently from any
2941 non-@code{nil} value.
2945 @node Quitting Windows
2946 @section Quitting Windows
2948 When you want to get rid of a window used for displaying a buffer, you
2949 can call @code{delete-window} or @code{delete-windows-on}
2950 (@pxref{Deleting Windows}) to remove that window from its frame. If the
2951 buffer is shown on a separate frame, you might want to call
2952 @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
2953 hand, a window has been reused for displaying the buffer, you might
2954 prefer showing the buffer previously shown in that window, by calling the
2955 function @code{switch-to-prev-buffer} (@pxref{Window History}).
2956 Finally, you might want to either bury (@pxref{Buffer List}) or kill
2957 (@pxref{Killing Buffers}) the window's buffer.
2959 The following command uses information on how the window for
2960 displaying the buffer was obtained in the first place, thus attempting
2961 to automate the above decisions for you.
2963 @deffn Command quit-window &optional kill window
2964 This command quits @var{window} and buries its buffer. The argument
2965 @var{window} must be a live window and defaults to the selected one.
2966 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
2967 instead of burying it. It calls the function @code{quit-restore-window}
2968 described next to deal with the window and its buffer.
2971 @defun quit-restore-window &optional window bury-or-kill
2972 This function tries to restore the state of @var{window} that existed
2973 before its buffer was displayed in it. The optional argument
2974 @var{window} must be a live window and defaults to the selected one.
2976 If @var{window} was created specially for displaying its buffer, this
2977 function deletes @var{window} provided its frame contains at least one
2978 other live window. If @var{window} is the only window on its frame and
2979 there are other frames on the frame's terminal, the value of the
2980 optional argument @var{bury-or-kill} determines how to proceed with the
2981 window. If @var{bury-or-kill} equals @code{kill}, the frame is deleted
2982 unconditionally. Otherwise, the fate of the frame is determined by
2983 calling @code{frame-auto-hide-function} (see below) with that frame as
2986 Otherwise, this function tries to redisplay the buffer previously shown
2987 in @var{window}. It also tries to restore the window start
2988 (@pxref{Window Start and End}) and point (@pxref{Window Point})
2989 positions of the previously shown buffer. If, in addition,
2990 @var{window}'s buffer was temporarily resized, this function will also
2991 try to restore the original height of @var{window}.
2993 The cases described so far require that the buffer shown in @var{window}
2994 is still the buffer displayed by the last buffer display function for
2995 this window. If another buffer has been shown in the meantime, or the
2996 buffer previously shown no longer exists, this function calls
2997 @code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
3000 The optional argument @var{bury-or-kill} specifies how to deal with
3001 @var{window}'s buffer. The following values are handled:
3005 This means to not deal with the buffer in any particular way. As a
3006 consequence, if @var{window} is not deleted, invoking
3007 @code{switch-to-prev-buffer} will usually show the buffer again.
3010 This means that if @var{window} is not deleted, its buffer is moved to
3011 the end of @var{window}'s list of previous buffers, so it's less likely
3012 that a future invocation of @code{switch-to-prev-buffer} will switch to
3013 it. Also, it moves the buffer to the end of the frame's buffer list.
3016 This means that if @var{window} is not deleted, its buffer is removed
3017 from @var{window}'s list of previous buffers. Also, it moves the buffer
3018 to the end of the frame's buffer list. This value provides the most
3019 reliable remedy to not have @code{switch-to-prev-buffer} switch to this
3020 buffer again without killing the buffer.
3023 This means to kill @var{window}'s buffer.
3026 @code{quit-restore-window} bases its decisions on information stored in
3027 @var{window}'s @code{quit-restore} window parameter (@pxref{Window
3028 Parameters}), and resets that parameter to @code{nil} after it's done.
3031 The following option specifies how to deal with a frame containing just
3032 one window that should be either quit, or whose buffer should be buried.
3034 @defopt frame-auto-hide-function
3035 The function specified by this option is called to automatically hide
3036 frames. This function is called with one argument---a frame.
3038 The function specified here is called by @code{bury-buffer}
3039 (@pxref{Buffer List}) when the selected window is dedicated and shows
3040 the buffer to bury. It is also called by @code{quit-restore-window}
3041 (see above) when the frame of the window to quit has been specially
3042 created for displaying that window's buffer and the buffer is not
3045 The default is to call @code{iconify-frame} (@pxref{Visibility of
3046 Frames}). Alternatively, you may specify either @code{delete-frame}
3047 (@pxref{Deleting Frames}) to remove the frame from its display,
3048 @code{ignore} to leave the frame unchanged, or any other function that
3049 can take a frame as its sole argument.
3051 Note that the function specified by this option is called only if the
3052 specified frame contains just one live window and there is at least one
3053 other frame on the same terminal.
3058 @section Windows and Point
3059 @cindex window position
3060 @cindex window point
3061 @cindex position in window
3062 @cindex point in window
3064 Each window has its own value of point (@pxref{Point}), independent of
3065 the value of point in other windows displaying the same buffer. This
3066 makes it useful to have multiple windows showing one buffer.
3070 The window point is established when a window is first created; it is
3071 initialized from the buffer's point, or from the window point of another
3072 window opened on the buffer if such a window exists.
3075 Selecting a window sets the value of point in its buffer from the
3076 window's value of point. Conversely, deselecting a window sets the
3077 window's value of point from that of the buffer. Thus, when you switch
3078 between windows that display a given buffer, the point value for the
3079 selected window is in effect in the buffer, while the point values for
3080 the other windows are stored in those windows.
3083 As long as the selected window displays the current buffer, the window's
3084 point and the buffer's point always move together; they remain equal.
3088 As far as the user is concerned, point is where the cursor is, and
3089 when the user switches to another buffer, the cursor jumps to the
3090 position of point in that buffer.
3092 @defun window-point &optional window
3093 This function returns the current position of point in @var{window}.
3094 For a nonselected window, this is the value point would have (in that
3095 window's buffer) if that window were selected. The default for
3096 @var{window} is the selected window.
3098 When @var{window} is the selected window, the value returned is the
3099 value of point in that window's buffer. Strictly speaking, it would be
3100 more correct to return the top-level value of point, outside of any
3101 @code{save-excursion} forms. But that value is hard to find.
3104 @defun set-window-point window position
3105 This function positions point in @var{window} at position
3106 @var{position} in @var{window}'s buffer. It returns @var{position}.
3108 If @var{window} is selected, this simply does @code{goto-char} in
3109 @var{window}'s buffer.
3112 @defvar window-point-insertion-type
3113 This variable specifies the marker insertion type (@pxref{Marker
3114 Insertion Types}) of @code{window-point}. The default is @code{nil},
3115 so @code{window-point} will stay behind text inserted there.
3118 @node Window Start and End
3119 @section The Window Start and End Positions
3120 @cindex window start position
3121 @cindex display-start position
3123 Each window maintains a marker used to keep track of a buffer position
3124 that specifies where in the buffer display should start. This position
3125 is called the @dfn{display-start} position of the window (or just the
3126 @dfn{start}). The character after this position is the one that appears
3127 at the upper left corner of the window. It is usually, but not
3128 inevitably, at the beginning of a text line.
3130 After switching windows or buffers, and in some other cases, if the
3131 window start is in the middle of a line, Emacs adjusts the window
3132 start to the start of a line. This prevents certain operations from
3133 leaving the window start at a meaningless point within a line. This
3134 feature may interfere with testing some Lisp code by executing it
3135 using the commands of Lisp mode, because they trigger this
3136 readjustment. To test such code, put it into a command and bind the
3139 @defun window-start &optional window
3140 @cindex window top line
3141 This function returns the display-start position of window
3142 @var{window}. If @var{window} is @code{nil}, the selected window is
3145 When you create a window, or display a different buffer in it, the
3146 display-start position is set to a display-start position recently used
3147 for the same buffer, or to @code{point-min} if the buffer doesn't have
3150 Redisplay updates the window-start position (if you have not specified
3151 it explicitly since the previous redisplay)---to make sure point appears
3152 on the screen. Nothing except redisplay automatically changes the
3153 window-start position; if you move point, do not expect the window-start
3154 position to change in response until after the next redisplay.
3157 @defun window-group-start &optional window
3158 @vindex window-group-start-function
3159 This function is like @code{window-start}, except that when
3160 @var{window} is a part of a group of windows (@pxref{Window Group}),
3161 @code{window-group-start} returns the start position of the entire
3162 group. This condition holds when the buffer local variable
3163 @code{window-group-start-function} is set to a function. In this
3164 case, @code{window-group-start} calls the function with the single
3165 argument @var{window}, then returns its result.
3168 @cindex window end position
3169 @defun window-end &optional window update
3170 This function returns the position where display of its buffer ends in
3171 @var{window}. The default for @var{window} is the selected window.
3173 Simply changing the buffer text or moving point does not update the
3174 value that @code{window-end} returns. The value is updated only when
3175 Emacs redisplays and redisplay completes without being preempted.
3177 If the last redisplay of @var{window} was preempted, and did not finish,
3178 Emacs does not know the position of the end of display in that window.
3179 In that case, this function returns @code{nil}.
3181 If @var{update} is non-@code{nil}, @code{window-end} always returns an
3182 up-to-date value for where display ends, based on the current
3183 @code{window-start} value. If a previously saved value of that position
3184 is still valid, @code{window-end} returns that value; otherwise it
3185 computes the correct value by scanning the buffer text.
3187 Even if @var{update} is non-@code{nil}, @code{window-end} does not
3188 attempt to scroll the display if point has moved off the screen, the
3189 way real redisplay would do. It does not alter the
3190 @code{window-start} value. In effect, it reports where the displayed
3191 text will end if scrolling is not required.
3194 @vindex window-group-end-function
3195 @defun window-group-end &optional window update
3196 This function is like @code{window-end}, except that when @var{window}
3197 is a part of a group of windows (@pxref{Window Group}),
3198 @code{window-group-end} returns the end position of the entire group.
3199 This condition holds when the buffer local variable
3200 @code{window-group-end-function} is set to a function. In this case,
3201 @code{window-group-end} calls the function with the two arguments
3202 @var{window} and @var{update}, then returns its result. The argument
3203 @var{update} has the same meaning as in @code{window-end}.
3206 @defun set-window-start window position &optional noforce
3207 This function sets the display-start position of @var{window} to
3208 @var{position} in @var{window}'s buffer. It returns @var{position}.
3210 The display routines insist that the position of point be visible when a
3211 buffer is displayed. Normally, they change the display-start position
3212 (that is, scroll the window) whenever necessary to make point visible.
3213 However, if you specify the start position with this function using
3214 @code{nil} for @var{noforce}, it means you want display to start at
3215 @var{position} even if that would put the location of point off the
3216 screen. If this does place point off screen, the display routines move
3217 point to the left margin on the middle line in the window.
3219 For example, if point @w{is 1} and you set the start of the window
3220 @w{to 37}, the start of the next line, point will be above the top
3221 of the window. The display routines will automatically move point if
3222 it is still 1 when redisplay occurs. Here is an example:
3226 ;; @r{Here is what @samp{foo} looks like before executing}
3227 ;; @r{the @code{set-window-start} expression.}
3231 ---------- Buffer: foo ----------
3232 @point{}This is the contents of buffer foo.
3238 ---------- Buffer: foo ----------
3252 ;; @r{Here is what @samp{foo} looks like after executing}
3253 ;; @r{the @code{set-window-start} expression.}
3254 ---------- Buffer: foo ----------
3260 ---------- Buffer: foo ----------
3264 If @var{noforce} is non-@code{nil}, and @var{position} would place point
3265 off screen at the next redisplay, then redisplay computes a new window-start
3266 position that works well with point, and thus @var{position} is not used.
3269 @vindex set-window-group-start-function
3270 @defun set-window-group-start window position &optional noforce
3271 This function is like @code{set-window-start}, except that when
3272 @var{window} is a part of a group of windows (@pxref{Window Group}),
3273 @code{set-window-group-start} sets the start position of the entire
3274 group. This condition holds when the buffer local variable
3275 @code{set-window-group-start-function} is set to a function. In this
3276 case, @code{set-window-group-start} calls the function with the three
3277 arguments @var{window}, @var{position}, and @var{noforce}, then
3278 returns its result. The arguments @var{position} and @var{noforce} in
3279 this function have the same meaning as in @code{set-window-start}.
3282 @defun pos-visible-in-window-p &optional position window partially
3283 This function returns non-@code{nil} if @var{position} is within the
3284 range of text currently visible on the screen in @var{window}. It
3285 returns @code{nil} if @var{position} is scrolled vertically out of
3286 view. Locations that are partially obscured are not considered
3287 visible unless @var{partially} is non-@code{nil}. The argument
3288 @var{position} defaults to the current position of point in
3289 @var{window}; @var{window} defaults to the selected window. If
3290 @var{position} is @code{t}, that means to check either the first
3291 visible position of the last screen line in @var{window}, or the
3292 end-of-buffer position, whichever comes first.
3294 This function considers only vertical scrolling. If @var{position} is
3295 out of view only because @var{window} has been scrolled horizontally,
3296 @code{pos-visible-in-window-p} returns non-@code{nil} anyway.
3297 @xref{Horizontal Scrolling}.
3299 If @var{position} is visible, @code{pos-visible-in-window-p} returns
3300 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
3301 non-@code{nil}, and the character following @var{position} is fully
3302 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
3303 @var{x} and @var{y} are the pixel coordinates relative to the top left
3304 corner of the window; otherwise it returns an extended list of the form
3305 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
3306 where @var{rtop} and @var{rbot} specify the number of off-window pixels
3307 at the top and bottom of the row at @var{position}, @var{rowh} specifies
3308 the visible height of that row, and @var{vpos} specifies the vertical
3309 position (zero-based row number) of that row.
3315 ;; @r{If point is off the screen now, recenter it now.}
3316 (or (pos-visible-in-window-p
3317 (point) (selected-window))
3323 @vindex pos-visible-in-window-group-p-function
3324 @defun pos-visible-in-window-group-p &optional position window partially
3325 This function is like @code{pos-visible-in-window-p}, except that when
3326 @var{window} is a part of a group of windows (@pxref{Window Group}),
3327 @code{pos-visible-in-window-group-p} tests the visibility of @var{pos}
3328 in the entire group, not just in the single @var{window}. This
3329 condition holds when the buffer local variable
3330 @code{pos-visible-in-window-group-p-function} is set to a function.
3331 In this case @code{pos-visible-in-window-group-p} calls the function
3332 with the three arguments @var{position}, @var{window}, and
3333 @var{partially}, then returns its result. The arguments
3334 @var{position} and @var{partially} have the same meaning as in
3335 @code{pos-visible-in-window-p}.
3338 @defun window-line-height &optional line window
3339 This function returns the height of text line @var{line} in
3340 @var{window}. If @var{line} is one of @code{header-line} or
3341 @code{mode-line}, @code{window-line-height} returns information about
3342 the corresponding line of the window. Otherwise, @var{line} is a text
3343 line number starting from 0. A negative number counts from the end of
3344 the window. The default for @var{line} is the current line in
3345 @var{window}; the default for @var{window} is the selected window.
3347 If the display is not up to date, @code{window-line-height} returns
3348 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
3349 to obtain related information.
3351 If there is no line corresponding to the specified @var{line},
3352 @code{window-line-height} returns @code{nil}. Otherwise, it returns
3353 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
3354 where @var{height} is the height in pixels of the visible part of the
3355 line, @var{vpos} and @var{ypos} are the vertical position in lines and
3356 pixels of the line relative to the top of the first text line, and
3357 @var{offbot} is the number of off-window pixels at the bottom of the
3358 text line. If there are off-window pixels at the top of the (first)
3359 text line, @var{ypos} is negative.
3362 @node Textual Scrolling
3363 @section Textual Scrolling
3364 @cindex textual scrolling
3365 @cindex scrolling textually
3367 @dfn{Textual scrolling} means moving the text up or down through a
3368 window. It works by changing the window's display-start location. It
3369 may also change the value of @code{window-point} to keep point on the
3370 screen (@pxref{Window Point}).
3372 The basic textual scrolling functions are @code{scroll-up} (which
3373 scrolls forward) and @code{scroll-down} (which scrolls backward). In
3374 these function names, ``up'' and ``down'' refer to the direction of
3375 motion of the buffer text relative to the window. Imagine that the
3376 text is written on a long roll of paper and that the scrolling
3377 commands move the paper up and down. Thus, if you are looking at the
3378 middle of a buffer and repeatedly call @code{scroll-down}, you will
3379 eventually see the beginning of the buffer.
3381 Unfortunately, this sometimes causes confusion, because some people
3382 tend to think in terms of the opposite convention: they
3383 imagine the window moving over text that remains in place, so that
3384 ``down'' commands take you to the end of the buffer. This convention
3385 is consistent with fact that such a command is bound to a key named
3386 @key{PageDown} on modern keyboards.
3388 We have not switched to this convention as that is likely to break
3389 existing Emacs Lisp code.
3392 Textual scrolling functions (aside from @code{scroll-other-window})
3393 have unpredictable results if the current buffer is not the one
3394 displayed in the selected window. @xref{Current Buffer}.
3396 If the window contains a row taller than the height of the window
3397 (for example in the presence of a large image), the scroll functions
3398 will adjust the window's vertical scroll position to scroll the
3399 partially visible row. Lisp callers can disable this feature by
3400 binding the variable @code{auto-window-vscroll} to @code{nil}
3401 (@pxref{Vertical Scrolling}).
3403 @deffn Command scroll-up &optional count
3404 This function scrolls forward by @var{count} lines in the selected
3407 If @var{count} is negative, it scrolls backward instead. If
3408 @var{count} is @code{nil} (or omitted), the distance scrolled is
3409 @code{next-screen-context-lines} lines less than the height of the
3412 If the selected window cannot be scrolled any further, this function
3413 signals an error. Otherwise, it returns @code{nil}.
3416 @deffn Command scroll-down &optional count
3417 This function scrolls backward by @var{count} lines in the selected
3420 If @var{count} is negative, it scrolls forward instead. In other
3421 respects, it behaves the same way as @code{scroll-up} does.
3424 @deffn Command scroll-up-command &optional count
3425 This behaves like @code{scroll-up}, except that if the selected window
3426 cannot be scrolled any further and the value of the variable
3427 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3428 end of the buffer instead. If point is already there, it signals an
3432 @deffn Command scroll-down-command &optional count
3433 This behaves like @code{scroll-down}, except that if the selected
3434 window cannot be scrolled any further and the value of the variable
3435 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3436 beginning of the buffer instead. If point is already there, it
3440 @deffn Command scroll-other-window &optional count
3441 This function scrolls the text in another window upward @var{count}
3442 lines. Negative values of @var{count}, or @code{nil}, are handled
3443 as in @code{scroll-up}.
3445 You can specify which buffer to scroll by setting the variable
3446 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
3447 already displayed, @code{scroll-other-window} displays it in some
3450 When the selected window is the minibuffer, the next window is normally
3451 the leftmost one immediately above it. You can specify a different
3452 window to scroll, when the minibuffer is selected, by setting the variable
3453 @code{minibuffer-scroll-window}. This variable has no effect when any
3454 other window is selected. When it is non-@code{nil} and the
3455 minibuffer is selected, it takes precedence over
3456 @code{other-window-scroll-buffer}. @xref{Definition of
3457 minibuffer-scroll-window}.
3459 When the minibuffer is active, it is the next window if the selected
3460 window is the one at the bottom right corner. In this case,
3461 @code{scroll-other-window} attempts to scroll the minibuffer. If the
3462 minibuffer contains just one line, it has nowhere to scroll to, so the
3463 line reappears after the echo area momentarily displays the message
3464 @samp{End of buffer}.
3467 @defvar other-window-scroll-buffer
3468 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
3469 which buffer's window to scroll.
3472 @defopt scroll-margin
3473 This option specifies the size of the scroll margin---a minimum number
3474 of lines between point and the top or bottom of a window. Whenever
3475 point gets within this many lines of the top or bottom of the window,
3476 redisplay scrolls the text automatically (if possible) to move point
3477 out of the margin, closer to the center of the window.
3480 @defopt scroll-conservatively
3481 This variable controls how scrolling is done automatically when point
3482 moves off the screen (or into the scroll margin). If the value is a
3483 positive integer @var{n}, then redisplay scrolls the text up to
3484 @var{n} lines in either direction, if that will bring point back into
3485 proper view. This behavior is called @dfn{conservative scrolling}.
3486 Otherwise, scrolling happens in the usual way, under the control of
3487 other variables such as @code{scroll-up-aggressively} and
3488 @code{scroll-down-aggressively}.
3490 The default value is zero, which means that conservative scrolling
3494 @defopt scroll-down-aggressively
3495 The value of this variable should be either @code{nil} or a fraction
3496 @var{f} between 0 and 1. If it is a fraction, that specifies where on
3497 the screen to put point when scrolling down. More precisely, when a
3498 window scrolls down because point is above the window start, the new
3499 start position is chosen to put point @var{f} part of the window
3500 height from the top. The larger @var{f}, the more aggressive the
3503 A value of @code{nil} is equivalent to .5, since its effect is to center
3504 point. This variable automatically becomes buffer-local when set in any
3508 @defopt scroll-up-aggressively
3509 Likewise, for scrolling up. The value, @var{f}, specifies how far
3510 point should be placed from the bottom of the window; thus, as with
3511 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
3515 This variable is an older variant of @code{scroll-conservatively}.
3516 The difference is that if its value is @var{n}, that permits scrolling
3517 only by precisely @var{n} lines, not a smaller number. This feature
3518 does not work with @code{scroll-margin}. The default value is zero.
3521 @cindex @code{scroll-command} property
3522 @defopt scroll-preserve-screen-position
3523 If this option is @code{t}, whenever a scrolling command moves point
3524 off-window, Emacs tries to adjust point to keep the cursor at its old
3525 vertical position in the window, rather than the window edge.
3527 If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
3528 to keep the cursor at the same vertical position, even if the
3529 scrolling command didn't move point off-window.
3531 This option affects all scroll commands that have a non-@code{nil}
3532 @code{scroll-command} symbol property.
3535 @defopt next-screen-context-lines
3536 The value of this variable is the number of lines of continuity to
3537 retain when scrolling by full screens. For example, @code{scroll-up}
3538 with an argument of @code{nil} scrolls so that this many lines at the
3539 bottom of the window appear instead at the top. The default value is
3543 @defopt scroll-error-top-bottom
3544 If this option is @code{nil} (the default), @code{scroll-up-command}
3545 and @code{scroll-down-command} simply signal an error when no more
3546 scrolling is possible.
3548 If the value is @code{t}, these commands instead move point to the
3549 beginning or end of the buffer (depending on scrolling direction);
3550 only if point is already on that position do they signal an error.
3553 @deffn Command recenter &optional count
3554 @cindex centering point
3555 This function scrolls the text in the selected window so that point is
3556 displayed at a specified vertical position within the window. It does
3557 not move point with respect to the text.
3559 If @var{count} is a non-negative number, that puts the line containing
3560 point @var{count} lines down from the top of the window. If
3561 @var{count} is a negative number, then it counts upward from the
3562 bottom of the window, so that @minus{}1 stands for the last usable
3565 If @var{count} is @code{nil} (or a non-@code{nil} list),
3566 @code{recenter} puts the line containing point in the middle of the
3567 window. If @var{count} is @code{nil}, this function may redraw the
3568 frame, according to the value of @code{recenter-redisplay}.
3570 When @code{recenter} is called interactively, @var{count} is the raw
3571 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
3572 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
3573 @var{count} to 4, which positions the current line four lines from the
3576 With an argument of zero, @code{recenter} positions the current line at
3577 the top of the window. The command @code{recenter-top-bottom} offers
3578 a more convenient way to achieve this.
3581 @vindex recenter-window-group-function
3582 @defun recenter-window-group &optional count
3583 This function is like @code{recenter}, except that when the selected
3584 window is part of a group of windows (@pxref{Window Group}),
3585 @code{recenter-window-group} scrolls the entire group. This condition
3586 holds when the buffer local variable
3587 @code{recenter-window-group-function} is set to a function. In this
3588 case, @code{recenter-window-group} calls the function with the
3589 argument @var{count}, then returns its result. The argument
3590 @var{count} has the same meaning as in @code{recenter}, but with
3591 respect to the entire window group.
3594 @defopt recenter-redisplay
3595 If this variable is non-@code{nil}, calling @code{recenter} with a
3596 @code{nil} argument redraws the frame. The default value is
3597 @code{tty}, which means only redraw the frame if it is a tty frame.
3600 @deffn Command recenter-top-bottom &optional count
3601 This command, which is the default binding for @kbd{C-l}, acts like
3602 @code{recenter}, except if called with no argument. In that case,
3603 successive calls place point according to the cycling order defined
3604 by the variable @code{recenter-positions}.
3607 @defopt recenter-positions
3608 This variable controls how @code{recenter-top-bottom} behaves when
3609 called with no argument. The default value is @code{(middle top
3610 bottom)}, which means that successive calls of
3611 @code{recenter-top-bottom} with no argument cycle between placing
3612 point at the middle, top, and bottom of the window.
3616 @node Vertical Scrolling
3617 @section Vertical Fractional Scrolling
3618 @cindex vertical fractional scrolling
3619 @cindex vertical scroll position
3621 @dfn{Vertical fractional scrolling} means shifting text in a window
3622 up or down by a specified multiple or fraction of a line. Each window
3623 has a @dfn{vertical scroll position}, which is a number, never less than
3624 zero. It specifies how far to raise the contents of the window.
3625 Raising the window contents generally makes all or part of some lines
3626 disappear off the top, and all or part of some other lines appear at the
3627 bottom. The usual value is zero.
3629 The vertical scroll position is measured in units of the normal line
3630 height, which is the height of the default font. Thus, if the value is
3631 .5, that means the window contents are scrolled up half the normal line
3632 height. If it is 3.3, that means the window contents are scrolled up
3633 somewhat over three times the normal line height.
3635 What fraction of a line the vertical scrolling covers, or how many
3636 lines, depends on what the lines contain. A value of .5 could scroll a
3637 line whose height is very short off the screen, while a value of 3.3
3638 could scroll just part of the way through a tall line or an image.
3640 @defun window-vscroll &optional window pixels-p
3641 This function returns the current vertical scroll position of
3642 @var{window}. The default for @var{window} is the selected window.
3643 If @var{pixels-p} is non-@code{nil}, the return value is measured in
3644 pixels, rather than in units of the normal line height.
3654 @defun set-window-vscroll window lines &optional pixels-p
3655 This function sets @var{window}'s vertical scroll position to
3656 @var{lines}. If @var{window} is @code{nil}, the selected window is
3657 used. The argument @var{lines} should be zero or positive; if not, it
3661 The actual vertical scroll position must always correspond
3662 to an integral number of pixels, so the value you specify
3663 is rounded accordingly.
3665 The return value is the result of this rounding.
3669 (set-window-vscroll (selected-window) 1.2)
3674 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
3675 pixels. In this case, the return value is @var{lines}.
3678 @defvar auto-window-vscroll
3679 If this variable is non-@code{nil}, the @code{line-move},
3680 @code{scroll-up}, and @code{scroll-down} functions will automatically
3681 modify the vertical scroll position to scroll through display rows
3682 that are taller than the height of the window, for example in the
3683 presence of large images.
3686 @node Horizontal Scrolling
3687 @section Horizontal Scrolling
3688 @cindex horizontal scrolling
3690 @dfn{Horizontal scrolling} means shifting the image in the window left
3691 or right by a specified multiple of the normal character width. Each
3692 window has a @dfn{horizontal scroll position}, which is a number, never
3693 less than zero. It specifies how far to shift the contents left.
3694 Shifting the window contents left generally makes all or part of some
3695 characters disappear off the left, and all or part of some other
3696 characters appear at the right. The usual value is zero.
3698 The horizontal scroll position is measured in units of the normal
3699 character width, which is the width of space in the default font. Thus,
3700 if the value is 5, that means the window contents are scrolled left by 5
3701 times the normal character width. How many characters actually
3702 disappear off to the left depends on their width, and could vary from
3705 Because we read from side to side in the inner loop, and from top
3706 to bottom in the outer loop, the effect of horizontal scrolling is
3707 not like that of textual or vertical scrolling. Textual scrolling
3708 involves selection of a portion of text to display, and vertical
3709 scrolling moves the window contents contiguously; but horizontal
3710 scrolling causes part of @emph{each line} to go off screen.
3712 Usually, no horizontal scrolling is in effect; then the leftmost
3713 column is at the left edge of the window. In this state, scrolling to
3714 the right is meaningless, since there is no data to the left of the edge
3715 to be revealed by it; so this is not allowed. Scrolling to the left is
3716 allowed; it scrolls the first columns of text off the edge of the window
3717 and can reveal additional columns on the right that were truncated
3718 before. Once a window has a nonzero amount of leftward horizontal
3719 scrolling, you can scroll it back to the right, but only so far as to
3720 reduce the net horizontal scroll to zero. There is no limit to how far
3721 left you can scroll, but eventually all the text will disappear off the
3724 @vindex auto-hscroll-mode
3725 If @code{auto-hscroll-mode} is set, redisplay automatically alters
3726 the horizontal scrolling of a window as necessary to ensure that point
3727 is always visible. However, you can still set the horizontal
3728 scrolling value explicitly. The value you specify serves as a lower
3729 bound for automatic scrolling, i.e., automatic scrolling will not
3730 scroll a window to a column less than the specified one.
3732 @deffn Command scroll-left &optional count set-minimum
3733 This function scrolls the selected window @var{count} columns to the
3734 left (or to the right if @var{count} is negative). The default
3735 for @var{count} is the window width, minus 2.
3737 The return value is the total amount of leftward horizontal scrolling in
3738 effect after the change---just like the value returned by
3739 @code{window-hscroll} (below).
3741 Note that text in paragraphs whose base direction is right-to-left
3742 (@pxref{Bidirectional Display}) moves in the opposite direction: e.g.,
3743 it moves to the right when @code{scroll-left} is invoked with a
3744 positive value of @var{count}.
3746 Once you scroll a window as far right as it can go, back to its normal
3747 position where the total leftward scrolling is zero, attempts to scroll
3748 any farther right have no effect.
3750 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
3751 the lower bound for automatic scrolling; that is, automatic scrolling
3752 will not scroll a window to a column less than the value returned by
3753 this function. Interactive calls pass non-@code{nil} for
3757 @deffn Command scroll-right &optional count set-minimum
3758 This function scrolls the selected window @var{count} columns to the
3759 right (or to the left if @var{count} is negative). The default
3760 for @var{count} is the window width, minus 2. Aside from the direction
3761 of scrolling, this works just like @code{scroll-left}.
3764 @defun window-hscroll &optional window
3765 This function returns the total leftward horizontal scrolling of
3766 @var{window}---the number of columns by which the text in @var{window}
3767 is scrolled left past the left margin. (In right-to-left paragraphs,
3768 the value is the total amount of the rightward scrolling instead.)
3769 The default for @var{window} is the selected window.
3771 The return value is never negative. It is zero when no horizontal
3772 scrolling has been done in @var{window} (which is usually the case).
3791 @defun set-window-hscroll window columns
3792 This function sets horizontal scrolling of @var{window}. The value of
3793 @var{columns} specifies the amount of scrolling, in terms of columns
3794 from the left margin (right margin in right-to-left paragraphs). The
3795 argument @var{columns} should be zero or positive; if not, it is taken
3796 as zero. Fractional values of @var{columns} are not supported at
3799 Note that @code{set-window-hscroll} may appear not to work if you test
3800 it by evaluating a call with @kbd{M-:} in a simple way. What happens
3801 is that the function sets the horizontal scroll value and returns, but
3802 then redisplay adjusts the horizontal scrolling to make point visible,
3803 and this overrides what the function did. You can observe the
3804 function's effect if you call it while point is sufficiently far from
3805 the left margin that it will remain visible.
3807 The value returned is @var{columns}.
3811 (set-window-hscroll (selected-window) 10)
3817 Here is how you can determine whether a given position @var{position}
3818 is off the screen due to horizontal scrolling:
3820 @c FIXME: Maybe hscroll-on-screen-p is a better name?
3823 (defun hscroll-on-screen (window position)
3825 (goto-char position)
3827 (>= (- (current-column) (window-hscroll window)) 0)
3828 (< (- (current-column) (window-hscroll window))
3829 (window-width window)))))
3834 @node Coordinates and Windows
3835 @section Coordinates and Windows
3836 @cindex frame-relative coordinate
3837 @cindex coordinate, relative to frame
3838 @cindex window position
3840 This section describes functions that report the position of a window.
3841 Most of these functions report positions relative to an origin at the
3842 native position of the window's frame (@pxref{Frame Geometry}). Some
3843 functions report positions relative to the origin of the display of the
3844 window's frame. In any case, the origin has the coordinates (0, 0) and
3845 X and Y coordinates increase rightward and downward
3848 For the following functions, X and Y coordinates are reported in
3849 integer character units, i.e., numbers of lines and columns
3850 respectively. On a graphical display, each ``line'' and ``column''
3851 corresponds to the height and width of the default character specified by
3852 the frame's default font (@pxref{Frame Font}).
3854 @defun window-edges &optional window body absolute pixelwise
3855 This function returns a list of the edge coordinates of @var{window}.
3856 If @var{window} is omitted or @code{nil}, it defaults to the selected
3859 The return value has the form @code{(@var{left} @var{top} @var{right}
3860 @var{bottom})}. These list elements are, respectively, the X
3861 coordinate of the leftmost column occupied by the window, the Y
3862 coordinate of the topmost row, the X coordinate one column to the
3863 right of the rightmost column, and the Y coordinate one row down from
3866 Note that these are the actual outer edges of the window, including any
3867 header line, mode line, scroll bar, fringes, window divider and display
3868 margins. On a text terminal, if the window has a neighbor on its right,
3869 its right edge includes the separator line between the window and its
3872 If the optional argument @var{body} is @code{nil}, this means to
3873 return the edges corresponding to the total size of @var{window}.
3874 @var{body} non-@code{nil} means to return the edges of @var{window}'s
3875 body (aka text area). If @var{body} is non-@code{nil}, @var{window}
3876 must specify a live window.
3878 If the optional argument @var{absolute} is @code{nil}, this means to
3879 return edges relative to the native position of @var{window}'s frame.
3880 @var{absolute} non-@code{nil} means to return coordinates relative to
3881 the origin (0, 0) of @var{window}'s display. On non-graphical systems
3882 this argument has no effect.
3884 If the optional argument @var{pixelwise} is @code{nil}, this means to
3885 return the coordinates in terms of the default character width and
3886 height of @var{window}'s frame (@pxref{Frame Font}), rounded if
3887 necessary. @var{pixelwise} non-@code{nil} means to return the
3888 coordinates in pixels. Note that the pixel specified by @var{right} and
3889 @var{bottom} is immediately outside of these edges. If @var{absolute}
3890 is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too.
3893 @defun window-body-edges &optional window
3894 This function returns the edges of @var{window}'s body (@pxref{Window
3895 Sizes}). Calling @code{(window-body-edges window)} is equivalent to
3896 calling @code{(window-edges window t)}, see above.
3899 @comment The following two functions are confusing and hardly used.
3901 @defun window-left-column &optional window
3902 This function returns the leftmost column of @var{window}. This value
3903 equals the @var{left} entry in the list returned by @code{(window-edges
3904 window)} minus the number of columns occupied by the internal border of
3905 @var{window}'s frame.
3908 @defun window-top-line &optional window
3909 This function returns the topmost row of @var{window}. This value is
3910 equal to the @var{top} entry in the list returned by @code{(window-edges
3911 window)} minus the number of lines occupied by the internal border of
3912 @var{window}'s frame.
3916 The following functions can be used to relate a set of
3917 frame-relative coordinates to a window:
3919 @defun window-at x y &optional frame
3920 This function returns the live window at the coordinates @var{x} and
3921 @var{y} given in default character sizes (@pxref{Frame Font}) relative
3922 to the native position of @var{frame} (@pxref{Frame Geometry}).
3924 If there is no window at that position, the return value is @code{nil}.
3925 If @var{frame} is omitted or @code{nil}, it defaults to the selected
3929 @defun coordinates-in-window-p coordinates window
3930 This function checks whether a window @var{window} occupies the frame
3931 relative coordinates @var{coordinates}, and if so, which part of the
3932 window that is. @var{window} should be a live window.
3934 @var{coordinates} should be a cons cell of the form @code{(@var{x}
3935 . @var{y})}, where @var{x} and @var{y} are given in default character
3936 sizes (@pxref{Frame Font}) relative to the native position of
3937 @var{window}'s frame (@pxref{Frame Geometry}).
3939 If there is no window at the specified position, the return value is
3940 @code{nil} . Otherwise, the return value is one of the following:
3943 @item (@var{relx} . @var{rely})
3944 The coordinates are inside @var{window}. The numbers @var{relx} and
3945 @var{rely} are the equivalent window-relative coordinates for the
3946 specified position, counting from 0 at the top left corner of the
3950 The coordinates are in the mode line of @var{window}.
3953 The coordinates are in the header line of @var{window}.
3956 The coordinates are in the divider separating @var{window} from a
3957 window on the right.
3959 @item bottom-divider
3960 The coordinates are in the divider separating @var{window} from a
3964 The coordinates are in the vertical line between @var{window} and its
3965 neighbor to the right. This value occurs only if the window doesn't
3966 have a scroll bar; positions in a scroll bar are considered outside the
3967 window for these purposes.
3971 The coordinates are in the left or right fringe of the window.
3975 The coordinates are in the left or right margin of the window.
3978 The coordinates are not in any part of @var{window}.
3981 The function @code{coordinates-in-window-p} does not require a frame as
3982 argument because it always uses the frame that @var{window} is on.
3985 The following functions return window positions in pixels, rather
3986 than character units. Though mostly useful on graphical displays,
3987 they can also be called on text terminals, where the screen area of
3988 each text character is taken to be one pixel.
3990 @defun window-pixel-edges &optional window
3991 This function returns a list of pixel coordinates for the edges of
3992 @var{window}. Calling @code{(window-pixel-edges window)} is equivalent
3993 to calling @code{(window-edges window nil nil t)}, see above.
3996 @comment The following two functions are confusing and hardly used.
3998 @defun window-pixel-left &optional window
3999 This function returns the left pixel edge of window @var{window}. This
4000 value equals the @var{left} entry in the list returned by
4001 @code{(window-pixel-edges window)} minus the number of pixels occupied
4002 by the internal border of @var{window}'s frame. @var{window} must be a
4003 valid window and defaults to the selected one.
4006 @defun window-pixel-top &optional window
4007 This function returns the top pixel edge of window @var{window}. This
4008 value is equal to the @var{top} entry in the list returned by
4009 @code{(window-pixel-edges window)} minus the number of pixels occupied
4010 by the internal border of @var{window}'s frame. @var{window} must be a
4011 valid window and defaults to the selected one.
4015 @defun window-body-pixel-edges &optional window
4016 This function returns the pixel edges of @var{window}'s body. Calling
4017 @code{(window-body-pixel-edges window)} is equivalent to calling
4018 @code{(window-edges window t nil t)}, see above.
4021 The following functions return window positions in pixels, relative to
4022 the origin of the display screen rather than that of the frame:
4024 @defun window-absolute-pixel-edges &optional window
4025 This function returns the pixel coordinates of @var{WINDOW} relative to
4026 an origin at (0, 0) of the display of @var{window}'s frame. Calling
4027 @code{(window-absolute-pixel-edges)} is equivalent to calling
4028 @code{(window-edges window nil t t)}, see above.
4031 @defun window-absolute-body-pixel-edges &optional window
4032 This function returns the pixel coordinates of @var{WINDOW}'s body
4033 relative to an origin at (0, 0) of the display of @var{window}'s frame.
4034 Calling @code{(window-absolute-body-pixel-edges window)} is equivalent
4035 to calling @code{(window-edges window t t t)}, see above.
4037 Combined with @code{set-mouse-absolute-pixel-position}, this function
4038 can be used to move the mouse pointer to an arbitrary buffer position
4039 visible in some window:
4043 (let ((edges (window-absolute-body-pixel-edges))
4044 (position (pos-visible-in-window-p nil nil t)))
4045 (set-mouse-absolute-pixel-position
4046 (+ (nth 0 edges) (nth 0 position))
4047 (+ (nth 1 edges) (nth 1 position))))
4051 On a graphical terminal this form ``warps'' the mouse cursor to the
4052 upper left corner of the glyph at the selected window's point. A
4053 position calculated this way can be also used to show a tooltip window
4057 The following function returns the screen coordinates of a buffer
4058 position visible in a window:
4060 @defun window-absolute-pixel-position &optional position window
4061 If the buffer position @var{position} is visible in window @var{window},
4062 this function returns the display coordinates of the upper/left corner
4063 of the glyph at @var{position}. The return value is a cons of the X-
4064 and Y-coordinates of that corner, relative to an origin at (0, 0) of
4065 @var{window}'s display. It returns @code{nil} if @var{position} is not
4066 visible in @var{window}.
4068 @var{window} must be a live window and defaults to the selected
4069 window. @var{position} defaults to the value of @code{window-point}
4072 This means that in order to move the mouse pointer to the position of
4073 point in the selected window, it's sufficient to write:
4077 (let ((position (window-absolute-pixel-position)))
4078 (set-mouse-absolute-pixel-position
4079 (car position) (cdr position)))
4085 @node Window Configurations
4086 @section Window Configurations
4087 @cindex window configurations
4088 @cindex saving window information
4090 A @dfn{window configuration} records the entire layout of one
4091 frame---all windows, their sizes, which buffers they contain, how those
4092 buffers are scrolled, and their value of point; also their
4093 fringes, margins, and scroll bar settings. It also includes the value
4094 of @code{minibuffer-scroll-window}. As a special exception, the window
4095 configuration does not record the value of point in the selected window
4096 for the current buffer.
4098 You can bring back an entire frame layout by restoring a previously
4099 saved window configuration. If you want to record the layout of all
4100 frames instead of just one, use a frame configuration instead of a
4101 window configuration. @xref{Frame Configurations}.
4103 @defun current-window-configuration &optional frame
4104 This function returns a new object representing @var{frame}'s current
4105 window configuration. The default for @var{frame} is the selected
4106 frame. The variable @code{window-persistent-parameters} specifies
4107 which window parameters (if any) are saved by this function.
4108 @xref{Window Parameters}.
4111 @defun set-window-configuration configuration
4112 This function restores the configuration of windows and buffers as
4113 specified by @var{configuration}, for the frame that @var{configuration}
4116 The argument @var{configuration} must be a value that was previously
4117 returned by @code{current-window-configuration}. The configuration is
4118 restored in the frame from which @var{configuration} was made, whether
4119 that frame is selected or not. In some rare cases this may trigger
4120 execution of the @code{window-size-change-functions} (@pxref{Window
4121 Hooks}) even if the size of windows did not change at all. The
4122 @code{window-configuration-change-hook} functions will be called if and
4123 only if at least one window was added to or deleted from the frame.
4125 If the frame from which @var{configuration} was saved is dead, all this
4126 function does is restore the three variables @code{window-min-height},
4127 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
4128 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
4130 Here is a way of using this function to get the same effect
4131 as @code{save-window-excursion}:
4135 (let ((config (current-window-configuration)))
4137 (progn (split-window-below nil)
4139 (set-window-configuration config)))
4144 @defmac save-window-excursion forms@dots{}
4145 This macro records the window configuration of the selected frame,
4146 executes @var{forms} in sequence, then restores the earlier window
4147 configuration. The return value is the value of the final form in
4150 Most Lisp code should not use this macro; @code{save-selected-window}
4151 is typically sufficient. In particular, this macro cannot reliably
4152 prevent the code in @var{forms} from opening new windows, because new
4153 windows might be opened in other frames (@pxref{Choosing Window}), and
4154 @code{save-window-excursion} only saves and restores the window
4155 configuration on the current frame.
4157 Do not use this macro in @code{window-size-change-functions}; exiting
4158 the macro triggers execution of @code{window-size-change-functions},
4159 leading to an endless loop.
4162 @defun window-configuration-p object
4163 This function returns @code{t} if @var{object} is a window configuration.
4166 @defun compare-window-configurations config1 config2
4167 This function compares two window configurations as regards the
4168 structure of windows, but ignores the values of point and the
4169 saved scrolling positions---it can return @code{t} even if those
4172 The function @code{equal} can also compare two window configurations; it
4173 regards configurations as unequal if they differ in any respect, even a
4177 @defun window-configuration-frame config
4178 This function returns the frame for which the window configuration
4179 @var{config} was made.
4182 Other primitives to look inside of window configurations would make
4183 sense, but are not implemented because we did not need them. See the
4184 file @file{winner.el} for some more operations on windows
4187 The objects returned by @code{current-window-configuration} die
4188 together with the Emacs process. In order to store a window
4189 configuration on disk and read it back in another Emacs session, you
4190 can use the functions described next. These functions are also useful
4191 to clone the state of a frame into an arbitrary live window
4192 (@code{set-window-configuration} effectively clones the windows of a
4193 frame into the root window of that very frame only).
4195 @cindex window state
4196 @defun window-state-get &optional window writable
4197 This function returns the state of @var{window} as a Lisp object. The
4198 argument @var{window} must be a valid window and defaults to the root
4199 window of the selected frame.
4201 If the optional argument @var{writable} is non-@code{nil}, this means to
4202 not use markers for sampling positions like @code{window-point} or
4203 @code{window-start}. This argument should be non-@code{nil} when the
4204 state will be written to disk and read back in another session.
4206 Together, the argument @var{writable} and the variable
4207 @code{window-persistent-parameters} specify which window parameters are
4208 saved by this function. @xref{Window Parameters}.
4211 The value returned by @code{window-state-get} can be used in the same
4212 session to make a clone of a window in another window. It can be also
4213 written to disk and read back in another session. In either case, use
4214 the following function to restore the state of the window.
4216 @defun window-state-put state &optional window ignore
4217 This function puts the window state @var{state} into @var{window}.
4218 The argument @var{state} should be the state of a window returned by
4219 an earlier invocation of @code{window-state-get}, see above. The
4220 optional argument @var{window} can be either a live window or an
4221 internal window (@pxref{Windows and Frames}) and defaults to the
4222 selected one. If @var{window} is not live, it is replaced by a live
4223 window before putting @var{state} into it.
4225 If the optional argument @var{ignore} is non-@code{nil}, it means to ignore
4226 minimum window sizes and fixed-size restrictions. If @var{ignore}
4227 is @code{safe}, this means windows can get as small as one line
4232 @node Window Parameters
4233 @section Window Parameters
4234 @cindex window parameters
4236 This section describes how window parameters can be used to associate
4237 additional information with windows.
4239 @defun window-parameter window parameter
4240 This function returns @var{window}'s value for @var{parameter}. The
4241 default for @var{window} is the selected window. If @var{window} has no
4242 setting for @var{parameter}, this function returns @code{nil}.
4245 @defun window-parameters &optional window
4246 This function returns all parameters of @var{window} and their values.
4247 The default for @var{window} is the selected window. The return value
4248 is either @code{nil}, or an association list whose elements have the form
4249 @code{(@var{parameter} . @var{value})}.
4252 @defun set-window-parameter window parameter value
4253 This function sets @var{window}'s value of @var{parameter} to
4254 @var{value} and returns @var{value}. The default for @var{window}
4255 is the selected window.
4258 By default, the functions that save and restore window configurations or the
4259 states of windows (@pxref{Window Configurations}) do not care about
4260 window parameters. This means that when you change the value of a
4261 parameter within the body of a @code{save-window-excursion}, the
4262 previous value is not restored when that macro exits. It also means
4263 that when you restore via @code{window-state-put} a window state saved
4264 earlier by @code{window-state-get}, all cloned windows have their
4265 parameters reset to @code{nil}. The following variable allows you to
4266 override the standard behavior:
4268 @defvar window-persistent-parameters
4269 This variable is an alist specifying which parameters get saved by
4270 @code{current-window-configuration} and @code{window-state-get}, and
4271 subsequently restored by @code{set-window-configuration} and
4272 @code{window-state-put}. @xref{Window Configurations}.
4274 The @sc{car} of each entry of this alist is a symbol specifying the
4275 parameter. The @sc{cdr} should be one of the following:
4279 This value means the parameter is saved neither by
4280 @code{window-state-get} nor by @code{current-window-configuration}.
4283 This value specifies that the parameter is saved by
4284 @code{current-window-configuration} and (provided its @var{writable}
4285 argument is @code{nil}) by @code{window-state-get}.
4287 @item @code{writable}
4288 This means that the parameter is saved unconditionally by both
4289 @code{current-window-configuration} and @code{window-state-get}. This
4290 value should not be used for parameters whose values do not have a read
4291 syntax. Otherwise, invoking @code{window-state-put} in another session
4292 may fail with an @code{invalid-read-syntax} error.
4296 Some functions (notably @code{delete-window},
4297 @code{delete-other-windows} and @code{split-window}), may behave specially
4298 when their @var{window} argument has a parameter set. You can override
4299 such special behavior by binding the following variable to a
4300 non-@code{nil} value:
4302 @defvar ignore-window-parameters
4303 If this variable is non-@code{nil}, some standard functions do not
4304 process window parameters. The functions currently affected by this are
4305 @code{split-window}, @code{delete-window}, @code{delete-other-windows},
4306 and @code{other-window}.
4308 An application can bind this variable to a non-@code{nil} value around
4309 calls to these functions. If it does so, the application is fully
4310 responsible for correctly assigning the parameters of all involved
4311 windows when exiting that function.
4314 The following parameters are currently used by the window management
4318 @item @code{delete-window}
4319 This parameter affects the execution of @code{delete-window}
4320 (@pxref{Deleting Windows}).
4322 @item @code{delete-other-windows}
4323 This parameter affects the execution of @code{delete-other-windows}
4324 (@pxref{Deleting Windows}).
4326 @item @code{split-window}
4327 This parameter affects the execution of @code{split-window}
4328 (@pxref{Splitting Windows}).
4330 @item @code{other-window}
4331 This parameter affects the execution of @code{other-window}
4332 (@pxref{Cyclic Window Ordering}).
4334 @item @code{no-other-window}
4335 This parameter marks the window as not selectable by @code{other-window}
4336 (@pxref{Cyclic Window Ordering}).
4338 @item @code{clone-of}
4339 This parameter specifies the window that this one has been cloned
4340 from. It is installed by @code{window-state-get} (@pxref{Window
4343 @item @code{preserved-size}
4344 This parameter specifies a buffer, a direction where @code{nil} means
4345 vertical and @code{t} horizontal, and a size in pixels. If this window
4346 displays the specified buffer and its size in the indicated direction
4347 equals the size specified by this parameter, then Emacs will try to
4348 preserve the size of this window in the indicated direction. This
4349 parameter is installed and updated by the function
4350 @code{window-preserve-size} (@pxref{Preserving Window Sizes}).
4352 @item @code{quit-restore}
4353 This parameter is installed by the buffer display functions
4354 (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
4355 (@pxref{Quitting Windows}). It contains four elements:
4357 The first element is one of the symbols @code{window}, meaning that the
4358 window has been specially created by @code{display-buffer}; @code{frame},
4359 a separate frame has been created; @code{same}, the window has
4360 displayed the same buffer before; or @code{other}, the window showed
4361 another buffer before.
4363 The second element is either one of the symbols @code{window} or
4364 @code{frame}, or a list whose elements are the buffer shown in the
4365 window before, that buffer's window start and window point positions,
4366 and the window's height at that time.
4368 The third element is the window selected at the time the parameter was
4369 created. The function @code{quit-restore-window} tries to reselect that
4370 window when it deletes the window passed to it as argument.
4372 The fourth element is the buffer whose display caused the creation of
4373 this parameter. @code{quit-restore-window} deletes the specified window
4374 only if it still shows that buffer.
4377 There are additional parameters @code{window-atom} and @code{window-side};
4378 these are reserved and should not be used by applications.
4382 @section Hooks for Window Scrolling and Changes
4383 @cindex hooks for window operations
4385 This section describes how a Lisp program can take action whenever a
4386 window displays a different part of its buffer or a different buffer.
4387 There are three actions that can change this: scrolling the window,
4388 switching buffers in the window, and changing the size of the window.
4389 The first two actions run @code{window-scroll-functions}; the last runs
4390 @code{window-size-change-functions}.
4392 @defvar window-scroll-functions
4393 This variable holds a list of functions that Emacs should call before
4394 redisplaying a window with scrolling. Displaying a different buffer in
4395 the window also runs these functions.
4397 This variable is not a normal hook, because each function is called with
4398 two arguments: the window, and its new display-start position.
4400 These functions must take care when using @code{window-end}
4401 (@pxref{Window Start and End}); if you need an up-to-date value, you
4402 must use the @var{update} argument to ensure you get it.
4404 @strong{Warning:} don't use this feature to alter the way the window
4405 is scrolled. It's not designed for that, and such use probably won't
4409 @defvar window-size-change-functions
4410 This variable holds a list of functions to be called if the size of any
4411 window changes for any reason. The functions are called once per
4412 redisplay, and once for each frame on which size changes have occurred.
4414 Each function receives the frame as its sole argument. To find out
4415 whether a specific window has changed size, compare the return values of
4416 @code{window-pixel-width-before-size-change} and
4417 @code{window-pixel-width} respectively
4418 @code{window-pixel-height-before-size-change} and
4419 @code{window-pixel-height} for that window (@pxref{Window Sizes}).
4421 These function are usually only called when at least one window was
4422 added or has changed size since the last time this hook was run for the
4423 associated frame. In some rare cases this hook also runs when a window
4424 that was added intermittently has been deleted afterwards. In these
4425 cases none of the windows on the frame will appear to have changed its
4428 You may use @code{save-selected-window} in these functions
4429 (@pxref{Selecting Windows}). However, do not use
4430 @code{save-window-excursion} (@pxref{Window Configurations}); exiting
4431 that macro counts as a size change, which would cause these functions to
4435 @defvar window-configuration-change-hook
4436 A normal hook that is run every time the window configuration of a frame
4437 changes. Window configuration changes include splitting and deleting
4438 windows and the display of a different buffer in a window. Resizing the
4439 frame or individual windows do not count as configuration changes. Use
4440 @code{window-size-change-functions}, see above, when you want to track
4441 size changes that are not caused by the deletion or creation of windows.
4443 The buffer-local part of this hook is run once for each window on the
4444 affected frame, with the relevant window selected and its buffer
4445 current. The global part is run once for the modified frame, with that
4449 In addition, you can use @code{jit-lock-register} to register a Font
4450 Lock fontification function, which will be called whenever parts of a
4451 buffer are (re)fontified because a window was scrolled or its size
4452 changed. @xref{Other Font Lock Variables}.