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.
620 Note that when one or both fringes are removed (by setting their width
621 to zero), the display engine reserves two character cells, one on each
622 side of the window, for displaying the continuation and truncation
623 glyphs, which leaves 2 columns less for text display. (The function
624 @code{window-max-chars-per-line}, described below, takes this
625 peculiarity into account.)
627 @defun window-body-width &optional window pixelwise
628 This function returns the width, in columns, of the body of window
629 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
630 the selected window; otherwise it must be a live window.
632 If the optional argument @var{pixelwise} is non-@code{nil}, this
633 function returns the body width of @var{window} in units of pixels.
635 If @var{pixelwise} is @code{nil}, the return value is rounded down to
636 the nearest integer, if necessary. This means that if a column on the
637 right of the text area is only partially visible, that column is not
638 counted. It also means that the width of a window's body can never
639 exceed its total width as returned by @code{window-total-width}.
642 @cindex window body size
643 @cindex body size of a window
644 @defun window-body-size &optional window horizontal pixelwise
645 This function returns the body height or body width of @var{window}. If
646 @var{horizontal} is omitted or @code{nil}, it is equivalent to calling
647 @code{window-body-height} for @var{window}; otherwise it is equivalent
648 to calling @code{window-body-width}. In either case, the optional
649 argument @var{pixelwise} is passed to the function called.
652 For compatibility with previous versions of Emacs,
653 @code{window-height} is an alias for @code{window-total-height}, and
654 @code{window-width} is an alias for @code{window-body-width}. These
655 aliases are considered obsolete and will be removed in the future.
657 The pixel heights of a window's mode and header line can be retrieved
658 with the functions given below. Their return value is usually accurate
659 unless the window has not been displayed before: In that case, the
660 return value is based on an estimate of the font used for the window's
663 @defun window-mode-line-height &optional window
664 This function returns the height in pixels of @var{window}'s mode line.
665 @var{window} must be a live window and defaults to the selected one. If
666 @var{window} has no mode line, the return value is zero.
669 @defun window-header-line-height &optional window
670 This function returns the height in pixels of @var{window}'s header
671 line. @var{window} must be a live window and defaults to the selected
672 one. If @var{window} has no header line, the return value is zero.
675 Functions for retrieving the height and/or width of window dividers
676 (@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
677 (@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
678 described in the corresponding sections.
680 If your Lisp program needs to make layout decisions, you will find the
681 following function useful:
683 @defun window-max-chars-per-line &optional window face
684 This function returns the number of characters displayed in the
685 specified face @var{face} in the specified window @var{window} (which
686 must be a live window). If @var{face} was remapped (@pxref{Face
687 Remapping}), the information is returned for the remapped face. If
688 omitted or @code{nil}, @var{face} defaults to the default face, and
689 @var{window} defaults to the selected window.
691 Unlike @code{window-body-width}, this function accounts for the actual
692 size of @var{face}'s font, instead of working in units of the canonical
693 character width of @var{window}'s frame (@pxref{Frame Font}). It also
694 accounts for space used by the continuation glyph, if @var{window} lacks
695 one or both of its fringes.
698 @cindex fixed-size window
699 @vindex window-min-height
700 @vindex window-min-width
701 Commands that change the size of windows (@pxref{Resizing Windows}),
702 or split them (@pxref{Splitting Windows}), obey the variables
703 @code{window-min-height} and @code{window-min-width}, which specify the
704 smallest allowable window height and width. They also obey the variable
705 @code{window-size-fixed}, with which a window can be @dfn{fixed} in
706 size (@pxref{Preserving Window Sizes}).
708 @defopt window-min-height
709 This option specifies the minimum total height, in lines, of any window.
710 Its value has to accommodate at least one text line as well as a mode
711 and header line, a horizontal scroll bar and a bottom divider, if
715 @defopt window-min-width
716 This option specifies the minimum total width, in columns, of any
717 window. Its value has to accommodate two text columns as well as
718 margins, fringes, a scroll bar and a right divider, if present.
721 The following function tells how small a specific window can get taking
722 into account the sizes of its areas and the values of
723 @code{window-min-height}, @code{window-min-width} and
724 @code{window-size-fixed} (@pxref{Preserving Window Sizes}).
726 @defun window-min-size &optional window horizontal ignore pixelwise
727 This function returns the minimum size of @var{window}. @var{window}
728 must be a valid window and defaults to the selected one. The optional
729 argument @var{horizontal} non-@code{nil} means to return the minimum
730 number of columns of @var{window}; otherwise return the minimum number
731 of @var{window}'s lines.
733 The return value makes sure that all components of @var{window} remain
734 fully visible if @var{window}'s size were actually set to it. With
735 @var{horizontal} @code{nil} it includes the mode and header line, the
736 horizontal scroll bar and the bottom divider, if present. With
737 @var{horizontal} non-@code{nil} it includes the margins and fringes, the
738 vertical scroll bar and the right divider, if present.
740 The optional argument @var{ignore}, if non-@code{nil}, means ignore
741 restrictions imposed by fixed size windows, @code{window-min-height} or
742 @code{window-min-width} settings. If @var{ignore} equals @code{safe},
743 live windows may get as small as @code{window-safe-min-height} lines and
744 @code{window-safe-min-width} columns. If @var{ignore} is a window,
745 ignore restrictions for that window only. Any other non-@code{nil}
746 value means ignore all of the above restrictions for all windows.
748 The optional argument @var{pixelwise} non-@code{nil} means to return the
749 minimum size of @var{window} counted in pixels.
752 @node Resizing Windows
753 @section Resizing Windows
754 @cindex window resizing
755 @cindex resize window
756 @cindex changing window size
757 @cindex window size, changing
759 This section describes functions for resizing a window without
760 changing the size of its frame. Because live windows do not overlap,
761 these functions are meaningful only on frames that contain two or more
762 windows: resizing a window also changes the size of a neighboring
763 window. If there is just one window on a frame, its size cannot be
764 changed except by resizing the frame (@pxref{Size and Position}).
766 Except where noted, these functions also accept internal windows as
767 arguments. Resizing an internal window causes its child windows to be
768 resized to fit the same space.
770 @defun window-resizable window delta &optional horizontal ignore pixelwise
771 This function returns @var{delta} if the size of @var{window} can be
772 changed vertically by @var{delta} lines. If the optional argument
773 @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
774 @var{window} can be resized horizontally by @var{delta} columns. It
775 does not actually change the window size.
777 If @var{window} is @code{nil}, it defaults to the selected window.
779 A positive value of @var{delta} means to check whether the window can be
780 enlarged by that number of lines or columns; a negative value of
781 @var{delta} means to check whether the window can be shrunk by that many
782 lines or columns. If @var{delta} is non-zero, a return value of 0 means
783 that the window cannot be resized.
785 Normally, the variables @code{window-min-height} and
786 @code{window-min-width} specify the smallest allowable window size
787 (@pxref{Window Sizes}). However, if the optional argument @var{ignore}
788 is non-@code{nil}, this function ignores @code{window-min-height} and
789 @code{window-min-width}, as well as @code{window-size-fixed}. Instead,
790 it considers the minimum-height window to be one consisting of a header
791 and a mode line, a horizontal scrollbar and a bottom divider (if any),
792 plus a text area one line tall; and a minimum-width window as one
793 consisting of fringes, margins, a scroll bar and a right divider (if
794 any), plus a text area two columns wide.
796 If the optional argument @var{pixelwise} is non-@code{nil},
797 @var{delta} is interpreted as pixels.
800 @defun window-resize window delta &optional horizontal ignore pixelwise
801 This function resizes @var{window} by @var{delta} increments. If
802 @var{horizontal} is @code{nil}, it changes the height by @var{delta}
803 lines; otherwise, it changes the width by @var{delta} columns. A
804 positive @var{delta} means to enlarge the window, and a negative
805 @var{delta} means to shrink it.
807 If @var{window} is @code{nil}, it defaults to the selected window. If
808 the window cannot be resized as demanded, an error is signaled.
810 The optional argument @var{ignore} has the same meaning as for the
811 function @code{window-resizable} above.
813 If the optional argument @var{pixelwise} is non-@code{nil},
814 @var{delta} will be interpreted as pixels.
816 The choice of which window edges this function alters depends on the
817 values of the option @code{window-combination-resize} and the
818 combination limits of the involved windows; in some cases, it may alter
819 both edges. @xref{Recombining Windows}. To resize by moving only the
820 bottom or right edge of a window, use the function
821 @code{adjust-window-trailing-edge}.
824 @c The commands enlarge-window, enlarge-window-horizontally,
825 @c shrink-window, and shrink-window-horizontally are documented in the
826 @c Emacs manual. They are not preferred for calling from Lisp.
828 @defun adjust-window-trailing-edge window delta &optional horizontal pixelwise
829 This function moves @var{window}'s bottom edge by @var{delta} lines.
830 If optional argument @var{horizontal} is non-@code{nil}, it instead
831 moves the right edge by @var{delta} columns. If @var{window} is
832 @code{nil}, it defaults to the selected window.
834 If the optional argument @var{pixelwise} is non-@code{nil},
835 @var{delta} is interpreted as pixels.
837 A positive @var{delta} moves the edge downwards or to the right; a
838 negative @var{delta} moves it upwards or to the left. If the edge
839 cannot be moved as far as specified by @var{delta}, this function
840 moves it as far as possible but does not signal a error.
842 This function tries to resize windows adjacent to the edge that is
843 moved. If this is not possible for some reason (e.g., if that adjacent
844 window is fixed-size), it may resize other windows.
847 @cindex pixelwise, resizing windows
848 @defopt window-resize-pixelwise
849 If the value of this option is non-@code{nil}, Emacs resizes windows in
850 units of pixels. This currently affects functions like
851 @code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
852 @code{minimize-window}, @code{fit-window-to-buffer},
853 @code{fit-frame-to-buffer} and
854 @code{shrink-window-if-larger-than-buffer} (all listed below).
856 Note that when a frame's pixel size is not a multiple of its character
857 size, at least one window may get resized pixelwise even if this
858 option is @code{nil}. The default value is @code{nil}.
861 The following commands resize windows in more specific ways. When
862 called interactively, they act on the selected window.
864 @deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size
865 This command adjusts the height or width of @var{window} to fit the text
866 in it. It returns non-@code{nil} if it was able to resize @var{window},
867 and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
868 defaults to the selected window. Otherwise, it should be a live window.
870 If @var{window} is part of a vertical combination, this function adjusts
871 @var{window}'s height. The new height is calculated from the actual
872 height of the accessible portion of its buffer. The optional argument
873 @var{max-height}, if non-@code{nil}, specifies the maximum total height
874 that this function can give @var{window}. The optional argument
875 @var{min-height}, if non-@code{nil}, specifies the minimum total height
876 that it can give, which overrides the variable @code{window-min-height}.
877 Both @var{max-height} and @var{min-height} are specified in lines and
878 include mode and header line and a bottom divider, if any.
880 If @var{window} is part of a horizontal combination and the value of the
881 option @code{fit-window-to-buffer-horizontally} (see below) is
882 non-@code{nil}, this function adjusts @var{window}'s height. The new
883 width of @var{window} is calculated from the maximum length of its
884 buffer's lines that follow the current start position of @var{window}.
885 The optional argument @var{max-width} specifies a maximum width and
886 defaults to the width of @var{window}'s frame. The optional argument
887 @var{min-width} specifies a minimum width and defaults to
888 @code{window-min-width}. Both @var{max-width} and @var{min-width} are
889 specified in columns and include fringes, margins and scrollbars, if
892 The optional argument @var{preserve-size}, if non-@code{nil}, will
893 install a parameter to preserve the size of @var{window} during future
894 resize operations (@pxref{Preserving Window Sizes}).
896 If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
897 this function will try to resize the frame of @var{window} to fit its
898 contents by calling @code{fit-frame-to-buffer} (see below).
901 @defopt fit-window-to-buffer-horizontally
902 If this is non-@code{nil}, @code{fit-window-to-buffer} can resize
903 windows horizontally. If this is @code{nil} (the default)
904 @code{fit-window-to-buffer} never resizes windows horizontally. If this
905 is @code{only}, it can resize windows horizontally only. Any other
906 value means @code{fit-window-to-buffer} can resize windows in both
910 @defopt fit-frame-to-buffer
911 If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a
912 frame to its buffer. A frame is fit if and only if its root window is a
913 live window and this option is non-@code{nil}. If this is
914 @code{horizontally}, frames are fit horizontally only. If this is
915 @code{vertically}, frames are fit vertically only. Any other
916 non-@code{nil} value means frames can be resized in both dimensions.
919 If you have a frame that displays only one window, you can fit that
920 frame to its buffer using the command @code{fit-frame-to-buffer}.
922 @deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
923 This command adjusts the size of @var{frame} to display the contents of
924 its buffer exactly. @var{frame} can be any live frame and defaults to
925 the selected one. Fitting is done only if @var{frame}'s root window is
926 live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
927 and @var{min-width} specify bounds on the new total size of
928 @var{frame}'s root window. @var{min-height} and @var{min-width} default
929 to the values of @code{window-min-height} and @code{window-min-width}
932 If the optional argument @var{only} is @code{vertically}, this function
933 may resize the frame vertically only. If @var{only} is
934 @code{horizontally}, it may resize the frame horizontally only.
937 The behavior of @code{fit-frame-to-buffer} can be controlled with the
938 help of the two options listed next.
940 @defopt fit-frame-to-buffer-margins
941 This option can be used to specify margins around frames to be fit by
942 @code{fit-frame-to-buffer}. Such margins can be useful to avoid, for
943 example, that such frames overlap the taskbar.
945 It specifies the numbers of pixels to be left free on the left, above,
946 the right, and below a frame that shall be fit. The default specifies
947 @code{nil} for each which means to use no margins. The value specified
948 here can be overridden for a specific frame by that frame's
949 @code{fit-frame-to-buffer-margins} parameter, if present.
952 @defopt fit-frame-to-buffer-sizes
953 This option specifies size boundaries for @code{fit-frame-to-buffer}.
954 It specifies the total maximum and minimum lines and maximum and minimum
955 columns of the root window of any frame that shall be fit to its buffer.
956 If any of these values is non-@code{nil}, it overrides the corresponding
957 argument of @code{fit-frame-to-buffer}.
960 @deffn Command shrink-window-if-larger-than-buffer &optional window
961 This command attempts to reduce @var{window}'s height as much as
962 possible while still showing its full buffer, but no less than
963 @code{window-min-height} lines. The return value is non-@code{nil} if
964 the window was resized, and @code{nil} otherwise. If @var{window} is
965 omitted or @code{nil}, it defaults to the selected window. Otherwise,
966 it should be a live window.
968 This command does nothing if the window is already too short to
969 display all of its buffer, or if any of the buffer is scrolled
970 off-screen, or if the window is the only live window in its frame.
972 This command calls @code{fit-window-to-buffer} (see above) to do its
977 @cindex balancing window sizes
978 @deffn Command balance-windows &optional window-or-frame
979 This function balances windows in a way that gives more space to
980 full-width and/or full-height windows. If @var{window-or-frame}
981 specifies a frame, it balances all windows on that frame. If
982 @var{window-or-frame} specifies a window, it balances only that window
983 and its siblings (@pxref{Windows and Frames}).
986 @deffn Command balance-windows-area
987 This function attempts to give all windows on the selected frame
988 approximately the same share of the screen area. Full-width or
989 full-height windows are not given more space than other windows.
992 @cindex maximizing windows
993 @deffn Command maximize-window &optional window
994 This function attempts to make @var{window} as large as possible, in
995 both dimensions, without resizing its frame or deleting other windows.
996 If @var{window} is omitted or @code{nil}, it defaults to the selected
1000 @cindex minimizing windows
1001 @deffn Command minimize-window &optional window
1002 This function attempts to make @var{window} as small as possible, in
1003 both dimensions, without deleting it or resizing its frame. If
1004 @var{window} is omitted or @code{nil}, it defaults to the selected
1009 @node Preserving Window Sizes
1010 @section Preserving Window Sizes
1011 @cindex preserving window sizes
1013 A window can get resized explicitly by using one of the functions from
1014 the preceding section or implicitly, for example, when resizing an
1015 adjacent window, when splitting or deleting a window (@pxref{Splitting
1016 Windows}, @pxref{Deleting Windows}) or when resizing the window's frame
1017 (@pxref{Size and Position}).
1019 It is possible to avoid implicit resizing of a specific window when
1020 there are one or more other resizable windows on the same frame. For
1021 this purpose, Emacs must be advised to @dfn{preserve} the size of that
1022 window. There are two basic ways to do that.
1024 @defvar window-size-fixed
1025 If this buffer-local variable is non-@code{nil}, the size of any window
1026 displaying the buffer cannot normally be changed. Deleting a window or
1027 changing the frame's size may still change the window's size, if there
1030 If the value is @code{height}, then only the window's height is fixed;
1031 if the value is @code{width}, then only the window's width is fixed.
1032 Any other non-@code{nil} value fixes both the width and the height.
1034 If this variable is @code{nil}, this does not necessarily mean that any
1035 window showing the buffer can be resized in the desired direction. To
1036 determine that, use the function @code{window-resizable}.
1037 @xref{Resizing Windows}.
1040 Often @code{window-size-fixed} is overly aggressive because it inhibits
1041 any attempt to explicitly resize or split an affected window as well.
1042 This may even happen after the window has been resized implicitly, for
1043 example, when deleting an adjacent window or resizing the window's
1044 frame. The following function tries hard to never disallow resizing
1045 such a window explicitly:
1047 @defun window-preserve-size &optional window horizontal preserve
1048 This function (un-)marks the height of window @var{window} as preserved
1049 for future resize operations. @var{window} must be a live window and
1050 defaults to the selected one. If the optional argument @var{horizontal}
1051 is non-@code{nil}, it (un-)marks the width of @var{window} as preserved.
1053 If the optional argument @var{preserve} is @code{t}, this means to
1054 preserve the current height/width of @var{window}'s body. The
1055 height/width of @var{window} will change only if Emacs has no better
1056 choice. Resizing a window whose height/width is preserved by this
1057 function never throws an error.
1059 If @var{preserve} is @code{nil}, this means to stop preserving the
1060 height/width of @var{window}, lifting any respective restraint induced
1061 by a previous call of this function for @var{window}. Calling
1062 @code{enlarge-window}, @code{shrink-window} or
1063 @code{fit-window-to-buffer} with @var{window} as argument may also
1064 remove the respective restraint.
1067 @code{window-preserve-size} is currently invoked by the following
1071 @item fit-window-to-buffer
1072 If the optional argument @var{preserve-size} of that function
1073 (@pxref{Resizing Windows}) is non-@code{nil}, the size established by
1074 that function is preserved.
1076 @item display-buffer
1077 If the @var{alist} argument of that function (@pxref{Choosing Window})
1078 contains a @code{preserve-size} entry, the size of the window produced
1079 by that function is preserved.
1082 @code{window-preserve-size} installs a window parameter (@pxref{Window
1083 Parameters}) called @code{preserved-size} which is consulted by the
1084 window resizing functions. This parameter will not prevent resizing the
1085 window when the window shows another buffer than the one when
1086 @code{window-preserve-size} was invoked or if its size has changed since
1089 The following function can be used to check whether the height of a
1090 particular window is preserved:
1092 @defun window-preserved-size &optional window horizontal
1093 This function returns the preserved height of window @var{window} in
1094 pixels. @var{window} must be a live window and defaults to the selected
1095 one. If the optional argument @var{horizontal} is non-@code{nil}, it
1096 returns the preserved width of @var{window}. It returns @code{nil} if
1097 the size of @var{window} is not preserved.
1101 @node Splitting Windows
1102 @section Splitting Windows
1103 @cindex splitting windows
1104 @cindex window splitting
1106 This section describes functions for creating a new window by
1107 @dfn{splitting} an existing one.
1109 @defun split-window &optional window size side pixelwise
1110 This function creates a new live window next to the window
1111 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
1112 to the selected window. That window is split, and reduced in
1113 size. The space is taken up by the new window, which is returned.
1115 The optional second argument @var{size} determines the sizes of
1116 @var{window} and/or the new window. If it is omitted or @code{nil},
1117 both windows are given equal sizes; if there is an odd line, it is
1118 allocated to the new window. If @var{size} is a positive number,
1119 @var{window} is given @var{size} lines (or columns, depending on the
1120 value of @var{side}). If @var{size} is a negative number, the new
1121 window is given @minus{}@var{size} lines (or columns).
1123 If @var{size} is @code{nil}, this function obeys the variables
1124 @code{window-min-height} and @code{window-min-width} (@pxref{Window
1125 Sizes}). Thus, it signals an error if splitting would result in making
1126 a window smaller than those variables specify. However, a
1127 non-@code{nil} value for @var{size} causes those variables to be
1128 ignored; in that case, the smallest allowable window is considered to be
1129 one that has space for a text area one line tall and/or two columns
1132 Hence, if @var{size} is specified, it's the caller's responsibility to
1133 check whether the emanating windows are large enough to encompass all
1134 areas like a mode line or a scroll bar. The function
1135 @code{window-min-size} (@pxref{Window Sizes}) can be used to determine
1136 the minimum requirements of @var{window} in this regard. Since the new
1137 window usually inherits areas like the mode line or the scroll bar
1138 from @var{window}, that function is also a good guess for the minimum
1139 size of the new window. The caller should specify a smaller size only
1140 if it correspondingly removes an inherited area before the next
1143 The optional third argument @var{side} determines the position of the
1144 new window relative to @var{window}. If it is @code{nil} or
1145 @code{below}, the new window is placed below @var{window}. If it is
1146 @code{above}, the new window is placed above @var{window}. In both
1147 these cases, @var{size} specifies a total window height, in lines.
1149 If @var{side} is @code{t} or @code{right}, the new window is placed on
1150 the right of @var{window}. If @var{side} is @code{left}, the new
1151 window is placed on the left of @var{window}. In both these cases,
1152 @var{size} specifies a total window width, in columns.
1154 The optional fourth argument @var{pixelwise}, if non-@code{nil}, means
1155 to interpret @var{size} in units of pixels, instead of lines and
1158 If @var{window} is a live window, the new window inherits various
1159 properties from it, including margins and scroll bars. If
1160 @var{window} is an internal window, the new window inherits the
1161 properties of the window selected within @var{window}'s frame.
1163 The behavior of this function may be altered by the window parameters
1164 of @var{window}, so long as the variable
1165 @code{ignore-window-parameters} is @code{nil}. If the value of
1166 the @code{split-window} window parameter is @code{t}, this function
1167 ignores all other window parameters. Otherwise, if the value of the
1168 @code{split-window} window parameter is a function, that function is
1169 called with the arguments @var{window}, @var{size}, and @var{side}, in
1170 lieu of the usual action of @code{split-window}. Otherwise, this
1171 function obeys the @code{window-atom} or @code{window-side} window
1172 parameter, if any. @xref{Window Parameters}.
1175 As an example, here is a sequence of @code{split-window} calls that
1176 yields the window configuration discussed in @ref{Windows and Frames}.
1177 This example demonstrates splitting a live window as well as splitting
1178 an internal window. We begin with a frame containing a single window
1179 (a live root window), which we denote by @var{W4}. Calling
1180 @code{(split-window W4)} yields this window configuration:
1184 ______________________________________
1185 | ____________________________________ |
1189 ||_________________W4_________________||
1190 | ____________________________________ |
1194 ||_________________W5_________________||
1195 |__________________W3__________________|
1201 The @code{split-window} call has created a new live window, denoted by
1202 @var{W5}. It has also created a new internal window, denoted by
1203 @var{W3}, which becomes the root window and the parent of both
1204 @var{W4} and @var{W5}.
1206 Next, we call @code{(split-window W3 nil 'left)}, passing the
1207 internal window @var{W3} as the argument. The result:
1211 ______________________________________
1212 | ______ ____________________________ |
1213 || || __________________________ ||
1217 || |||____________W4____________|||
1218 || || __________________________ ||
1221 || |||____________W5____________|||
1222 ||__W2__||_____________W3_____________ |
1223 |__________________W1__________________|
1228 A new live window @var{W2} is created, to the left of the internal
1229 window @var{W3}. A new internal window @var{W1} is created, becoming
1230 the new root window.
1232 For interactive use, Emacs provides two commands which always split
1233 the selected window. These call @code{split-window} internally.
1235 @deffn Command split-window-right &optional size
1236 This function splits the selected window into two side-by-side
1237 windows, putting the selected window on the left. If @var{size} is
1238 positive, the left window gets @var{size} columns; if @var{size} is
1239 negative, the right window gets @minus{}@var{size} columns.
1242 @deffn Command split-window-below &optional size
1243 This function splits the selected window into two windows, one above
1244 the other, leaving the upper window selected. If @var{size} is
1245 positive, the upper window gets @var{size} lines; if @var{size} is
1246 negative, the lower window gets @minus{}@var{size} lines.
1249 @defopt split-window-keep-point
1250 If the value of this variable is non-@code{nil} (the default),
1251 @code{split-window-below} behaves as described above.
1253 If it is @code{nil}, @code{split-window-below} adjusts point in each
1254 of the two windows to minimize redisplay. (This is useful on slow
1255 terminals.) It selects whichever window contains the screen line that
1256 point was previously on. Note that this only affects
1257 @code{split-window-below}, not the lower-level @code{split-window}
1262 @node Deleting Windows
1263 @section Deleting Windows
1264 @cindex deleting windows
1266 @dfn{Deleting} a window removes it from the frame's window tree. If
1267 the window is a live window, it disappears from the screen. If the
1268 window is an internal window, its child windows are deleted too.
1270 Even after a window is deleted, it continues to exist as a Lisp
1271 object, until there are no more references to it. Window deletion can
1272 be reversed, by restoring a saved window configuration (@pxref{Window
1275 @deffn Command delete-window &optional window
1276 This function removes @var{window} from display and returns
1277 @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
1278 the selected window. If deleting the window would leave no more
1279 windows in the window tree (e.g., if it is the only live window in the
1280 frame), an error is signaled.
1282 By default, the space taken up by @var{window} is given to one of its
1283 adjacent sibling windows, if any. However, if the variable
1284 @code{window-combination-resize} is non-@code{nil}, the space is
1285 proportionally distributed among any remaining windows in the same
1286 window combination. @xref{Recombining Windows}.
1288 The behavior of this function may be altered by the window parameters
1289 of @var{window}, so long as the variable
1290 @code{ignore-window-parameters} is @code{nil}. If the value of
1291 the @code{delete-window} window parameter is @code{t}, this function
1292 ignores all other window parameters. Otherwise, if the value of the
1293 @code{delete-window} window parameter is a function, that function is
1294 called with the argument @var{window}, in lieu of the usual action of
1295 @code{delete-window}. Otherwise, this function obeys the
1296 @code{window-atom} or @code{window-side} window parameter, if any.
1297 @xref{Window Parameters}.
1300 @deffn Command delete-other-windows &optional window
1301 This function makes @var{window} fill its frame, by deleting other
1302 windows as necessary. If @var{window} is omitted or @code{nil}, it
1303 defaults to the selected window. The return value is @code{nil}.
1305 The behavior of this function may be altered by the window parameters
1306 of @var{window}, so long as the variable
1307 @code{ignore-window-parameters} is @code{nil}. If the value of
1308 the @code{delete-other-windows} window parameter is @code{t}, this
1309 function ignores all other window parameters. Otherwise, if the value
1310 of the @code{delete-other-windows} window parameter is a function,
1311 that function is called with the argument @var{window}, in lieu of the
1312 usual action of @code{delete-other-windows}. Otherwise, this function
1313 obeys the @code{window-atom} or @code{window-side} window parameter,
1314 if any. @xref{Window Parameters}.
1317 @deffn Command delete-windows-on &optional buffer-or-name frame
1318 This function deletes all windows showing @var{buffer-or-name}, by
1319 calling @code{delete-window} on those windows. @var{buffer-or-name}
1320 should be a buffer, or the name of a buffer; if omitted or @code{nil},
1321 it defaults to the current buffer. If there are no windows showing
1322 the specified buffer, this function does nothing. If the specified
1323 buffer is a minibuffer, an error is signaled.
1325 If there is a dedicated window showing the buffer, and that window is
1326 the only one on its frame, this function also deletes that frame if it
1327 is not the only frame on the terminal.
1329 The optional argument @var{frame} specifies which frames to operate
1334 means operate on all frames.
1336 means operate on the selected frame.
1337 @item @code{visible}
1338 means operate on all visible frames.
1340 means operate on all visible or iconified frames.
1342 means operate on that frame.
1345 Note that this argument does not have the same meaning as in other
1346 functions which scan all live windows (@pxref{Cyclic Window
1347 Ordering}). Specifically, the meanings of @code{t} and @code{nil} here
1348 are the opposite of what they are in those other functions.
1352 @node Recombining Windows
1353 @section Recombining Windows
1354 @cindex recombining windows
1355 @cindex windows, recombining
1357 When deleting the last sibling of a window @var{W}, its parent window
1358 is deleted too, with @var{W} replacing it in the window tree. This
1359 means that @var{W} must be recombined with its parent's siblings to
1360 form a new window combination (@pxref{Windows and Frames}). In some
1361 occasions, deleting a live window may even entail the deletion of two
1366 ______________________________________
1367 | ______ ____________________________ |
1368 || || __________________________ ||
1369 || ||| ___________ ___________ |||
1371 || ||||____W6_____||_____W7____||||
1372 || |||____________W4____________|||
1373 || || __________________________ ||
1376 || |||____________W5____________|||
1377 ||__W2__||_____________W3_____________ |
1378 |__________________W1__________________|
1384 Deleting @var{W5} in this configuration normally causes the deletion of
1385 @var{W3} and @var{W4}. The remaining live windows @var{W2},
1386 @var{W6} and @var{W7} are recombined to form a new horizontal
1387 combination with parent @var{W1}.
1389 Sometimes, however, it makes sense to not delete a parent window like
1390 @var{W4}. In particular, a parent window should not be removed when it
1391 was used to preserve a combination embedded in a combination of the same
1392 type. Such embeddings make sense to assure that when you split a window
1393 and subsequently delete the new window, Emacs reestablishes the layout
1394 of the associated frame as it existed before the splitting.
1396 Consider a scenario starting with two live windows @var{W2} and
1397 @var{W3} and their parent @var{W1}.
1401 ______________________________________
1402 | ____________________________________ |
1409 ||_________________W2_________________||
1410 | ____________________________________ |
1413 ||_________________W3_________________||
1414 |__________________W1__________________|
1420 Split @var{W2} to make a new window @var{W4} as follows.
1424 ______________________________________
1425 | ____________________________________ |
1428 ||_________________W2_________________||
1429 | ____________________________________ |
1432 ||_________________W4_________________||
1433 | ____________________________________ |
1436 ||_________________W3_________________||
1437 |__________________W1__________________|
1443 Now, when enlarging a window vertically, Emacs tries to obtain the
1444 corresponding space from its lower sibling, provided such a window
1445 exists. In our scenario, enlarging @var{W4} will steal space from
1450 ______________________________________
1451 | ____________________________________ |
1454 ||_________________W2_________________||
1455 | ____________________________________ |
1460 ||_________________W4_________________||
1461 | ____________________________________ |
1462 ||_________________W3_________________||
1463 |__________________W1__________________|
1469 Deleting @var{W4} will now give its entire space to @var{W2},
1470 including the space earlier stolen from @var{W3}.
1474 ______________________________________
1475 | ____________________________________ |
1484 ||_________________W2_________________||
1485 | ____________________________________ |
1486 ||_________________W3_________________||
1487 |__________________W1__________________|
1493 This can be counterintuitive, in particular if @var{W4} were used for
1494 displaying a buffer only temporarily (@pxref{Temporary Displays}), and
1495 you want to continue working with the initial layout.
1497 The behavior can be fixed by making a new parent window when splitting
1498 @var{W2}. The variable described next allows that to be done.
1500 @defopt window-combination-limit
1501 This variable controls whether splitting a window shall make a new
1502 parent window. The following values are recognized:
1506 This means that the new live window is allowed to share the existing
1507 parent window, if one exists, provided the split occurs in the same
1508 direction as the existing window combination (otherwise, a new internal
1509 window is created anyway).
1512 In this case @code{display-buffer} makes a new parent window if it is
1513 passed a @code{window-height} or @code{window-width} entry in the
1514 @var{alist} argument (@pxref{Display Action Functions}).
1517 This value causes the creation of a new parent window when a window is
1518 split for showing a temporary buffer (@pxref{Temporary Displays}) only.
1520 @item display-buffer
1521 This means that when @code{display-buffer} (@pxref{Choosing Window})
1522 splits a window it always makes a new parent window.
1525 In this case a new parent window is always created when splitting a
1526 window. Thus, if the value of this variable is at all times @code{t},
1527 then at all times every window tree is a binary tree (a tree where each
1528 window except the root window has exactly one sibling).
1531 The default is @code{nil}. Other values are reserved for future use.
1533 If, as a consequence of this variable's setting, @code{split-window}
1534 makes a new parent window, it also calls
1535 @code{set-window-combination-limit} (see below) on the newly-created
1536 internal window. This affects how the window tree is rearranged when
1537 the child windows are deleted (see below).
1540 If @code{window-combination-limit} is @code{t}, splitting @var{W2} in
1541 the initial configuration of our scenario would have produced this:
1545 ______________________________________
1546 | ____________________________________ |
1547 || __________________________________ ||
1549 |||________________W2________________|||
1550 || __________________________________ ||
1552 |||________________W4________________|||
1553 ||_________________W5_________________||
1554 | ____________________________________ |
1557 ||_________________W3_________________||
1558 |__________________W1__________________|
1564 A new internal window @var{W5} has been created; its children are
1565 @var{W2} and the new live window @var{W4}. Now, @var{W2} is the only
1566 sibling of @var{W4}, so enlarging @var{W4} will try to shrink
1567 @var{W2}, leaving @var{W3} unaffected. Observe that @var{W5}
1568 represents a vertical combination of two windows embedded in the
1569 vertical combination @var{W1}.
1571 @cindex window combination limit
1572 @defun set-window-combination-limit window limit
1573 This function sets the @dfn{combination limit} of the window
1574 @var{window} to @var{limit}. This value can be retrieved via the
1575 function @code{window-combination-limit}. See below for its effects;
1576 note that it is only meaningful for internal windows. The
1577 @code{split-window} function automatically calls this function, passing
1578 it @code{t} as @var{limit}, provided the value of the variable
1579 @code{window-combination-limit} is @code{t} when it is called.
1582 @defun window-combination-limit window
1583 This function returns the combination limit for @var{window}.
1585 The combination limit is meaningful only for an internal window. If it
1586 is @code{nil}, then Emacs is allowed to automatically delete
1587 @var{window}, in response to a window deletion, in order to group the
1588 child windows of @var{window} with its sibling windows to form a new
1589 window combination. If the combination limit is @code{t}, the child
1590 windows of @var{window} are never automatically recombined with its
1593 If, in the configuration shown at the beginning of this section, the
1594 combination limit of @var{W4} (the parent window of @var{W6} and
1595 @var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete
1599 Alternatively, the problems sketched above can be avoided by always
1600 resizing all windows in the same combination whenever one of its windows
1601 is split or deleted. This also permits splitting windows that would be
1602 otherwise too small for such an operation.
1604 @defopt window-combination-resize
1605 If this variable is @code{nil}, @code{split-window} can only split a
1606 window (denoted by @var{window}) if @var{window}'s screen area is large
1607 enough to accommodate both itself and the new window.
1609 If this variable is @code{t}, @code{split-window} tries to resize all
1610 windows that are part of the same combination as @var{window}, in order
1611 to accommodate the new window. In particular, this may allow
1612 @code{split-window} to succeed even if @var{window} is a fixed-size
1613 window or too small to ordinarily split. Furthermore, subsequently
1614 resizing or deleting @var{window} may resize all other windows in its
1617 The default is @code{nil}. Other values are reserved for future use.
1618 The value of this variable is ignored when
1619 @code{window-combination-limit} is non-@code{nil}.
1622 To illustrate the effect of @code{window-combination-resize}, consider
1623 the following frame layout.
1627 ______________________________________
1628 | ____________________________________ |
1633 ||_________________W2_________________||
1634 | ____________________________________ |
1639 ||_________________W3_________________||
1640 |__________________W1__________________|
1646 If @code{window-combination-resize} is @code{nil}, splitting window
1647 @var{W3} leaves the size of @var{W2} unchanged:
1651 ______________________________________
1652 | ____________________________________ |
1657 ||_________________W2_________________||
1658 | ____________________________________ |
1660 ||_________________W3_________________||
1661 | ____________________________________ |
1663 ||_________________W4_________________||
1664 |__________________W1__________________|
1670 If @code{window-combination-resize} is @code{t}, splitting @var{W3}
1671 instead leaves all three live windows with approximately the same
1676 ______________________________________
1677 | ____________________________________ |
1680 ||_________________W2_________________||
1681 | ____________________________________ |
1684 ||_________________W3_________________||
1685 | ____________________________________ |
1688 ||_________________W4_________________||
1689 |__________________W1__________________|
1695 Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will
1696 distribute its space proportionally among the two remaining live
1700 @node Selecting Windows
1701 @section Selecting Windows
1702 @cindex selecting a window
1704 @defun select-window window &optional norecord
1705 This function makes @var{window} the selected window and the window
1706 selected within its frame (@pxref{Basic Windows}) and selects that
1707 frame. It also makes @var{window}'s buffer (@pxref{Buffers and
1708 Windows}) current and sets that buffer's value of @code{point} to the
1709 value of @code{window-point} (@pxref{Window Point}) in @var{window}.
1710 @var{window} must be a live window. The return value is @var{window}.
1712 By default, this function also moves @var{window}'s buffer to the front
1713 of the buffer list (@pxref{Buffer List}), and makes @var{window} the
1714 most recently selected window. However, if the optional argument
1715 @var{norecord} is non-@code{nil}, these additional actions are omitted.
1717 This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
1718 unless @var{norecord} is non-@code{nil}. Note that applications and
1719 internal routines often temporarily select a window in order to simplify
1720 coding. As a rule, such selections (including those made by the macros
1721 @code{save-selected-window} and @code{with-selected-window} below) are
1722 not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
1723 Selections that really count are those causing a visible change in
1724 the next redisplay of @var{window}'s frame and should be always
1725 recorded. This also means that to run a function each time a window
1726 gets selected, putting it on @code{buffer-list-update-hook} should be
1730 @cindex most recently selected windows
1731 The sequence of calls to @code{select-window} with a non-@code{nil}
1732 @var{norecord} argument determines an ordering of windows by their
1733 selection time. The function @code{get-lru-window} can be used to
1734 retrieve the least recently selected live window (@pxref{Cyclic Window
1737 @defmac save-selected-window forms@dots{}
1738 This macro records the selected frame, as well as the selected window
1739 of each frame, executes @var{forms} in sequence, then restores the
1740 earlier selected frame and windows. It also saves and restores the
1741 current buffer. It returns the value of the last form in @var{forms}.
1743 This macro does not save or restore anything about the sizes,
1744 arrangement or contents of windows; therefore, if @var{forms} change
1745 them, the change persists. If the previously selected window of some
1746 frame is no longer live at the time of exit from @var{forms}, that
1747 frame's selected window is left alone. If the previously selected
1748 window is no longer live, then whatever window is selected at the end of
1749 @var{forms} remains selected. The current buffer is restored if and
1750 only if it is still live when exiting @var{forms}.
1752 This macro changes neither the ordering of recently selected windows nor
1756 @defmac with-selected-window window forms@dots{}
1757 This macro selects @var{window}, executes @var{forms} in sequence, then
1758 restores the previously selected window and current buffer. The ordering
1759 of recently selected windows and the buffer list remain unchanged unless
1760 you deliberately change them within @var{forms}; for example, by calling
1761 @code{select-window} with argument @var{norecord} @code{nil}.
1763 This macro does not change the order of recently selected windows or
1767 @defun frame-selected-window &optional frame
1768 This function returns the window on @var{frame} that is selected
1769 within that frame. @var{frame} should be a live frame; if omitted or
1770 @code{nil}, it defaults to the selected frame.
1773 @defun set-frame-selected-window frame window &optional norecord
1774 This function makes @var{window} the window selected within the frame
1775 @var{frame}. @var{frame} should be a live frame; if @code{nil}, it
1776 defaults to the selected frame. @var{window} should be a live window;
1777 if @code{nil}, it defaults to the selected window.
1779 If @var{frame} is the selected frame, this makes @var{window} the
1782 If the optional argument @var{norecord} is non-@code{nil}, this
1783 function does not alter the list of most recently selected windows,
1784 nor the buffer list.
1787 @cindex window use time
1788 @cindex use time of window
1789 @cindex window order by time of last use
1790 @defun window-use-time &optional window
1791 This functions returns the use time of window @var{window}.
1792 @var{window} must be a live window and defaults to the selected one.
1794 The @dfn{use time} of a window is not really a time value, but an
1795 integer that does increase monotonically with each call of
1796 @code{select-window} with a @code{nil} @var{norecord} argument. The
1797 window with the lowest use time is usually called the least recently
1798 used window while the window with the highest use time is called the
1799 most recently used one (@pxref{Cyclic Window Ordering}).
1803 @node Cyclic Window Ordering
1804 @section Cyclic Ordering of Windows
1805 @cindex cyclic ordering of windows
1806 @cindex ordering of windows, cyclic
1807 @cindex window ordering, cyclic
1809 When you use the command @kbd{C-x o} (@code{other-window}) to select
1810 some other window, it moves through live windows in a specific order.
1811 For any given configuration of windows, this order never varies. It
1812 is called the @dfn{cyclic ordering of windows}.
1814 The ordering is determined by a depth-first traversal of each frame's
1815 window tree, retrieving the live windows which are the leaf nodes of the
1816 tree (@pxref{Windows and Frames}). If the minibuffer is active, the
1817 minibuffer window is included too. The ordering is cyclic, so the last
1818 window in the sequence is followed by the first one.
1820 @defun next-window &optional window minibuf all-frames
1821 @cindex minibuffer window, and @code{next-window}
1822 This function returns a live window, the one following @var{window} in
1823 the cyclic ordering of windows. @var{window} should be a live window;
1824 if omitted or @code{nil}, it defaults to the selected window.
1826 The optional argument @var{minibuf} specifies whether minibuffer windows
1827 should be included in the cyclic ordering. Normally, when @var{minibuf}
1828 is @code{nil}, a minibuffer window is included only if it is currently
1829 active; this matches the behavior of @kbd{C-x o}. (Note that a
1830 minibuffer window is active as long as its minibuffer is in use; see
1833 If @var{minibuf} is @code{t}, the cyclic ordering includes all
1834 minibuffer windows. If @var{minibuf} is neither @code{t} nor
1835 @code{nil}, minibuffer windows are not included even if they are active.
1837 The optional argument @var{all-frames} specifies which frames to
1842 means to consider windows on @var{window}'s frame. If the minibuffer
1843 window is considered (as specified by the @var{minibuf} argument),
1844 then frames that share the minibuffer window are considered too.
1847 means to consider windows on all existing frames.
1849 @item @code{visible}
1850 means to consider windows on all visible frames.
1853 means to consider windows on all visible or iconified frames.
1856 means to consider windows on that specific frame.
1859 means to consider windows on @var{window}'s frame, and no others.
1862 If more than one frame is considered, the cyclic ordering is obtained
1863 by appending the orderings for those frames, in the same order as the
1864 list of all live frames (@pxref{Finding All Frames}).
1867 @defun previous-window &optional window minibuf all-frames
1868 This function returns a live window, the one preceding @var{window} in
1869 the cyclic ordering of windows. The other arguments are handled like
1870 in @code{next-window}.
1873 @deffn Command other-window count &optional all-frames
1874 This function selects a live window, one @var{count} places from the
1875 selected window in the cyclic ordering of windows. If @var{count} is
1876 a positive number, it skips @var{count} windows forwards; if
1877 @var{count} is negative, it skips @minus{}@var{count} windows
1878 backwards; if @var{count} is zero, that simply re-selects the selected
1879 window. When called interactively, @var{count} is the numeric prefix
1882 The optional argument @var{all-frames} has the same meaning as in
1883 @code{next-window}, like a @code{nil} @var{minibuf} argument to
1886 This function does not select a window that has a non-@code{nil}
1887 @code{no-other-window} window parameter (@pxref{Window Parameters}).
1890 @defun walk-windows fun &optional minibuf all-frames
1891 This function calls the function @var{fun} once for each live window,
1892 with the window as the argument.
1894 It follows the cyclic ordering of windows. The optional arguments
1895 @var{minibuf} and @var{all-frames} specify the set of windows
1896 included; these have the same arguments as in @code{next-window}. If
1897 @var{all-frames} specifies a frame, the first window walked is the
1898 first window on that frame (the one returned by
1899 @code{frame-first-window}), not necessarily the selected window.
1901 If @var{fun} changes the window configuration by splitting or deleting
1902 windows, that does not alter the set of windows walked, which is
1903 determined prior to calling @var{fun} for the first time.
1906 @defun one-window-p &optional no-mini all-frames
1907 This function returns @code{t} if the selected window is the only live
1908 window, and @code{nil} otherwise.
1910 If the minibuffer window is active, it is normally considered (so that
1911 this function returns @code{nil}). However, if the optional argument
1912 @var{no-mini} is non-@code{nil}, the minibuffer window is ignored even
1913 if active. The optional argument @var{all-frames} has the same
1914 meaning as for @code{next-window}.
1917 @cindex finding windows
1918 The following functions return a window which satisfies some
1919 criterion, without selecting it:
1921 @cindex least recently used window
1922 @defun get-lru-window &optional all-frames dedicated not-selected
1923 This function returns a live window which is heuristically the least
1924 recently used. The optional argument @var{all-frames} has
1925 the same meaning as in @code{next-window}.
1927 If any full-width windows are present, only those windows are
1928 considered. A minibuffer window is never a candidate. A dedicated
1929 window (@pxref{Dedicated Windows}) is never a candidate unless the
1930 optional argument @var{dedicated} is non-@code{nil}. The selected
1931 window is never returned, unless it is the only candidate. However, if
1932 the optional argument @var{not-selected} is non-@code{nil}, this
1933 function returns @code{nil} in that case.
1936 @cindex most recently used window
1937 @defun get-mru-window &optional all-frames dedicated not-selected
1938 This function is like @code{get-lru-window}, but it returns the most
1939 recently used window instead. The meaning of the arguments is the
1940 same as described for @code{get-lru-window}.
1943 @cindex largest window
1944 @defun get-largest-window &optional all-frames dedicated not-selected
1945 This function returns the window with the largest area (height times
1946 width). The optional argument @var{all-frames} specifies the windows to
1947 search, and has the same meaning as in @code{next-window}.
1949 A minibuffer window is never a candidate. A dedicated window
1950 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1951 argument @var{dedicated} is non-@code{nil}. The selected window is not
1952 a candidate if the optional argument @var{not-selected} is
1953 non-@code{nil}. If the optional argument @var{not-selected} is
1954 non-@code{nil} and the selected window is the only candidate, this
1955 function returns @code{nil}.
1957 If there are two candidate windows of the same size, this function
1958 prefers the one that comes first in the cyclic ordering of windows,
1959 starting from the selected window.
1962 @cindex window that satisfies a predicate
1963 @cindex conditional selection of windows
1964 @defun get-window-with-predicate predicate &optional minibuf all-frames default
1965 This function calls the function @var{predicate} for each of the
1966 windows in the cyclic order of windows in turn, passing it the window
1967 as an argument. If the predicate returns non-@code{nil} for any
1968 window, this function stops and returns that window. If no such
1969 window is found, the return value is @var{default} (which defaults to
1972 The optional arguments @var{minibuf} and @var{all-frames} specify the
1973 windows to search, and have the same meanings as in
1978 @node Buffers and Windows
1979 @section Buffers and Windows
1980 @cindex examining windows
1981 @cindex windows, controlling precisely
1982 @cindex buffers, controlled in windows
1984 This section describes low-level functions for examining and setting
1985 the contents of windows. @xref{Switching Buffers}, for higher-level
1986 functions for displaying a specific buffer in a window.
1988 @defun window-buffer &optional window
1989 This function returns the buffer that @var{window} is displaying. If
1990 @var{window} is omitted or @code{nil} it defaults to the selected
1991 window. If @var{window} is an internal window, this function returns
1995 @defun set-window-buffer window buffer-or-name &optional keep-margins
1996 This function makes @var{window} display @var{buffer-or-name}.
1997 @var{window} should be a live window; if @code{nil}, it defaults to
1998 the selected window. @var{buffer-or-name} should be a buffer, or the
1999 name of an existing buffer. This function does not change which
2000 window is selected, nor does it directly change which buffer is
2001 current (@pxref{Current Buffer}). Its return value is @code{nil}.
2003 If @var{window} is @dfn{strongly dedicated} to a buffer and
2004 @var{buffer-or-name} does not specify that buffer, this function
2005 signals an error. @xref{Dedicated Windows}.
2007 By default, this function resets @var{window}'s position, display
2008 margins, fringe widths, and scroll bar settings, based on the local
2009 variables in the specified buffer. However, if the optional argument
2010 @var{keep-margins} is non-@code{nil}, it leaves the display margins
2011 and fringe widths unchanged.
2013 When writing an application, you should normally use the higher-level
2014 functions described in @ref{Switching Buffers}, instead of calling
2015 @code{set-window-buffer} directly.
2017 This runs @code{window-scroll-functions}, followed by
2018 @code{window-configuration-change-hook}. @xref{Window Hooks}.
2021 @defvar buffer-display-count
2022 This buffer-local variable records the number of times a buffer has been
2023 displayed in a window. It is incremented each time
2024 @code{set-window-buffer} is called for the buffer.
2027 @defvar buffer-display-time
2028 This buffer-local variable records the time at which a buffer was last
2029 displayed in a window. The value is @code{nil} if the buffer has
2030 never been displayed. It is updated each time
2031 @code{set-window-buffer} is called for the buffer, with the value
2032 returned by @code{current-time} (@pxref{Time of Day}).
2035 @defun get-buffer-window &optional buffer-or-name all-frames
2036 This function returns the first window displaying @var{buffer-or-name}
2037 in the cyclic ordering of windows, starting from the selected window
2038 (@pxref{Cyclic Window Ordering}). If no such window exists, the
2039 return value is @code{nil}.
2041 @var{buffer-or-name} should be a buffer or the name of a buffer; if
2042 omitted or @code{nil}, it defaults to the current buffer. The
2043 optional argument @var{all-frames} specifies which windows to
2048 @code{t} means consider windows on all existing frames.
2050 @code{visible} means consider windows on all visible frames.
2052 0 means consider windows on all visible or iconified frames.
2054 A frame means consider windows on that frame only.
2056 Any other value means consider windows on the selected frame.
2059 Note that these meanings differ slightly from those of the
2060 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
2061 Ordering}). This function may be changed in a future version of Emacs
2062 to eliminate this discrepancy.
2065 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
2066 This function returns a list of all windows currently displaying
2067 @var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the
2068 name of an existing buffer. If omitted or @code{nil}, it defaults to
2069 the current buffer. If the currently selected window displays
2070 @var{buffer-or-name}, it will be the first in the list returned by
2073 The arguments @var{minibuf} and @var{all-frames} have the same
2074 meanings as in the function @code{next-window} (@pxref{Cyclic Window
2075 Ordering}). Note that the @var{all-frames} argument does @emph{not}
2076 behave exactly like in @code{get-buffer-window}.
2079 @deffn Command replace-buffer-in-windows &optional buffer-or-name
2080 This command replaces @var{buffer-or-name} with some other buffer, in
2081 all windows displaying it. @var{buffer-or-name} should be a buffer, or
2082 the name of an existing buffer; if omitted or @code{nil}, it defaults to
2085 The replacement buffer in each window is chosen via
2086 @code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated
2087 window displaying @var{buffer-or-name} is deleted if possible
2088 (@pxref{Dedicated Windows}). If such a window is the only window on its
2089 frame and there are other frames on the same terminal, the frame is
2090 deleted as well. If the dedicated window is the only window on the only
2091 frame on its terminal, the buffer is replaced anyway.
2095 @node Switching Buffers
2096 @section Switching to a Buffer in a Window
2097 @cindex switching to a buffer
2098 @cindex displaying a buffer
2100 This section describes high-level functions for switching to a specified
2101 buffer in some window. In general, ``switching to a buffer'' means to
2102 (1) show the buffer in some window, (2) make that window the selected
2103 window (and its frame the selected frame), and (3) make the buffer the
2106 Do @emph{not} use these functions to make a buffer temporarily
2107 current just so a Lisp program can access or modify it. They have
2108 side-effects, such as changing window histories (@pxref{Window
2109 History}), which will surprise the user if used that way. If you want
2110 to make a buffer current to modify it in Lisp, use
2111 @code{with-current-buffer}, @code{save-current-buffer}, or
2112 @code{set-buffer}. @xref{Current Buffer}.
2114 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
2115 This command attempts to display @var{buffer-or-name} in the selected
2116 window and make it the current buffer. It is often used interactively
2117 (as the binding of @kbd{C-x b}), as well as in Lisp programs. The
2118 return value is the buffer switched to.
2120 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2121 returned by @code{other-buffer} (@pxref{Buffer List}). If
2122 @var{buffer-or-name} is a string that is not the name of any existing
2123 buffer, this function creates a new buffer with that name; the new
2124 buffer's major mode is determined by the variable @code{major-mode}
2125 (@pxref{Major Modes}).
2127 Normally, the specified buffer is put at the front of the buffer
2128 list---both the global buffer list and the selected frame's buffer
2129 list (@pxref{Buffer List}). However, this is not done if the
2130 optional argument @var{norecord} is non-@code{nil}.
2132 Sometimes, the selected window may not be suitable for displaying the
2133 buffer. This happens if the selected window is a minibuffer window, or
2134 if the selected window is strongly dedicated to its buffer
2135 (@pxref{Dedicated Windows}). In such cases, the command normally tries
2136 to display the buffer in some other window, by invoking
2137 @code{pop-to-buffer} (see below).
2139 If the optional argument @var{force-same-window} is non-@code{nil} and
2140 the selected window is not suitable for displaying the buffer, this
2141 function always signals an error when called non-interactively. In
2142 interactive use, if the selected window is a minibuffer window, this
2143 function will try to use some other window instead. If the selected
2144 window is strongly dedicated to its buffer, the option
2145 @code{switch-to-buffer-in-dedicated-window} described next can be used
2149 @defopt switch-to-buffer-in-dedicated-window
2150 This option, if non-@code{nil}, allows @code{switch-to-buffer} to
2151 proceed when called interactively and the selected window is strongly
2152 dedicated to its buffer.
2154 The following values are respected:
2158 Disallows switching and signals an error as in non-interactive use.
2161 Prompts the user whether to allow switching.
2164 Invokes @code{pop-to-buffer} to proceed.
2167 Marks the selected window as non-dedicated and proceeds.
2170 This option does not affect non-interactive calls of
2171 @code{switch-to-buffer}.
2174 By default, @code{switch-to-buffer} tries to preserve
2175 @code{window-point}. This behavior can be tuned using the following
2178 @defopt switch-to-buffer-preserve-window-point
2179 If this variable is @code{nil}, @code{switch-to-buffer} displays the
2180 buffer specified by @var{buffer-or-name} at the position of that
2181 buffer's @code{point}. If this variable is @code{already-displayed}, it
2182 tries to display the buffer at its previous position in the selected
2183 window, provided the buffer is currently displayed in some other window
2184 on any visible or iconified frame. If this variable is @code{t},
2185 @code{switch-to-buffer} unconditionally tries to display the buffer at
2186 its previous position in the selected window.
2188 This variable is ignored if the buffer is already displayed in the
2189 selected window or never appeared in it before, or if
2190 @code{switch-to-buffer} calls @code{pop-to-buffer} to display the
2194 The next two commands are similar to @code{switch-to-buffer}, except for
2195 the described features.
2197 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
2198 This function displays the buffer specified by @var{buffer-or-name} in
2199 some window other than the selected window. It uses the function
2200 @code{pop-to-buffer} internally (see below).
2202 If the selected window already displays the specified buffer, it
2203 continues to do so, but another window is nonetheless found to display
2206 The @var{buffer-or-name} and @var{norecord} arguments have the same
2207 meanings as in @code{switch-to-buffer}.
2210 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
2211 This function displays the buffer specified by @var{buffer-or-name} in a
2212 new frame. It uses the function @code{pop-to-buffer} internally (see
2215 If the specified buffer is already displayed in another window, in any
2216 frame on the current terminal, this switches to that window instead of
2217 creating a new frame. However, the selected window is never used for
2220 The @var{buffer-or-name} and @var{norecord} arguments have the same
2221 meanings as in @code{switch-to-buffer}.
2224 The above commands use the function @code{pop-to-buffer}, which
2225 flexibly displays a buffer in some window and selects that window for
2226 editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for
2227 displaying the buffer. Hence, all the variables affecting
2228 @code{display-buffer} will affect it as well. @xref{Choosing Window},
2229 for the documentation of @code{display-buffer}.
2231 @deffn Command pop-to-buffer buffer-or-name &optional action norecord
2232 This function makes @var{buffer-or-name} the current buffer and
2233 displays it in some window, preferably not the window currently
2234 selected. It then selects the displaying window. If that window is
2235 on a different graphical frame, that frame is given input focus if
2236 possible (@pxref{Input Focus}). The return value is the buffer that
2239 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2240 returned by @code{other-buffer} (@pxref{Buffer List}). If
2241 @var{buffer-or-name} is a string that is not the name of any existing
2242 buffer, this function creates a new buffer with that name; the new
2243 buffer's major mode is determined by the variable @code{major-mode}
2244 (@pxref{Major Modes}).
2246 If @var{action} is non-@code{nil}, it should be a display action to
2247 pass to @code{display-buffer} (@pxref{Choosing Window}).
2248 Alternatively, a non-@code{nil}, non-list value means to pop to a
2249 window other than the selected one---even if the buffer is already
2250 displayed in the selected window.
2252 Like @code{switch-to-buffer}, this function updates the buffer list
2253 unless @var{norecord} is non-@code{nil}.
2257 @node Choosing Window
2258 @section Choosing a Window for Display
2260 The command @code{display-buffer} flexibly chooses a window for
2261 display, and displays a specified buffer in that window. It can be
2262 called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
2263 used as a subroutine by many functions and commands, including
2264 @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
2267 @cindex display action
2268 @cindex action function, for @code{display-buffer}
2269 @cindex action alist, for @code{display-buffer}
2270 This command performs several complex steps to find a window to
2271 display in. These steps are described by means of @dfn{display
2272 actions}, which have the form @code{(@var{function} . @var{alist})}.
2273 Here, @var{function} is either a function or a list of functions,
2274 which we refer to as @dfn{action functions}; @var{alist} is an
2275 association list, which we refer to as an @dfn{action alist}.
2277 An action function accepts two arguments: the buffer to display and
2278 an action alist. It attempts to display the buffer in some window,
2279 picking or creating a window according to its own criteria. If
2280 successful, it returns the window; otherwise, it returns @code{nil}.
2281 @xref{Display Action Functions}, for a list of predefined action
2284 @code{display-buffer} works by combining display actions from
2285 several sources, and calling the action functions in turn, until one
2286 of them manages to display the buffer and returns a non-@code{nil}
2289 @deffn Command display-buffer buffer-or-name &optional action frame
2290 This command makes @var{buffer-or-name} appear in some window, without
2291 selecting the window or making the buffer current. The argument
2292 @var{buffer-or-name} must be a buffer or the name of an existing
2293 buffer. The return value is the window chosen to display the buffer.
2295 The optional argument @var{action}, if non-@code{nil}, should normally
2296 be a display action (described above). @code{display-buffer} builds a
2297 list of action functions and an action alist, by consolidating display
2298 actions from the following sources (in order):
2302 The variable @code{display-buffer-overriding-action}.
2305 The user option @code{display-buffer-alist}.
2308 The @var{action} argument.
2311 The user option @code{display-buffer-base-action}.
2314 The constant @code{display-buffer-fallback-action}.
2318 Each action function is called in turn, passing the buffer as the
2319 first argument and the combined action alist as the second argument,
2320 until one of the functions returns non-@code{nil}. The caller can
2321 pass @code{(allow-no-window . t)} as an element of the action alist to
2322 indicate its readiness to handle the case of not displaying the
2325 The argument @var{action} can also have a non-@code{nil}, non-list
2326 value. This has the special meaning that the buffer should be
2327 displayed in a window other than the selected one, even if the
2328 selected window is already displaying it. If called interactively
2329 with a prefix argument, @var{action} is @code{t}.
2331 The optional argument @var{frame}, if non-@code{nil}, specifies which
2332 frames to check when deciding whether the buffer is already displayed.
2333 It is equivalent to adding an element @code{(reusable-frames
2334 . @var{frame})} to the action alist of @var{action}. @xref{Display
2338 @defvar display-buffer-overriding-action
2339 The value of this variable should be a display action, which is
2340 treated with the highest priority by @code{display-buffer}. The
2341 default value is empty, i.e., @code{(nil . nil)}.
2344 @defopt display-buffer-alist
2345 The value of this option is an alist mapping conditions to display
2346 actions. Each condition may be either a regular expression matching a
2347 buffer name or a function that takes two arguments: a buffer name and
2348 the @var{action} argument passed to @code{display-buffer}. If the name
2349 of the buffer passed to @code{display-buffer} either matches a regular
2350 expression in this alist or the function specified by a condition
2351 returns non-@code{nil}, then @code{display-buffer} uses the
2352 corresponding display action to display the buffer.
2355 @defopt display-buffer-base-action
2356 The value of this option should be a display action. This option can
2357 be used to define a standard display action for calls to
2358 @code{display-buffer}.
2361 @defvr Constant display-buffer-fallback-action
2362 This display action specifies the fallback behavior for
2363 @code{display-buffer} if no other display actions are given.
2367 @node Display Action Functions
2368 @section Action Functions for @code{display-buffer}
2370 The following basic action functions are defined in Emacs. Each of
2371 these functions takes two arguments: @var{buffer}, the buffer to
2372 display, and @var{alist}, an action alist. Each action function
2373 returns the window if it succeeds, and @code{nil} if it fails.
2375 @defun display-buffer-same-window buffer alist
2376 This function tries to display @var{buffer} in the selected window.
2377 It fails if the selected window is a minibuffer window or is dedicated
2378 to another buffer (@pxref{Dedicated Windows}). It also fails if
2379 @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
2382 @defun display-buffer-reuse-window buffer alist
2383 This function tries to display @var{buffer} by finding a window
2384 that is already displaying it.
2386 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2387 the selected window is not eligible for reuse. If @var{alist}
2388 contains a @code{reusable-frames} entry, its value determines which
2389 frames to search for a reusable window:
2393 @code{nil} means consider windows on the selected frame.
2394 (Actually, the last non-minibuffer frame.)
2396 @code{t} means consider windows on all frames.
2398 @code{visible} means consider windows on all visible frames.
2400 0 means consider windows on all visible or iconified frames.
2402 A frame means consider windows on that frame only.
2405 Note that these meanings differ slightly from those of the
2406 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
2409 If @var{alist} contains no @code{reusable-frames} entry, this function
2410 normally searches just the selected frame; however, if the variable
2411 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
2412 current terminal. @xref{Choosing Window Options}.
2414 If this function chooses a window on another frame, it makes that frame
2415 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
2416 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
2419 @defun display-buffer-reuse-mode-window buffer alist
2420 This function tries to display @var{buffer} by finding a window
2421 that is displaying a buffer in a given mode.
2423 If @var{alist} contains a @code{mode} entry, its value is a major mode
2424 (a symbol) or a list of major modes. If @var{alist} contains no
2425 @code{mode} entry, the current major mode of @var{buffer} is used. A
2426 window is a candidate if it displays a buffer that derives from one of
2429 The behavior is also controlled by entries for
2430 @code{inhibit-same-window}, @code{reusable-frames} and
2431 @code{inhibit-switch-frame} as is done in the function
2432 @code{display-buffer-reuse-window}.
2436 @defun display-buffer-pop-up-frame buffer alist
2437 This function creates a new frame, and displays the buffer in that
2438 frame's window. It actually performs the frame creation by calling
2439 the function specified in @code{pop-up-frame-function}
2440 (@pxref{Choosing Window Options}). If @var{alist} contains a
2441 @code{pop-up-frame-parameters} entry, the associated value
2442 is added to the newly created frame's parameters.
2445 @defun display-buffer-use-some-frame buffer alist
2446 This function tries to display @var{buffer} by trying to find a
2447 frame that meets a predicate (by default any frame other than the
2450 If this function chooses a window on another frame, it makes that frame
2451 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
2452 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
2454 If @var{alist} has a non-@code{nil} @code{frame-predicate} entry, its
2455 value is a function taking one argument (a frame), returning
2456 non-@code{nil} if the frame is a candidate; this function replaces the
2459 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2460 the selected window is used; thus if the selected frame has a single
2461 window, it is not used.
2464 @defun display-buffer-pop-up-window buffer alist
2465 This function tries to display @var{buffer} by splitting the largest
2466 or least recently-used window (typically one on the selected frame).
2467 It actually performs the split by calling the function specified in
2468 @code{split-window-preferred-function} (@pxref{Choosing Window
2471 The size of the new window can be adjusted by supplying
2472 @code{window-height} and @code{window-width} entries in @var{alist}. To
2473 adjust the window's height, use an entry whose @sc{car} is
2474 @code{window-height} and whose @sc{cdr} is one of:
2478 @code{nil} means to leave the height of the new window alone.
2481 A number specifies the desired height of the new window. An integer
2482 specifies the number of lines of the window. A floating-point
2483 number gives the fraction of the window's height with respect to the
2484 height of the frame's root window.
2487 If the @sc{cdr} specifies a function, that function is called with one
2488 argument: the new window. The function is supposed to adjust the
2489 height of the window; its return value is ignored. Suitable functions
2490 are @code{shrink-window-if-larger-than-buffer} and
2491 @code{fit-window-to-buffer}, see @ref{Resizing Windows}.
2494 To adjust the window's width, use an entry whose @sc{car} is
2495 @code{window-width} and whose @sc{cdr} is one of:
2499 @code{nil} means to leave the width of the new window alone.
2502 A number specifies the desired width of the new window. An integer
2503 specifies the number of columns of the window. A floating-point
2504 number gives the fraction of the window's width with respect to the
2505 width of the frame's root window.
2508 If the @sc{cdr} specifies a function, that function is called with one
2509 argument: the new window. The function is supposed to adjust the width
2510 of the window; its return value is ignored.
2513 If @var{alist} contains a @code{preserve-size} entry, Emacs will try to
2514 preserve the size of the new window during future resize operations
2515 (@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a
2516 cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width
2517 of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve
2518 the height of the window.
2520 This function can fail if no window splitting can be performed for some
2521 reason (e.g., if the selected frame has an @code{unsplittable} frame
2522 parameter; @pxref{Buffer Parameters}).
2525 @defun display-buffer-below-selected buffer alist
2526 This function tries to display @var{buffer} in a window below the
2527 selected window. If there is a window below the selected one and that
2528 window already displays @var{buffer}, it reuses that window.
2530 If there is no such window, this function tries to create a new window
2531 by splitting the selected one and display @var{buffer} there. It will
2532 also adjust that window's size provided @var{alist} contains a suitable
2533 @code{window-height} or @code{window-width} entry, see above.
2535 If splitting the selected window fails and there is a non-dedicated
2536 window below the selected one showing some other buffer, it uses that
2537 window for showing @var{buffer}.
2540 @defun display-buffer-in-previous-window buffer alist
2541 This function tries to display @var{buffer} in a window previously
2542 showing it. If @var{alist} has a non-@code{nil}
2543 @code{inhibit-same-window} entry, the selected window is not eligible
2544 for reuse. If @var{alist} contains a @code{reusable-frames} entry, its
2545 value determines which frames to search for a suitable window as with
2546 @code{display-buffer-reuse-window}.
2548 If @var{alist} has a @code{previous-window} entry, the window
2549 specified by that entry will override any other window found by the
2550 methods above, even if that window never showed @var{buffer} before.
2553 @defun display-buffer-at-bottom buffer alist
2554 This function tries to display @var{buffer} in a window at the bottom
2555 of the selected frame.
2557 This either splits the window at the bottom of the frame or the
2558 frame's root window, or reuses an existing window at the bottom of the
2562 @defun display-buffer-use-some-window buffer alist
2563 This function tries to display @var{buffer} by choosing an existing
2564 window and displaying the buffer in that window. It can fail if all
2565 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
2568 @defun display-buffer-no-window buffer alist
2569 If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then
2570 this function does not display @code{buffer}. This allows you to
2571 override the default action and avoid displaying the buffer. It is
2572 assumed that when the caller specifies a non-@code{nil}
2573 @code{allow-no-window} value it can handle a @code{nil} value returned
2574 from @code{display-buffer} in this case.
2577 To illustrate the use of action functions, consider the following
2583 (get-buffer-create "*foo*")
2584 '((display-buffer-reuse-window
2585 display-buffer-pop-up-window
2586 display-buffer-pop-up-frame)
2587 (reusable-frames . 0)
2588 (window-height . 10) (window-width . 40)))
2593 Evaluating the form above will cause @code{display-buffer} to proceed as
2594 follows: If a buffer called *foo* already appears on a visible or
2595 iconified frame, it will reuse its window. Otherwise, it will try to
2596 pop up a new window or, if that is impossible, a new frame and show the
2597 buffer there. If all these steps fail, it will proceed using whatever
2598 @code{display-buffer-base-action} and
2599 @code{display-buffer-fallback-action} prescribe.
2601 Furthermore, @code{display-buffer} will try to adjust a reused window
2602 (provided *foo* was put by @code{display-buffer} there before) or a
2603 popped-up window as follows: If the window is part of a vertical
2604 combination, it will set its height to ten lines. Note that if, instead
2605 of the number 10, we specified the function
2606 @code{fit-window-to-buffer}, @code{display-buffer} would come up with a
2607 one-line window to fit the empty buffer. If the window is part of a
2608 horizontal combination, it sets its width to 40 columns. Whether a new
2609 window is vertically or horizontally combined depends on the shape of
2610 the window split and the values of
2611 @code{split-window-preferred-function}, @code{split-height-threshold}
2612 and @code{split-width-threshold} (@pxref{Choosing Window Options}).
2614 Now suppose we combine this call with a preexisting setup for
2615 @code{display-buffer-alist} as follows.
2619 (let ((display-buffer-alist
2622 (display-buffer-reuse-window display-buffer-below-selected)
2624 (window-height . 5))
2625 display-buffer-alist)))
2627 (get-buffer-create "*foo*")
2628 '((display-buffer-reuse-window
2629 display-buffer-pop-up-window
2630 display-buffer-pop-up-frame)
2631 (reusable-frames . 0)
2632 (window-height . 10) (window-width . 40))))
2637 This form will have @code{display-buffer} first try reusing a window
2638 that shows *foo* on the selected frame. If there's no such window, it
2639 will try to split the selected window or, if that is impossible, use the
2640 window below the selected window.
2642 If there's no window below the selected one, or the window below the
2643 selected one is dedicated to its buffer, @code{display-buffer} will
2644 proceed as described in the previous example. Note, however, that when
2645 it tries to adjust the height of any reused or popped-up window, it will
2646 in any case try to set its number of lines to 5 since that value
2647 overrides the corresponding specification in the @var{action} argument
2648 of @code{display-buffer}.
2651 @node Choosing Window Options
2652 @section Additional Options for Displaying Buffers
2654 The behavior of the standard display actions of @code{display-buffer}
2655 (@pxref{Choosing Window}) can be modified by a variety of user
2658 @defopt pop-up-windows
2659 If the value of this variable is non-@code{nil}, @code{display-buffer}
2660 is allowed to split an existing window to make a new window for
2661 displaying in. This is the default.
2663 This variable is provided mainly for backward compatibility. It is
2664 obeyed by @code{display-buffer} via a special mechanism in
2665 @code{display-buffer-fallback-action}, which only calls the action
2666 function @code{display-buffer-pop-up-window} (@pxref{Display Action
2667 Functions}) when the value is @code{nil}. It is not consulted by
2668 @code{display-buffer-pop-up-window} itself, which the user may specify
2669 directly in @code{display-buffer-alist} etc.
2672 @defopt split-window-preferred-function
2673 This variable specifies a function for splitting a window, in order to
2674 make a new window for displaying a buffer. It is used by the
2675 @code{display-buffer-pop-up-window} action function to actually split
2676 the window (@pxref{Display Action Functions}).
2678 The default value is @code{split-window-sensibly}, which is documented
2679 below. The value must be a function that takes one argument, a window,
2680 and return either a new window (which will be used to display the
2681 desired buffer) or @code{nil} (which means the splitting failed).
2684 @defun split-window-sensibly &optional window
2685 This function tries to split @var{window}, and return the newly created
2686 window. If @var{window} cannot be split, it returns @code{nil}. If
2687 @var{window} is omitted or @code{nil}, it defaults to the selected
2690 This function obeys the usual rules that determine when a window may
2691 be split (@pxref{Splitting Windows}). It first tries to split by
2692 placing the new window below, subject to the restriction imposed by
2693 @code{split-height-threshold} (see below), in addition to any other
2694 restrictions. If that fails, it tries to split by placing the new
2695 window to the right, subject to @code{split-width-threshold} (see
2696 below). If that fails, and the window is the only window on its
2697 frame, this function again tries to split and place the new window
2698 below, disregarding @code{split-height-threshold}. If this fails as
2699 well, this function gives up and returns @code{nil}.
2702 @defopt split-height-threshold
2703 This variable, used by @code{split-window-sensibly}, specifies whether
2704 to split the window placing the new window below. If it is an
2705 integer, that means to split only if the original window has at least
2706 that many lines. If it is @code{nil}, that means not to split this
2710 @defopt split-width-threshold
2711 This variable, used by @code{split-window-sensibly}, specifies whether
2712 to split the window placing the new window to the right. If the value
2713 is an integer, that means to split only if the original window has at
2714 least that many columns. If the value is @code{nil}, that means not
2718 @defopt even-window-sizes
2719 This variable, if non-@code{nil}, causes @code{display-buffer} to even
2720 window sizes whenever it reuses an existing window and that window is
2721 adjacent to the selected one.
2723 If its value is @code{width-only}, sizes are evened only if the reused
2724 window is on the left or right of the selected one and the selected
2725 window is wider than the reused one. If its value is @code{height-only}
2726 sizes are evened only if the reused window is above or beneath the
2727 selected window and the selected window is higher than the reused one.
2728 Any other non-@code{nil} value means to even sizes in any of these cases
2729 provided the selected window is larger than the reused one in the sense
2730 of their combination.
2733 @defopt pop-up-frames
2734 If the value of this variable is non-@code{nil}, that means
2735 @code{display-buffer} may display buffers by making new frames. The
2736 default is @code{nil}.
2738 A non-@code{nil} value also means that when @code{display-buffer} is
2739 looking for a window already displaying @var{buffer-or-name}, it can
2740 search any visible or iconified frame, not just the selected frame.
2742 This variable is provided mainly for backward compatibility. It is
2743 obeyed by @code{display-buffer} via a special mechanism in
2744 @code{display-buffer-fallback-action}, which calls the action function
2745 @code{display-buffer-pop-up-frame} (@pxref{Display Action Functions})
2746 if the value is non-@code{nil}. (This is done before attempting to
2747 split a window.) This variable is not consulted by
2748 @code{display-buffer-pop-up-frame} itself, which the user may specify
2749 directly in @code{display-buffer-alist} etc.
2752 @defopt pop-up-frame-function
2753 This variable specifies a function for creating a new frame, in order
2754 to make a new window for displaying a buffer. It is used by the
2755 @code{display-buffer-pop-up-frame} action function (@pxref{Display
2758 The value should be a function that takes no arguments and returns a
2759 frame, or @code{nil} if no frame could be created. The default value
2760 is a function that creates a frame using the parameters specified by
2761 @code{pop-up-frame-alist} (see below).
2764 @defopt pop-up-frame-alist
2765 This variable holds an alist of frame parameters (@pxref{Frame
2766 Parameters}), which is used by the default function in
2767 @code{pop-up-frame-function} to make a new frame. The default is
2771 @defopt same-window-buffer-names
2772 A list of buffer names for buffers that should be displayed in the
2773 selected window. If a buffer's name is in this list,
2774 @code{display-buffer} handles the buffer by showing it in the selected
2778 @defopt same-window-regexps
2779 A list of regular expressions that specify buffers that should be
2780 displayed in the selected window. If the buffer's name matches any of
2781 the regular expressions in this list, @code{display-buffer} handles the
2782 buffer by showing it in the selected window.
2785 @defun same-window-p buffer-name
2786 This function returns @code{t} if displaying a buffer
2787 named @var{buffer-name} with @code{display-buffer} would
2788 put it in the selected window.
2791 @node Window History
2792 @section Window History
2793 @cindex window history
2795 Each window remembers in a list the buffers it has previously displayed,
2796 and the order in which these buffers were removed from it. This history
2797 is used, for example, by @code{replace-buffer-in-windows}
2798 (@pxref{Buffers and Windows}). The list is automatically maintained by
2799 Emacs, but you can use the following functions to explicitly inspect or
2802 @defun window-prev-buffers &optional window
2803 This function returns a list specifying the previous contents of
2804 @var{window}. The optional argument @var{window} should be a live
2805 window and defaults to the selected one.
2807 Each list element has the form @code{(@var{buffer} @var{window-start}
2808 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
2809 the window, @var{window-start} is the window start position
2810 (@pxref{Window Start and End}) when that buffer was last shown, and
2811 @var{window-pos} is the point position (@pxref{Window Point}) when
2812 that buffer was last shown in @var{window}.
2814 The list is ordered so that earlier elements correspond to more
2815 recently-shown buffers, and the first element usually corresponds to the
2816 buffer most recently removed from the window.
2819 @defun set-window-prev-buffers window prev-buffers
2820 This function sets @var{window}'s previous buffers to the value of
2821 @var{prev-buffers}. The argument @var{window} must be a live window
2822 and defaults to the selected one. The argument @var{prev-buffers}
2823 should be a list of the same form as that returned by
2824 @code{window-prev-buffers}.
2827 In addition, each buffer maintains a list of @dfn{next buffers}, which
2828 is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
2829 below). This list is mainly used by @code{switch-to-prev-buffer} and
2830 @code{switch-to-next-buffer} for choosing buffers to switch to.
2832 @defun window-next-buffers &optional window
2833 This function returns the list of buffers recently re-shown in
2834 @var{window} via @code{switch-to-prev-buffer}. The @var{window}
2835 argument must denote a live window or @code{nil} (meaning the selected
2839 @defun set-window-next-buffers window next-buffers
2840 This function sets the next buffer list of @var{window} to
2841 @var{next-buffers}. The @var{window} argument should be a live window
2842 or @code{nil} (meaning the selected window). The argument
2843 @var{next-buffers} should be a list of buffers.
2846 The following commands can be used to cycle through the global buffer
2847 list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
2848 they cycle according to the specified window's history list, rather
2849 than the global buffer list. In addition, they restore
2850 window-specific window start and point positions, and may show a
2851 buffer even if it is already shown in another window. The
2852 @code{switch-to-prev-buffer} command, in particular, is used by
2853 @code{replace-buffer-in-windows}, @code{bury-buffer} and
2854 @code{quit-window} to find a replacement buffer for a window.
2856 @deffn Command switch-to-prev-buffer &optional window bury-or-kill
2857 This command displays the previous buffer in @var{window}. The
2858 argument @var{window} should be a live window or @code{nil} (meaning
2859 the selected window). If the optional argument @var{bury-or-kill} is
2860 non-@code{nil}, this means that the buffer currently shown in
2861 @var{window} is about to be buried or killed and consequently should
2862 not be switched to in future invocations of this command.
2864 The previous buffer is usually the buffer shown before the buffer
2865 currently shown in @var{window}. However, a buffer that has been buried
2866 or killed, or has been already shown by a recent invocation of
2867 @code{switch-to-prev-buffer}, does not qualify as previous buffer.
2869 If repeated invocations of this command have already shown all buffers
2870 previously shown in @var{window}, further invocations will show buffers
2871 from the buffer list of the frame @var{window} appears on (@pxref{Buffer
2872 List}), trying to skip buffers that are already shown in another window
2876 @deffn Command switch-to-next-buffer &optional window
2877 This command switches to the next buffer in @var{window}, thus undoing
2878 the effect of the last @code{switch-to-prev-buffer} command in
2879 @var{window}. The argument @var{window} must be a live window and
2880 defaults to the selected one.
2882 If there is no recent invocation of @code{switch-to-prev-buffer} that
2883 can be undone, this function tries to show a buffer from the buffer list
2884 of the frame @var{window} appears on (@pxref{Buffer List}).
2887 By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
2888 can switch to a buffer that is already shown in another window on the
2889 same frame. The following option can be used to override this behavior.
2891 @defopt switch-to-visible-buffer
2892 If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
2893 @code{switch-to-next-buffer} may switch to a buffer that is already
2894 visible on the same frame, provided the buffer was shown in the
2895 relevant window before. If it is @code{nil},
2896 @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always
2897 try to avoid switching to a buffer that is already visible in another
2898 window on the same frame. The default is @code{t}.
2902 @node Dedicated Windows
2903 @section Dedicated Windows
2904 @cindex dedicated window
2906 Functions for displaying a buffer can be told to not use specific
2907 windows by marking these windows as @dfn{dedicated} to their buffers.
2908 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
2909 window for displaying another buffer in it. @code{get-lru-window} and
2910 @code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not
2911 consider dedicated windows as candidates when their @var{dedicated}
2912 argument is non-@code{nil}. The behavior of @code{set-window-buffer}
2913 (@pxref{Buffers and Windows}) with respect to dedicated windows is
2914 slightly different, see below.
2916 Functions supposed to remove a buffer from a window or a window from
2917 a frame can behave specially when a window they operate on is dedicated.
2918 We will distinguish three basic cases, namely where (1) the window is
2919 not the only window on its frame, (2) the window is the only window on
2920 its frame but there are other frames on the same terminal left, and (3)
2921 the window is the only window on the only frame on the same terminal.
2923 In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
2924 handles case (2) by deleting the associated frame and case (3) by
2925 showing another buffer in that frame's only window. The function
2926 @code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
2927 called when a buffer gets killed, deletes the window in case (1) and
2928 behaves like @code{delete-windows-on} otherwise.
2929 @c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
2931 When @code{bury-buffer} (@pxref{Buffer List}) operates on the
2932 selected window (which shows the buffer that shall be buried), it
2933 handles case (2) by calling @code{frame-auto-hide-function}
2934 (@pxref{Quitting Windows}) to deal with the selected frame. The other
2935 two cases are handled as with @code{replace-buffer-in-windows}.
2937 @defun window-dedicated-p &optional window
2938 This function returns non-@code{nil} if @var{window} is dedicated to its
2939 buffer and @code{nil} otherwise. More precisely, the return value is
2940 the value assigned by the last call of @code{set-window-dedicated-p} for
2941 @var{window}, or @code{nil} if that function was never called with
2942 @var{window} as its argument. The default for @var{window} is the
2946 @defun set-window-dedicated-p window flag
2947 This function marks @var{window} as dedicated to its buffer if
2948 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
2950 As a special case, if @var{flag} is @code{t}, @var{window} becomes
2951 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
2952 signals an error when the window it acts upon is strongly dedicated to
2953 its buffer and does not already display the buffer it is asked to
2954 display. Other functions do not treat @code{t} differently from any
2955 non-@code{nil} value.
2959 @node Quitting Windows
2960 @section Quitting Windows
2962 When you want to get rid of a window used for displaying a buffer, you
2963 can call @code{delete-window} or @code{delete-windows-on}
2964 (@pxref{Deleting Windows}) to remove that window from its frame. If the
2965 buffer is shown on a separate frame, you might want to call
2966 @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
2967 hand, a window has been reused for displaying the buffer, you might
2968 prefer showing the buffer previously shown in that window, by calling the
2969 function @code{switch-to-prev-buffer} (@pxref{Window History}).
2970 Finally, you might want to either bury (@pxref{Buffer List}) or kill
2971 (@pxref{Killing Buffers}) the window's buffer.
2973 The following command uses information on how the window for
2974 displaying the buffer was obtained in the first place, thus attempting
2975 to automate the above decisions for you.
2977 @deffn Command quit-window &optional kill window
2978 This command quits @var{window} and buries its buffer. The argument
2979 @var{window} must be a live window and defaults to the selected one.
2980 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
2981 instead of burying it. It calls the function @code{quit-restore-window}
2982 described next to deal with the window and its buffer.
2985 @defun quit-restore-window &optional window bury-or-kill
2986 This function tries to restore the state of @var{window} that existed
2987 before its buffer was displayed in it. The optional argument
2988 @var{window} must be a live window and defaults to the selected one.
2990 If @var{window} was created specially for displaying its buffer, this
2991 function deletes @var{window} provided its frame contains at least one
2992 other live window. If @var{window} is the only window on its frame and
2993 there are other frames on the frame's terminal, the value of the
2994 optional argument @var{bury-or-kill} determines how to proceed with the
2995 window. If @var{bury-or-kill} equals @code{kill}, the frame is deleted
2996 unconditionally. Otherwise, the fate of the frame is determined by
2997 calling @code{frame-auto-hide-function} (see below) with that frame as
3000 Otherwise, this function tries to redisplay the buffer previously shown
3001 in @var{window}. It also tries to restore the window start
3002 (@pxref{Window Start and End}) and point (@pxref{Window Point})
3003 positions of the previously shown buffer. If, in addition,
3004 @var{window}'s buffer was temporarily resized, this function will also
3005 try to restore the original height of @var{window}.
3007 The cases described so far require that the buffer shown in @var{window}
3008 is still the buffer displayed by the last buffer display function for
3009 this window. If another buffer has been shown in the meantime, or the
3010 buffer previously shown no longer exists, this function calls
3011 @code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
3014 The optional argument @var{bury-or-kill} specifies how to deal with
3015 @var{window}'s buffer. The following values are handled:
3019 This means to not deal with the buffer in any particular way. As a
3020 consequence, if @var{window} is not deleted, invoking
3021 @code{switch-to-prev-buffer} will usually show the buffer again.
3024 This means that if @var{window} is not deleted, its buffer is moved to
3025 the end of @var{window}'s list of previous buffers, so it's less likely
3026 that a future invocation of @code{switch-to-prev-buffer} will switch to
3027 it. Also, it moves the buffer to the end of the frame's buffer list.
3030 This means that if @var{window} is not deleted, its buffer is removed
3031 from @var{window}'s list of previous buffers. Also, it moves the buffer
3032 to the end of the frame's buffer list. This value provides the most
3033 reliable remedy to not have @code{switch-to-prev-buffer} switch to this
3034 buffer again without killing the buffer.
3037 This means to kill @var{window}'s buffer.
3040 @code{quit-restore-window} bases its decisions on information stored in
3041 @var{window}'s @code{quit-restore} window parameter (@pxref{Window
3042 Parameters}), and resets that parameter to @code{nil} after it's done.
3045 The following option specifies how to deal with a frame containing just
3046 one window that should be either quit, or whose buffer should be buried.
3048 @defopt frame-auto-hide-function
3049 The function specified by this option is called to automatically hide
3050 frames. This function is called with one argument---a frame.
3052 The function specified here is called by @code{bury-buffer}
3053 (@pxref{Buffer List}) when the selected window is dedicated and shows
3054 the buffer to bury. It is also called by @code{quit-restore-window}
3055 (see above) when the frame of the window to quit has been specially
3056 created for displaying that window's buffer and the buffer is not
3059 The default is to call @code{iconify-frame} (@pxref{Visibility of
3060 Frames}). Alternatively, you may specify either @code{delete-frame}
3061 (@pxref{Deleting Frames}) to remove the frame from its display,
3062 @code{ignore} to leave the frame unchanged, or any other function that
3063 can take a frame as its sole argument.
3065 Note that the function specified by this option is called only if the
3066 specified frame contains just one live window and there is at least one
3067 other frame on the same terminal.
3072 @section Windows and Point
3073 @cindex window position
3074 @cindex window point
3075 @cindex position in window
3076 @cindex point in window
3078 Each window has its own value of point (@pxref{Point}), independent of
3079 the value of point in other windows displaying the same buffer. This
3080 makes it useful to have multiple windows showing one buffer.
3084 The window point is established when a window is first created; it is
3085 initialized from the buffer's point, or from the window point of another
3086 window opened on the buffer if such a window exists.
3089 Selecting a window sets the value of point in its buffer from the
3090 window's value of point. Conversely, deselecting a window sets the
3091 window's value of point from that of the buffer. Thus, when you switch
3092 between windows that display a given buffer, the point value for the
3093 selected window is in effect in the buffer, while the point values for
3094 the other windows are stored in those windows.
3097 As long as the selected window displays the current buffer, the window's
3098 point and the buffer's point always move together; they remain equal.
3102 As far as the user is concerned, point is where the cursor is, and
3103 when the user switches to another buffer, the cursor jumps to the
3104 position of point in that buffer.
3106 @defun window-point &optional window
3107 This function returns the current position of point in @var{window}.
3108 For a nonselected window, this is the value point would have (in that
3109 window's buffer) if that window were selected. The default for
3110 @var{window} is the selected window.
3112 When @var{window} is the selected window, the value returned is the
3113 value of point in that window's buffer. Strictly speaking, it would be
3114 more correct to return the top-level value of point, outside of any
3115 @code{save-excursion} forms. But that value is hard to find.
3118 @defun set-window-point window position
3119 This function positions point in @var{window} at position
3120 @var{position} in @var{window}'s buffer. It returns @var{position}.
3122 If @var{window} is selected, this simply does @code{goto-char} in
3123 @var{window}'s buffer.
3126 @defvar window-point-insertion-type
3127 This variable specifies the marker insertion type (@pxref{Marker
3128 Insertion Types}) of @code{window-point}. The default is @code{nil},
3129 so @code{window-point} will stay behind text inserted there.
3132 @node Window Start and End
3133 @section The Window Start and End Positions
3134 @cindex window start position
3135 @cindex display-start position
3137 Each window maintains a marker used to keep track of a buffer position
3138 that specifies where in the buffer display should start. This position
3139 is called the @dfn{display-start} position of the window (or just the
3140 @dfn{start}). The character after this position is the one that appears
3141 at the upper left corner of the window. It is usually, but not
3142 inevitably, at the beginning of a text line.
3144 After switching windows or buffers, and in some other cases, if the
3145 window start is in the middle of a line, Emacs adjusts the window
3146 start to the start of a line. This prevents certain operations from
3147 leaving the window start at a meaningless point within a line. This
3148 feature may interfere with testing some Lisp code by executing it
3149 using the commands of Lisp mode, because they trigger this
3150 readjustment. To test such code, put it into a command and bind the
3153 @defun window-start &optional window
3154 @cindex window top line
3155 This function returns the display-start position of window
3156 @var{window}. If @var{window} is @code{nil}, the selected window is
3159 When you create a window, or display a different buffer in it, the
3160 display-start position is set to a display-start position recently used
3161 for the same buffer, or to @code{point-min} if the buffer doesn't have
3164 Redisplay updates the window-start position (if you have not specified
3165 it explicitly since the previous redisplay)---to make sure point appears
3166 on the screen. Nothing except redisplay automatically changes the
3167 window-start position; if you move point, do not expect the window-start
3168 position to change in response until after the next redisplay.
3171 @defun window-group-start &optional window
3172 @vindex window-group-start-function
3173 This function is like @code{window-start}, except that when
3174 @var{window} is a part of a group of windows (@pxref{Window Group}),
3175 @code{window-group-start} returns the start position of the entire
3176 group. This condition holds when the buffer local variable
3177 @code{window-group-start-function} is set to a function. In this
3178 case, @code{window-group-start} calls the function with the single
3179 argument @var{window}, then returns its result.
3182 @cindex window end position
3183 @defun window-end &optional window update
3184 This function returns the position where display of its buffer ends in
3185 @var{window}. The default for @var{window} is the selected window.
3187 Simply changing the buffer text or moving point does not update the
3188 value that @code{window-end} returns. The value is updated only when
3189 Emacs redisplays and redisplay completes without being preempted.
3191 If the last redisplay of @var{window} was preempted, and did not finish,
3192 Emacs does not know the position of the end of display in that window.
3193 In that case, this function returns @code{nil}.
3195 If @var{update} is non-@code{nil}, @code{window-end} always returns an
3196 up-to-date value for where display ends, based on the current
3197 @code{window-start} value. If a previously saved value of that position
3198 is still valid, @code{window-end} returns that value; otherwise it
3199 computes the correct value by scanning the buffer text.
3201 Even if @var{update} is non-@code{nil}, @code{window-end} does not
3202 attempt to scroll the display if point has moved off the screen, the
3203 way real redisplay would do. It does not alter the
3204 @code{window-start} value. In effect, it reports where the displayed
3205 text will end if scrolling is not required.
3208 @vindex window-group-end-function
3209 @defun window-group-end &optional window update
3210 This function is like @code{window-end}, except that when @var{window}
3211 is a part of a group of windows (@pxref{Window Group}),
3212 @code{window-group-end} returns the end position of the entire group.
3213 This condition holds when the buffer local variable
3214 @code{window-group-end-function} is set to a function. In this case,
3215 @code{window-group-end} calls the function with the two arguments
3216 @var{window} and @var{update}, then returns its result. The argument
3217 @var{update} has the same meaning as in @code{window-end}.
3220 @defun set-window-start window position &optional noforce
3221 This function sets the display-start position of @var{window} to
3222 @var{position} in @var{window}'s buffer. It returns @var{position}.
3224 The display routines insist that the position of point be visible when a
3225 buffer is displayed. Normally, they change the display-start position
3226 (that is, scroll the window) whenever necessary to make point visible.
3227 However, if you specify the start position with this function using
3228 @code{nil} for @var{noforce}, it means you want display to start at
3229 @var{position} even if that would put the location of point off the
3230 screen. If this does place point off screen, the display routines move
3231 point to the left margin on the middle line in the window.
3233 For example, if point @w{is 1} and you set the start of the window
3234 @w{to 37}, the start of the next line, point will be above the top
3235 of the window. The display routines will automatically move point if
3236 it is still 1 when redisplay occurs. Here is an example:
3240 ;; @r{Here is what @samp{foo} looks like before executing}
3241 ;; @r{the @code{set-window-start} expression.}
3245 ---------- Buffer: foo ----------
3246 @point{}This is the contents of buffer foo.
3252 ---------- Buffer: foo ----------
3266 ;; @r{Here is what @samp{foo} looks like after executing}
3267 ;; @r{the @code{set-window-start} expression.}
3268 ---------- Buffer: foo ----------
3274 ---------- Buffer: foo ----------
3278 If @var{noforce} is non-@code{nil}, and @var{position} would place point
3279 off screen at the next redisplay, then redisplay computes a new window-start
3280 position that works well with point, and thus @var{position} is not used.
3283 @vindex set-window-group-start-function
3284 @defun set-window-group-start window position &optional noforce
3285 This function is like @code{set-window-start}, except that when
3286 @var{window} is a part of a group of windows (@pxref{Window Group}),
3287 @code{set-window-group-start} sets the start position of the entire
3288 group. This condition holds when the buffer local variable
3289 @code{set-window-group-start-function} is set to a function. In this
3290 case, @code{set-window-group-start} calls the function with the three
3291 arguments @var{window}, @var{position}, and @var{noforce}, then
3292 returns its result. The arguments @var{position} and @var{noforce} in
3293 this function have the same meaning as in @code{set-window-start}.
3296 @defun pos-visible-in-window-p &optional position window partially
3297 This function returns non-@code{nil} if @var{position} is within the
3298 range of text currently visible on the screen in @var{window}. It
3299 returns @code{nil} if @var{position} is scrolled vertically out of
3300 view. Locations that are partially obscured are not considered
3301 visible unless @var{partially} is non-@code{nil}. The argument
3302 @var{position} defaults to the current position of point in
3303 @var{window}; @var{window} defaults to the selected window. If
3304 @var{position} is @code{t}, that means to check either the first
3305 visible position of the last screen line in @var{window}, or the
3306 end-of-buffer position, whichever comes first.
3308 This function considers only vertical scrolling. If @var{position} is
3309 out of view only because @var{window} has been scrolled horizontally,
3310 @code{pos-visible-in-window-p} returns non-@code{nil} anyway.
3311 @xref{Horizontal Scrolling}.
3313 If @var{position} is visible, @code{pos-visible-in-window-p} returns
3314 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
3315 non-@code{nil}, and the character following @var{position} is fully
3316 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
3317 @var{x} and @var{y} are the pixel coordinates relative to the top left
3318 corner of the window; otherwise it returns an extended list of the form
3319 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
3320 where @var{rtop} and @var{rbot} specify the number of off-window pixels
3321 at the top and bottom of the row at @var{position}, @var{rowh} specifies
3322 the visible height of that row, and @var{vpos} specifies the vertical
3323 position (zero-based row number) of that row.
3329 ;; @r{If point is off the screen now, recenter it now.}
3330 (or (pos-visible-in-window-p
3331 (point) (selected-window))
3337 @vindex pos-visible-in-window-group-p-function
3338 @defun pos-visible-in-window-group-p &optional position window partially
3339 This function is like @code{pos-visible-in-window-p}, except that when
3340 @var{window} is a part of a group of windows (@pxref{Window Group}),
3341 @code{pos-visible-in-window-group-p} tests the visibility of @var{pos}
3342 in the entire group, not just in the single @var{window}. This
3343 condition holds when the buffer local variable
3344 @code{pos-visible-in-window-group-p-function} is set to a function.
3345 In this case @code{pos-visible-in-window-group-p} calls the function
3346 with the three arguments @var{position}, @var{window}, and
3347 @var{partially}, then returns its result. The arguments
3348 @var{position} and @var{partially} have the same meaning as in
3349 @code{pos-visible-in-window-p}.
3352 @defun window-line-height &optional line window
3353 This function returns the height of text line @var{line} in
3354 @var{window}. If @var{line} is one of @code{header-line} or
3355 @code{mode-line}, @code{window-line-height} returns information about
3356 the corresponding line of the window. Otherwise, @var{line} is a text
3357 line number starting from 0. A negative number counts from the end of
3358 the window. The default for @var{line} is the current line in
3359 @var{window}; the default for @var{window} is the selected window.
3361 If the display is not up to date, @code{window-line-height} returns
3362 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
3363 to obtain related information.
3365 If there is no line corresponding to the specified @var{line},
3366 @code{window-line-height} returns @code{nil}. Otherwise, it returns
3367 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
3368 where @var{height} is the height in pixels of the visible part of the
3369 line, @var{vpos} and @var{ypos} are the vertical position in lines and
3370 pixels of the line relative to the top of the first text line, and
3371 @var{offbot} is the number of off-window pixels at the bottom of the
3372 text line. If there are off-window pixels at the top of the (first)
3373 text line, @var{ypos} is negative.
3376 @node Textual Scrolling
3377 @section Textual Scrolling
3378 @cindex textual scrolling
3379 @cindex scrolling textually
3381 @dfn{Textual scrolling} means moving the text up or down through a
3382 window. It works by changing the window's display-start location. It
3383 may also change the value of @code{window-point} to keep point on the
3384 screen (@pxref{Window Point}).
3386 The basic textual scrolling functions are @code{scroll-up} (which
3387 scrolls forward) and @code{scroll-down} (which scrolls backward). In
3388 these function names, ``up'' and ``down'' refer to the direction of
3389 motion of the buffer text relative to the window. Imagine that the
3390 text is written on a long roll of paper and that the scrolling
3391 commands move the paper up and down. Thus, if you are looking at the
3392 middle of a buffer and repeatedly call @code{scroll-down}, you will
3393 eventually see the beginning of the buffer.
3395 Unfortunately, this sometimes causes confusion, because some people
3396 tend to think in terms of the opposite convention: they
3397 imagine the window moving over text that remains in place, so that
3398 ``down'' commands take you to the end of the buffer. This convention
3399 is consistent with fact that such a command is bound to a key named
3400 @key{PageDown} on modern keyboards.
3402 We have not switched to this convention as that is likely to break
3403 existing Emacs Lisp code.
3406 Textual scrolling functions (aside from @code{scroll-other-window})
3407 have unpredictable results if the current buffer is not the one
3408 displayed in the selected window. @xref{Current Buffer}.
3410 If the window contains a row taller than the height of the window
3411 (for example in the presence of a large image), the scroll functions
3412 will adjust the window's vertical scroll position to scroll the
3413 partially visible row. Lisp callers can disable this feature by
3414 binding the variable @code{auto-window-vscroll} to @code{nil}
3415 (@pxref{Vertical Scrolling}).
3417 @deffn Command scroll-up &optional count
3418 This function scrolls forward by @var{count} lines in the selected
3421 If @var{count} is negative, it scrolls backward instead. If
3422 @var{count} is @code{nil} (or omitted), the distance scrolled is
3423 @code{next-screen-context-lines} lines less than the height of the
3426 If the selected window cannot be scrolled any further, this function
3427 signals an error. Otherwise, it returns @code{nil}.
3430 @deffn Command scroll-down &optional count
3431 This function scrolls backward by @var{count} lines in the selected
3434 If @var{count} is negative, it scrolls forward instead. In other
3435 respects, it behaves the same way as @code{scroll-up} does.
3438 @deffn Command scroll-up-command &optional count
3439 This behaves like @code{scroll-up}, except that if the selected window
3440 cannot be scrolled any further and the value of the variable
3441 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3442 end of the buffer instead. If point is already there, it signals an
3446 @deffn Command scroll-down-command &optional count
3447 This behaves like @code{scroll-down}, except that if the selected
3448 window cannot be scrolled any further and the value of the variable
3449 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3450 beginning of the buffer instead. If point is already there, it
3454 @deffn Command scroll-other-window &optional count
3455 This function scrolls the text in another window upward @var{count}
3456 lines. Negative values of @var{count}, or @code{nil}, are handled
3457 as in @code{scroll-up}.
3459 You can specify which buffer to scroll by setting the variable
3460 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
3461 already displayed, @code{scroll-other-window} displays it in some
3464 When the selected window is the minibuffer, the next window is normally
3465 the leftmost one immediately above it. You can specify a different
3466 window to scroll, when the minibuffer is selected, by setting the variable
3467 @code{minibuffer-scroll-window}. This variable has no effect when any
3468 other window is selected. When it is non-@code{nil} and the
3469 minibuffer is selected, it takes precedence over
3470 @code{other-window-scroll-buffer}. @xref{Definition of
3471 minibuffer-scroll-window}.
3473 When the minibuffer is active, it is the next window if the selected
3474 window is the one at the bottom right corner. In this case,
3475 @code{scroll-other-window} attempts to scroll the minibuffer. If the
3476 minibuffer contains just one line, it has nowhere to scroll to, so the
3477 line reappears after the echo area momentarily displays the message
3478 @samp{End of buffer}.
3481 @defvar other-window-scroll-buffer
3482 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
3483 which buffer's window to scroll.
3486 @defopt scroll-margin
3487 This option specifies the size of the scroll margin---a minimum number
3488 of lines between point and the top or bottom of a window. Whenever
3489 point gets within this many lines of the top or bottom of the window,
3490 redisplay scrolls the text automatically (if possible) to move point
3491 out of the margin, closer to the center of the window.
3494 @defopt scroll-conservatively
3495 This variable controls how scrolling is done automatically when point
3496 moves off the screen (or into the scroll margin). If the value is a
3497 positive integer @var{n}, then redisplay scrolls the text up to
3498 @var{n} lines in either direction, if that will bring point back into
3499 proper view. This behavior is called @dfn{conservative scrolling}.
3500 Otherwise, scrolling happens in the usual way, under the control of
3501 other variables such as @code{scroll-up-aggressively} and
3502 @code{scroll-down-aggressively}.
3504 The default value is zero, which means that conservative scrolling
3508 @defopt scroll-down-aggressively
3509 The value of this variable should be either @code{nil} or a fraction
3510 @var{f} between 0 and 1. If it is a fraction, that specifies where on
3511 the screen to put point when scrolling down. More precisely, when a
3512 window scrolls down because point is above the window start, the new
3513 start position is chosen to put point @var{f} part of the window
3514 height from the top. The larger @var{f}, the more aggressive the
3517 A value of @code{nil} is equivalent to .5, since its effect is to center
3518 point. This variable automatically becomes buffer-local when set in any
3522 @defopt scroll-up-aggressively
3523 Likewise, for scrolling up. The value, @var{f}, specifies how far
3524 point should be placed from the bottom of the window; thus, as with
3525 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
3529 This variable is an older variant of @code{scroll-conservatively}.
3530 The difference is that if its value is @var{n}, that permits scrolling
3531 only by precisely @var{n} lines, not a smaller number. This feature
3532 does not work with @code{scroll-margin}. The default value is zero.
3535 @cindex @code{scroll-command} property
3536 @defopt scroll-preserve-screen-position
3537 If this option is @code{t}, whenever a scrolling command moves point
3538 off-window, Emacs tries to adjust point to keep the cursor at its old
3539 vertical position in the window, rather than the window edge.
3541 If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
3542 to keep the cursor at the same vertical position, even if the
3543 scrolling command didn't move point off-window.
3545 This option affects all scroll commands that have a non-@code{nil}
3546 @code{scroll-command} symbol property.
3549 @defopt next-screen-context-lines
3550 The value of this variable is the number of lines of continuity to
3551 retain when scrolling by full screens. For example, @code{scroll-up}
3552 with an argument of @code{nil} scrolls so that this many lines at the
3553 bottom of the window appear instead at the top. The default value is
3557 @defopt scroll-error-top-bottom
3558 If this option is @code{nil} (the default), @code{scroll-up-command}
3559 and @code{scroll-down-command} simply signal an error when no more
3560 scrolling is possible.
3562 If the value is @code{t}, these commands instead move point to the
3563 beginning or end of the buffer (depending on scrolling direction);
3564 only if point is already on that position do they signal an error.
3567 @deffn Command recenter &optional count
3568 @cindex centering point
3569 This function scrolls the text in the selected window so that point is
3570 displayed at a specified vertical position within the window. It does
3571 not move point with respect to the text.
3573 If @var{count} is a non-negative number, that puts the line containing
3574 point @var{count} lines down from the top of the window. If
3575 @var{count} is a negative number, then it counts upward from the
3576 bottom of the window, so that @minus{}1 stands for the last usable
3579 If @var{count} is @code{nil} (or a non-@code{nil} list),
3580 @code{recenter} puts the line containing point in the middle of the
3581 window. If @var{count} is @code{nil}, this function may redraw the
3582 frame, according to the value of @code{recenter-redisplay}.
3584 When @code{recenter} is called interactively, @var{count} is the raw
3585 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
3586 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
3587 @var{count} to 4, which positions the current line four lines from the
3590 With an argument of zero, @code{recenter} positions the current line at
3591 the top of the window. The command @code{recenter-top-bottom} offers
3592 a more convenient way to achieve this.
3595 @vindex recenter-window-group-function
3596 @defun recenter-window-group &optional count
3597 This function is like @code{recenter}, except that when the selected
3598 window is part of a group of windows (@pxref{Window Group}),
3599 @code{recenter-window-group} scrolls the entire group. This condition
3600 holds when the buffer local variable
3601 @code{recenter-window-group-function} is set to a function. In this
3602 case, @code{recenter-window-group} calls the function with the
3603 argument @var{count}, then returns its result. The argument
3604 @var{count} has the same meaning as in @code{recenter}, but with
3605 respect to the entire window group.
3608 @defopt recenter-redisplay
3609 If this variable is non-@code{nil}, calling @code{recenter} with a
3610 @code{nil} argument redraws the frame. The default value is
3611 @code{tty}, which means only redraw the frame if it is a tty frame.
3614 @deffn Command recenter-top-bottom &optional count
3615 This command, which is the default binding for @kbd{C-l}, acts like
3616 @code{recenter}, except if called with no argument. In that case,
3617 successive calls place point according to the cycling order defined
3618 by the variable @code{recenter-positions}.
3621 @defopt recenter-positions
3622 This variable controls how @code{recenter-top-bottom} behaves when
3623 called with no argument. The default value is @code{(middle top
3624 bottom)}, which means that successive calls of
3625 @code{recenter-top-bottom} with no argument cycle between placing
3626 point at the middle, top, and bottom of the window.
3630 @node Vertical Scrolling
3631 @section Vertical Fractional Scrolling
3632 @cindex vertical fractional scrolling
3633 @cindex vertical scroll position
3635 @dfn{Vertical fractional scrolling} means shifting text in a window
3636 up or down by a specified multiple or fraction of a line. Each window
3637 has a @dfn{vertical scroll position}, which is a number, never less than
3638 zero. It specifies how far to raise the contents of the window.
3639 Raising the window contents generally makes all or part of some lines
3640 disappear off the top, and all or part of some other lines appear at the
3641 bottom. The usual value is zero.
3643 The vertical scroll position is measured in units of the normal line
3644 height, which is the height of the default font. Thus, if the value is
3645 .5, that means the window contents are scrolled up half the normal line
3646 height. If it is 3.3, that means the window contents are scrolled up
3647 somewhat over three times the normal line height.
3649 What fraction of a line the vertical scrolling covers, or how many
3650 lines, depends on what the lines contain. A value of .5 could scroll a
3651 line whose height is very short off the screen, while a value of 3.3
3652 could scroll just part of the way through a tall line or an image.
3654 @defun window-vscroll &optional window pixels-p
3655 This function returns the current vertical scroll position of
3656 @var{window}. The default for @var{window} is the selected window.
3657 If @var{pixels-p} is non-@code{nil}, the return value is measured in
3658 pixels, rather than in units of the normal line height.
3668 @defun set-window-vscroll window lines &optional pixels-p
3669 This function sets @var{window}'s vertical scroll position to
3670 @var{lines}. If @var{window} is @code{nil}, the selected window is
3671 used. The argument @var{lines} should be zero or positive; if not, it
3675 The actual vertical scroll position must always correspond
3676 to an integral number of pixels, so the value you specify
3677 is rounded accordingly.
3679 The return value is the result of this rounding.
3683 (set-window-vscroll (selected-window) 1.2)
3688 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
3689 pixels. In this case, the return value is @var{lines}.
3692 @defvar auto-window-vscroll
3693 If this variable is non-@code{nil}, the @code{line-move},
3694 @code{scroll-up}, and @code{scroll-down} functions will automatically
3695 modify the vertical scroll position to scroll through display rows
3696 that are taller than the height of the window, for example in the
3697 presence of large images.
3700 @node Horizontal Scrolling
3701 @section Horizontal Scrolling
3702 @cindex horizontal scrolling
3704 @dfn{Horizontal scrolling} means shifting the image in the window left
3705 or right by a specified multiple of the normal character width. Each
3706 window has a @dfn{horizontal scroll position}, which is a number, never
3707 less than zero. It specifies how far to shift the contents left.
3708 Shifting the window contents left generally makes all or part of some
3709 characters disappear off the left, and all or part of some other
3710 characters appear at the right. The usual value is zero.
3712 The horizontal scroll position is measured in units of the normal
3713 character width, which is the width of space in the default font. Thus,
3714 if the value is 5, that means the window contents are scrolled left by 5
3715 times the normal character width. How many characters actually
3716 disappear off to the left depends on their width, and could vary from
3719 Because we read from side to side in the inner loop, and from top
3720 to bottom in the outer loop, the effect of horizontal scrolling is
3721 not like that of textual or vertical scrolling. Textual scrolling
3722 involves selection of a portion of text to display, and vertical
3723 scrolling moves the window contents contiguously; but horizontal
3724 scrolling causes part of @emph{each line} to go off screen.
3726 Usually, no horizontal scrolling is in effect; then the leftmost
3727 column is at the left edge of the window. In this state, scrolling to
3728 the right is meaningless, since there is no data to the left of the edge
3729 to be revealed by it; so this is not allowed. Scrolling to the left is
3730 allowed; it scrolls the first columns of text off the edge of the window
3731 and can reveal additional columns on the right that were truncated
3732 before. Once a window has a nonzero amount of leftward horizontal
3733 scrolling, you can scroll it back to the right, but only so far as to
3734 reduce the net horizontal scroll to zero. There is no limit to how far
3735 left you can scroll, but eventually all the text will disappear off the
3738 @vindex auto-hscroll-mode
3739 If @code{auto-hscroll-mode} is set, redisplay automatically alters
3740 the horizontal scrolling of a window as necessary to ensure that point
3741 is always visible. However, you can still set the horizontal
3742 scrolling value explicitly. The value you specify serves as a lower
3743 bound for automatic scrolling, i.e., automatic scrolling will not
3744 scroll a window to a column less than the specified one.
3746 @deffn Command scroll-left &optional count set-minimum
3747 This function scrolls the selected window @var{count} columns to the
3748 left (or to the right if @var{count} is negative). The default
3749 for @var{count} is the window width, minus 2.
3751 The return value is the total amount of leftward horizontal scrolling in
3752 effect after the change---just like the value returned by
3753 @code{window-hscroll} (below).
3755 Note that text in paragraphs whose base direction is right-to-left
3756 (@pxref{Bidirectional Display}) moves in the opposite direction: e.g.,
3757 it moves to the right when @code{scroll-left} is invoked with a
3758 positive value of @var{count}.
3760 Once you scroll a window as far right as it can go, back to its normal
3761 position where the total leftward scrolling is zero, attempts to scroll
3762 any farther right have no effect.
3764 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
3765 the lower bound for automatic scrolling; that is, automatic scrolling
3766 will not scroll a window to a column less than the value returned by
3767 this function. Interactive calls pass non-@code{nil} for
3771 @deffn Command scroll-right &optional count set-minimum
3772 This function scrolls the selected window @var{count} columns to the
3773 right (or to the left if @var{count} is negative). The default
3774 for @var{count} is the window width, minus 2. Aside from the direction
3775 of scrolling, this works just like @code{scroll-left}.
3778 @defun window-hscroll &optional window
3779 This function returns the total leftward horizontal scrolling of
3780 @var{window}---the number of columns by which the text in @var{window}
3781 is scrolled left past the left margin. (In right-to-left paragraphs,
3782 the value is the total amount of the rightward scrolling instead.)
3783 The default for @var{window} is the selected window.
3785 The return value is never negative. It is zero when no horizontal
3786 scrolling has been done in @var{window} (which is usually the case).
3805 @defun set-window-hscroll window columns
3806 This function sets horizontal scrolling of @var{window}. The value of
3807 @var{columns} specifies the amount of scrolling, in terms of columns
3808 from the left margin (right margin in right-to-left paragraphs). The
3809 argument @var{columns} should be zero or positive; if not, it is taken
3810 as zero. Fractional values of @var{columns} are not supported at
3813 Note that @code{set-window-hscroll} may appear not to work if you test
3814 it by evaluating a call with @kbd{M-:} in a simple way. What happens
3815 is that the function sets the horizontal scroll value and returns, but
3816 then redisplay adjusts the horizontal scrolling to make point visible,
3817 and this overrides what the function did. You can observe the
3818 function's effect if you call it while point is sufficiently far from
3819 the left margin that it will remain visible.
3821 The value returned is @var{columns}.
3825 (set-window-hscroll (selected-window) 10)
3831 Here is how you can determine whether a given position @var{position}
3832 is off the screen due to horizontal scrolling:
3834 @c FIXME: Maybe hscroll-on-screen-p is a better name?
3837 (defun hscroll-on-screen (window position)
3839 (goto-char position)
3841 (>= (- (current-column) (window-hscroll window)) 0)
3842 (< (- (current-column) (window-hscroll window))
3843 (window-width window)))))
3848 @node Coordinates and Windows
3849 @section Coordinates and Windows
3850 @cindex frame-relative coordinate
3851 @cindex coordinate, relative to frame
3852 @cindex window position
3854 This section describes functions that report the position of a window.
3855 Most of these functions report positions relative to an origin at the
3856 native position of the window's frame (@pxref{Frame Geometry}). Some
3857 functions report positions relative to the origin of the display of the
3858 window's frame. In any case, the origin has the coordinates (0, 0) and
3859 X and Y coordinates increase rightward and downward
3862 For the following functions, X and Y coordinates are reported in
3863 integer character units, i.e., numbers of lines and columns
3864 respectively. On a graphical display, each ``line'' and ``column''
3865 corresponds to the height and width of the default character specified by
3866 the frame's default font (@pxref{Frame Font}).
3868 @defun window-edges &optional window body absolute pixelwise
3869 This function returns a list of the edge coordinates of @var{window}.
3870 If @var{window} is omitted or @code{nil}, it defaults to the selected
3873 The return value has the form @code{(@var{left} @var{top} @var{right}
3874 @var{bottom})}. These list elements are, respectively, the X
3875 coordinate of the leftmost column occupied by the window, the Y
3876 coordinate of the topmost row, the X coordinate one column to the
3877 right of the rightmost column, and the Y coordinate one row down from
3880 Note that these are the actual outer edges of the window, including any
3881 header line, mode line, scroll bar, fringes, window divider and display
3882 margins. On a text terminal, if the window has a neighbor on its right,
3883 its right edge includes the separator line between the window and its
3886 If the optional argument @var{body} is @code{nil}, this means to
3887 return the edges corresponding to the total size of @var{window}.
3888 @var{body} non-@code{nil} means to return the edges of @var{window}'s
3889 body (aka text area). If @var{body} is non-@code{nil}, @var{window}
3890 must specify a live window.
3892 If the optional argument @var{absolute} is @code{nil}, this means to
3893 return edges relative to the native position of @var{window}'s frame.
3894 @var{absolute} non-@code{nil} means to return coordinates relative to
3895 the origin (0, 0) of @var{window}'s display. On non-graphical systems
3896 this argument has no effect.
3898 If the optional argument @var{pixelwise} is @code{nil}, this means to
3899 return the coordinates in terms of the default character width and
3900 height of @var{window}'s frame (@pxref{Frame Font}), rounded if
3901 necessary. @var{pixelwise} non-@code{nil} means to return the
3902 coordinates in pixels. Note that the pixel specified by @var{right} and
3903 @var{bottom} is immediately outside of these edges. If @var{absolute}
3904 is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too.
3907 @defun window-body-edges &optional window
3908 This function returns the edges of @var{window}'s body (@pxref{Window
3909 Sizes}). Calling @code{(window-body-edges window)} is equivalent to
3910 calling @code{(window-edges window t)}, see above.
3913 @comment The following two functions are confusing and hardly used.
3915 @defun window-left-column &optional window
3916 This function returns the leftmost column of @var{window}. This value
3917 equals the @var{left} entry in the list returned by @code{(window-edges
3918 window)} minus the number of columns occupied by the internal border of
3919 @var{window}'s frame.
3922 @defun window-top-line &optional window
3923 This function returns the topmost row of @var{window}. This value is
3924 equal to the @var{top} entry in the list returned by @code{(window-edges
3925 window)} minus the number of lines occupied by the internal border of
3926 @var{window}'s frame.
3930 The following functions can be used to relate a set of
3931 frame-relative coordinates to a window:
3933 @defun window-at x y &optional frame
3934 This function returns the live window at the coordinates @var{x} and
3935 @var{y} given in default character sizes (@pxref{Frame Font}) relative
3936 to the native position of @var{frame} (@pxref{Frame Geometry}).
3938 If there is no window at that position, the return value is @code{nil}.
3939 If @var{frame} is omitted or @code{nil}, it defaults to the selected
3943 @defun coordinates-in-window-p coordinates window
3944 This function checks whether a window @var{window} occupies the frame
3945 relative coordinates @var{coordinates}, and if so, which part of the
3946 window that is. @var{window} should be a live window.
3948 @var{coordinates} should be a cons cell of the form @code{(@var{x}
3949 . @var{y})}, where @var{x} and @var{y} are given in default character
3950 sizes (@pxref{Frame Font}) relative to the native position of
3951 @var{window}'s frame (@pxref{Frame Geometry}).
3953 If there is no window at the specified position, the return value is
3954 @code{nil} . Otherwise, the return value is one of the following:
3957 @item (@var{relx} . @var{rely})
3958 The coordinates are inside @var{window}. The numbers @var{relx} and
3959 @var{rely} are the equivalent window-relative coordinates for the
3960 specified position, counting from 0 at the top left corner of the
3964 The coordinates are in the mode line of @var{window}.
3967 The coordinates are in the header line of @var{window}.
3970 The coordinates are in the divider separating @var{window} from a
3971 window on the right.
3973 @item bottom-divider
3974 The coordinates are in the divider separating @var{window} from a
3978 The coordinates are in the vertical line between @var{window} and its
3979 neighbor to the right. This value occurs only if the window doesn't
3980 have a scroll bar; positions in a scroll bar are considered outside the
3981 window for these purposes.
3985 The coordinates are in the left or right fringe of the window.
3989 The coordinates are in the left or right margin of the window.
3992 The coordinates are not in any part of @var{window}.
3995 The function @code{coordinates-in-window-p} does not require a frame as
3996 argument because it always uses the frame that @var{window} is on.
3999 The following functions return window positions in pixels, rather
4000 than character units. Though mostly useful on graphical displays,
4001 they can also be called on text terminals, where the screen area of
4002 each text character is taken to be one pixel.
4004 @defun window-pixel-edges &optional window
4005 This function returns a list of pixel coordinates for the edges of
4006 @var{window}. Calling @code{(window-pixel-edges window)} is equivalent
4007 to calling @code{(window-edges window nil nil t)}, see above.
4010 @comment The following two functions are confusing and hardly used.
4012 @defun window-pixel-left &optional window
4013 This function returns the left pixel edge of window @var{window}. This
4014 value equals the @var{left} entry in the list returned by
4015 @code{(window-pixel-edges window)} minus the number of pixels occupied
4016 by the internal border of @var{window}'s frame. @var{window} must be a
4017 valid window and defaults to the selected one.
4020 @defun window-pixel-top &optional window
4021 This function returns the top pixel edge of window @var{window}. This
4022 value is equal to the @var{top} entry in the list returned by
4023 @code{(window-pixel-edges window)} minus the number of pixels occupied
4024 by the internal border of @var{window}'s frame. @var{window} must be a
4025 valid window and defaults to the selected one.
4029 @defun window-body-pixel-edges &optional window
4030 This function returns the pixel edges of @var{window}'s body. Calling
4031 @code{(window-body-pixel-edges window)} is equivalent to calling
4032 @code{(window-edges window t nil t)}, see above.
4035 The following functions return window positions in pixels, relative to
4036 the origin of the display screen rather than that of the frame:
4038 @defun window-absolute-pixel-edges &optional window
4039 This function returns the pixel coordinates of @var{WINDOW} relative to
4040 an origin at (0, 0) of the display of @var{window}'s frame. Calling
4041 @code{(window-absolute-pixel-edges)} is equivalent to calling
4042 @code{(window-edges window nil t t)}, see above.
4045 @defun window-absolute-body-pixel-edges &optional window
4046 This function returns the pixel coordinates of @var{WINDOW}'s body
4047 relative to an origin at (0, 0) of the display of @var{window}'s frame.
4048 Calling @code{(window-absolute-body-pixel-edges window)} is equivalent
4049 to calling @code{(window-edges window t t t)}, see above.
4051 Combined with @code{set-mouse-absolute-pixel-position}, this function
4052 can be used to move the mouse pointer to an arbitrary buffer position
4053 visible in some window:
4057 (let ((edges (window-absolute-body-pixel-edges))
4058 (position (pos-visible-in-window-p nil nil t)))
4059 (set-mouse-absolute-pixel-position
4060 (+ (nth 0 edges) (nth 0 position))
4061 (+ (nth 1 edges) (nth 1 position))))
4065 On a graphical terminal this form ``warps'' the mouse cursor to the
4066 upper left corner of the glyph at the selected window's point. A
4067 position calculated this way can be also used to show a tooltip window
4071 The following function returns the screen coordinates of a buffer
4072 position visible in a window:
4074 @defun window-absolute-pixel-position &optional position window
4075 If the buffer position @var{position} is visible in window @var{window},
4076 this function returns the display coordinates of the upper/left corner
4077 of the glyph at @var{position}. The return value is a cons of the X-
4078 and Y-coordinates of that corner, relative to an origin at (0, 0) of
4079 @var{window}'s display. It returns @code{nil} if @var{position} is not
4080 visible in @var{window}.
4082 @var{window} must be a live window and defaults to the selected
4083 window. @var{position} defaults to the value of @code{window-point}
4086 This means that in order to move the mouse pointer to the position of
4087 point in the selected window, it's sufficient to write:
4091 (let ((position (window-absolute-pixel-position)))
4092 (set-mouse-absolute-pixel-position
4093 (car position) (cdr position)))
4099 @node Window Configurations
4100 @section Window Configurations
4101 @cindex window configurations
4102 @cindex saving window information
4104 A @dfn{window configuration} records the entire layout of one
4105 frame---all windows, their sizes, which buffers they contain, how those
4106 buffers are scrolled, and their value of point; also their
4107 fringes, margins, and scroll bar settings. It also includes the value
4108 of @code{minibuffer-scroll-window}. As a special exception, the window
4109 configuration does not record the value of point in the selected window
4110 for the current buffer.
4112 You can bring back an entire frame layout by restoring a previously
4113 saved window configuration. If you want to record the layout of all
4114 frames instead of just one, use a frame configuration instead of a
4115 window configuration. @xref{Frame Configurations}.
4117 @defun current-window-configuration &optional frame
4118 This function returns a new object representing @var{frame}'s current
4119 window configuration. The default for @var{frame} is the selected
4120 frame. The variable @code{window-persistent-parameters} specifies
4121 which window parameters (if any) are saved by this function.
4122 @xref{Window Parameters}.
4125 @defun set-window-configuration configuration
4126 This function restores the configuration of windows and buffers as
4127 specified by @var{configuration}, for the frame that @var{configuration}
4130 The argument @var{configuration} must be a value that was previously
4131 returned by @code{current-window-configuration}. The configuration is
4132 restored in the frame from which @var{configuration} was made, whether
4133 that frame is selected or not. In some rare cases this may trigger
4134 execution of the @code{window-size-change-functions} (@pxref{Window
4135 Hooks}) even if the size of windows did not change at all. The
4136 @code{window-configuration-change-hook} functions will be called if and
4137 only if at least one window was added to or deleted from the frame.
4139 If the frame from which @var{configuration} was saved is dead, all this
4140 function does is restore the three variables @code{window-min-height},
4141 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
4142 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
4144 Here is a way of using this function to get the same effect
4145 as @code{save-window-excursion}:
4149 (let ((config (current-window-configuration)))
4151 (progn (split-window-below nil)
4153 (set-window-configuration config)))
4158 @defmac save-window-excursion forms@dots{}
4159 This macro records the window configuration of the selected frame,
4160 executes @var{forms} in sequence, then restores the earlier window
4161 configuration. The return value is the value of the final form in
4164 Most Lisp code should not use this macro; @code{save-selected-window}
4165 is typically sufficient. In particular, this macro cannot reliably
4166 prevent the code in @var{forms} from opening new windows, because new
4167 windows might be opened in other frames (@pxref{Choosing Window}), and
4168 @code{save-window-excursion} only saves and restores the window
4169 configuration on the current frame.
4171 Do not use this macro in @code{window-size-change-functions}; exiting
4172 the macro triggers execution of @code{window-size-change-functions},
4173 leading to an endless loop.
4176 @defun window-configuration-p object
4177 This function returns @code{t} if @var{object} is a window configuration.
4180 @defun compare-window-configurations config1 config2
4181 This function compares two window configurations as regards the
4182 structure of windows, but ignores the values of point and the
4183 saved scrolling positions---it can return @code{t} even if those
4186 The function @code{equal} can also compare two window configurations; it
4187 regards configurations as unequal if they differ in any respect, even a
4191 @defun window-configuration-frame config
4192 This function returns the frame for which the window configuration
4193 @var{config} was made.
4196 Other primitives to look inside of window configurations would make
4197 sense, but are not implemented because we did not need them. See the
4198 file @file{winner.el} for some more operations on windows
4201 The objects returned by @code{current-window-configuration} die
4202 together with the Emacs process. In order to store a window
4203 configuration on disk and read it back in another Emacs session, you
4204 can use the functions described next. These functions are also useful
4205 to clone the state of a frame into an arbitrary live window
4206 (@code{set-window-configuration} effectively clones the windows of a
4207 frame into the root window of that very frame only).
4209 @cindex window state
4210 @defun window-state-get &optional window writable
4211 This function returns the state of @var{window} as a Lisp object. The
4212 argument @var{window} must be a valid window and defaults to the root
4213 window of the selected frame.
4215 If the optional argument @var{writable} is non-@code{nil}, this means to
4216 not use markers for sampling positions like @code{window-point} or
4217 @code{window-start}. This argument should be non-@code{nil} when the
4218 state will be written to disk and read back in another session.
4220 Together, the argument @var{writable} and the variable
4221 @code{window-persistent-parameters} specify which window parameters are
4222 saved by this function. @xref{Window Parameters}.
4225 The value returned by @code{window-state-get} can be used in the same
4226 session to make a clone of a window in another window. It can be also
4227 written to disk and read back in another session. In either case, use
4228 the following function to restore the state of the window.
4230 @defun window-state-put state &optional window ignore
4231 This function puts the window state @var{state} into @var{window}.
4232 The argument @var{state} should be the state of a window returned by
4233 an earlier invocation of @code{window-state-get}, see above. The
4234 optional argument @var{window} can be either a live window or an
4235 internal window (@pxref{Windows and Frames}) and defaults to the
4236 selected one. If @var{window} is not live, it is replaced by a live
4237 window before putting @var{state} into it.
4239 If the optional argument @var{ignore} is non-@code{nil}, it means to ignore
4240 minimum window sizes and fixed-size restrictions. If @var{ignore}
4241 is @code{safe}, this means windows can get as small as one line
4246 @node Window Parameters
4247 @section Window Parameters
4248 @cindex window parameters
4250 This section describes how window parameters can be used to associate
4251 additional information with windows.
4253 @defun window-parameter window parameter
4254 This function returns @var{window}'s value for @var{parameter}. The
4255 default for @var{window} is the selected window. If @var{window} has no
4256 setting for @var{parameter}, this function returns @code{nil}.
4259 @defun window-parameters &optional window
4260 This function returns all parameters of @var{window} and their values.
4261 The default for @var{window} is the selected window. The return value
4262 is either @code{nil}, or an association list whose elements have the form
4263 @code{(@var{parameter} . @var{value})}.
4266 @defun set-window-parameter window parameter value
4267 This function sets @var{window}'s value of @var{parameter} to
4268 @var{value} and returns @var{value}. The default for @var{window}
4269 is the selected window.
4272 By default, the functions that save and restore window configurations or the
4273 states of windows (@pxref{Window Configurations}) do not care about
4274 window parameters. This means that when you change the value of a
4275 parameter within the body of a @code{save-window-excursion}, the
4276 previous value is not restored when that macro exits. It also means
4277 that when you restore via @code{window-state-put} a window state saved
4278 earlier by @code{window-state-get}, all cloned windows have their
4279 parameters reset to @code{nil}. The following variable allows you to
4280 override the standard behavior:
4282 @defvar window-persistent-parameters
4283 This variable is an alist specifying which parameters get saved by
4284 @code{current-window-configuration} and @code{window-state-get}, and
4285 subsequently restored by @code{set-window-configuration} and
4286 @code{window-state-put}. @xref{Window Configurations}.
4288 The @sc{car} of each entry of this alist is a symbol specifying the
4289 parameter. The @sc{cdr} should be one of the following:
4293 This value means the parameter is saved neither by
4294 @code{window-state-get} nor by @code{current-window-configuration}.
4297 This value specifies that the parameter is saved by
4298 @code{current-window-configuration} and (provided its @var{writable}
4299 argument is @code{nil}) by @code{window-state-get}.
4301 @item @code{writable}
4302 This means that the parameter is saved unconditionally by both
4303 @code{current-window-configuration} and @code{window-state-get}. This
4304 value should not be used for parameters whose values do not have a read
4305 syntax. Otherwise, invoking @code{window-state-put} in another session
4306 may fail with an @code{invalid-read-syntax} error.
4310 Some functions (notably @code{delete-window},
4311 @code{delete-other-windows} and @code{split-window}), may behave specially
4312 when their @var{window} argument has a parameter set. You can override
4313 such special behavior by binding the following variable to a
4314 non-@code{nil} value:
4316 @defvar ignore-window-parameters
4317 If this variable is non-@code{nil}, some standard functions do not
4318 process window parameters. The functions currently affected by this are
4319 @code{split-window}, @code{delete-window}, @code{delete-other-windows},
4320 and @code{other-window}.
4322 An application can bind this variable to a non-@code{nil} value around
4323 calls to these functions. If it does so, the application is fully
4324 responsible for correctly assigning the parameters of all involved
4325 windows when exiting that function.
4328 The following parameters are currently used by the window management
4332 @item @code{delete-window}
4333 This parameter affects the execution of @code{delete-window}
4334 (@pxref{Deleting Windows}).
4336 @item @code{delete-other-windows}
4337 This parameter affects the execution of @code{delete-other-windows}
4338 (@pxref{Deleting Windows}).
4340 @item @code{split-window}
4341 This parameter affects the execution of @code{split-window}
4342 (@pxref{Splitting Windows}).
4344 @item @code{other-window}
4345 This parameter affects the execution of @code{other-window}
4346 (@pxref{Cyclic Window Ordering}).
4348 @item @code{no-other-window}
4349 This parameter marks the window as not selectable by @code{other-window}
4350 (@pxref{Cyclic Window Ordering}).
4352 @item @code{clone-of}
4353 This parameter specifies the window that this one has been cloned
4354 from. It is installed by @code{window-state-get} (@pxref{Window
4357 @item @code{preserved-size}
4358 This parameter specifies a buffer, a direction where @code{nil} means
4359 vertical and @code{t} horizontal, and a size in pixels. If this window
4360 displays the specified buffer and its size in the indicated direction
4361 equals the size specified by this parameter, then Emacs will try to
4362 preserve the size of this window in the indicated direction. This
4363 parameter is installed and updated by the function
4364 @code{window-preserve-size} (@pxref{Preserving Window Sizes}).
4366 @item @code{quit-restore}
4367 This parameter is installed by the buffer display functions
4368 (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
4369 (@pxref{Quitting Windows}). It contains four elements:
4371 The first element is one of the symbols @code{window}, meaning that the
4372 window has been specially created by @code{display-buffer}; @code{frame},
4373 a separate frame has been created; @code{same}, the window has
4374 displayed the same buffer before; or @code{other}, the window showed
4375 another buffer before.
4377 The second element is either one of the symbols @code{window} or
4378 @code{frame}, or a list whose elements are the buffer shown in the
4379 window before, that buffer's window start and window point positions,
4380 and the window's height at that time.
4382 The third element is the window selected at the time the parameter was
4383 created. The function @code{quit-restore-window} tries to reselect that
4384 window when it deletes the window passed to it as argument.
4386 The fourth element is the buffer whose display caused the creation of
4387 this parameter. @code{quit-restore-window} deletes the specified window
4388 only if it still shows that buffer.
4390 @item @code{min-margins}
4391 The value of this parameter is a cons cell whose @sc{car} and @sc{cdr},
4392 if non-@code{nil}, specify the minimum values (in columns) for the left
4393 and right margin of this window. When present, Emacs will use these
4394 values instead of the actual margin widths for determining whether a
4395 window can be split or shrunk horizontally.
4397 Emacs never auto-adjusts the margins of any window after splitting or
4398 resizing it. It is the sole responsibility of any application setting
4399 this parameter to adjust the margins of this window as well as those of
4400 any new window that inherits this window's margins due to a split.
4401 Both @code{window-configuration-change-hook} and
4402 @code{window-size-change-functions} (@pxref{Window Hooks}) should be
4403 employed for this purpose.
4405 This parameter was introduced in Emacs version 25.1 to support
4406 applications that use large margins to center buffer text within a
4407 window and should be used, with due care, exclusively by those
4408 applications. It might be replaced by an improved solution in future
4412 There are additional parameters @code{window-atom} and @code{window-side};
4413 these are reserved and should not be used by applications.
4417 @section Hooks for Window Scrolling and Changes
4418 @cindex hooks for window operations
4420 This section describes how a Lisp program can take action whenever a
4421 window displays a different part of its buffer or a different buffer.
4422 There are three actions that can change this: scrolling the window,
4423 switching buffers in the window, and changing the size of the window.
4424 The first two actions run @code{window-scroll-functions}; the last runs
4425 @code{window-size-change-functions}.
4427 @defvar window-scroll-functions
4428 This variable holds a list of functions that Emacs should call before
4429 redisplaying a window with scrolling. Displaying a different buffer in
4430 the window also runs these functions.
4432 This variable is not a normal hook, because each function is called with
4433 two arguments: the window, and its new display-start position.
4435 These functions must take care when using @code{window-end}
4436 (@pxref{Window Start and End}); if you need an up-to-date value, you
4437 must use the @var{update} argument to ensure you get it.
4439 @strong{Warning:} don't use this feature to alter the way the window
4440 is scrolled. It's not designed for that, and such use probably won't
4444 @defvar window-size-change-functions
4445 This variable holds a list of functions to be called if the size of any
4446 window changes for any reason. The functions are called once per
4447 redisplay, and once for each frame on which size changes have occurred.
4449 Each function receives the frame as its sole argument. To find out
4450 whether a specific window has changed size, compare the return values of
4451 @code{window-pixel-width-before-size-change} and
4452 @code{window-pixel-width} respectively
4453 @code{window-pixel-height-before-size-change} and
4454 @code{window-pixel-height} for that window (@pxref{Window Sizes}).
4456 These function are usually only called when at least one window was
4457 added or has changed size since the last time this hook was run for the
4458 associated frame. In some rare cases this hook also runs when a window
4459 that was added intermittently has been deleted afterwards. In these
4460 cases none of the windows on the frame will appear to have changed its
4463 You may use @code{save-selected-window} in these functions
4464 (@pxref{Selecting Windows}). However, do not use
4465 @code{save-window-excursion} (@pxref{Window Configurations}); exiting
4466 that macro counts as a size change, which would cause these functions to
4470 @defvar window-configuration-change-hook
4471 A normal hook that is run every time the window configuration of a frame
4472 changes. Window configuration changes include splitting and deleting
4473 windows and the display of a different buffer in a window. Resizing the
4474 frame or individual windows do not count as configuration changes. Use
4475 @code{window-size-change-functions}, see above, when you want to track
4476 size changes that are not caused by the deletion or creation of windows.
4478 The buffer-local part of this hook is run once for each window on the
4479 affected frame, with the relevant window selected and its buffer
4480 current. The global part is run once for the modified frame, with that
4484 In addition, you can use @code{jit-lock-register} to register a Font
4485 Lock fontification function, which will be called whenever parts of a
4486 buffer are (re)fontified because a window was scrolled or its size
4487 changed. @xref{Other Font Lock Variables}.