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 @cindex window pixel width
549 @cindex pixel width of a window
550 @cindex total pixel width of a window
552 @defun window-pixel-width &optional Lisp_Object &optional window
553 This function returns the width of window @var{window} in pixels.
554 @var{window} must be a valid window and defaults to the selected one.
556 The return value includes the fringes and margins of @var{window} as
557 well as any vertical dividers or scroll bars belonging to @var{window}.
558 If @var{window} is an internal window, its pixel width is the width of
559 the screen areas spanned by its children.
562 @cindex full-width window
563 @cindex full-height window
564 The following functions can be used to determine whether a given
565 window has any adjacent windows.
567 @defun window-full-height-p &optional window
568 This function returns non-@code{nil} if @var{window} has no other window
569 above or below it in its frame. More precisely, this means that the
570 total height of @var{window} equals the total height of the root window
571 on that frame. The minibuffer window does not count in this regard. If
572 @var{window} is omitted or @code{nil}, it defaults to the selected
576 @defun window-full-width-p &optional window
577 This function returns non-@code{nil} if @var{window} has no other
578 window to the left or right in its frame, i.e., its total width equals
579 that of the root window on that frame. If @var{window} is omitted or
580 @code{nil}, it defaults to the selected window.
583 @cindex window body height
584 @cindex body height of a window
585 The @dfn{body height} of a window is the height of its text area, which
586 does not include a mode or header line, a horizontal scroll bar, or a
589 @defun window-body-height &optional window pixelwise
590 This function returns the height, in lines, of the body of window
591 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
592 the selected window; otherwise it must be a live window.
594 If the optional argument @var{pixelwise} is non-@code{nil}, this
595 function returns the body height of @var{window} counted in pixels.
597 If @var{pixelwise} is @code{nil}, the return value is rounded down to
598 the nearest integer, if necessary. This means that if a line at the
599 bottom of the text area is only partially visible, that line is not
600 counted. It also means that the height of a window's body can never
601 exceed its total height as returned by @code{window-total-height}.
604 @cindex window body width
605 @cindex body width of a window
606 The @dfn{body width} of a window is the width of its text area, which
607 does not include the scroll bar, fringes, margins or a right divider.
608 Note that when one or both fringes are removed (by setting their width
609 to zero), the display engine reserves two character cells, one on each
610 side of the window, for displaying the continuation and truncation
611 glyphs, which leaves 2 columns less for text display. (The function
612 @code{window-max-chars-per-line}, described below, takes this
613 peculiarity into account.)
615 @defun window-body-width &optional window pixelwise
616 This function returns the width, in columns, of the body of window
617 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
618 the selected window; otherwise it must be a live window.
620 If the optional argument @var{pixelwise} is non-@code{nil}, this
621 function returns the body width of @var{window} in units of pixels.
623 If @var{pixelwise} is @code{nil}, the return value is rounded down to
624 the nearest integer, if necessary. This means that if a column on the
625 right of the text area is only partially visible, that column is not
626 counted. It also means that the width of a window's body can never
627 exceed its total width as returned by @code{window-total-width}.
630 @cindex window body size
631 @cindex body size of a window
632 @defun window-body-size &optional window horizontal pixelwise
633 This function returns the body height or body width of @var{window}. If
634 @var{horizontal} is omitted or @code{nil}, it is equivalent to calling
635 @code{window-body-height} for @var{window}; otherwise it is equivalent
636 to calling @code{window-body-width}. In either case, the optional
637 argument @var{pixelwise} is passed to the function called.
640 For compatibility with previous versions of Emacs,
641 @code{window-height} is an alias for @code{window-total-height}, and
642 @code{window-width} is an alias for @code{window-body-width}. These
643 aliases are considered obsolete and will be removed in the future.
645 The pixel heights of a window's mode and header line can be retrieved
646 with the functions given below. Their return value is usually accurate
647 unless the window has not been displayed before: In that case, the
648 return value is based on an estimate of the font used for the window's
651 @defun window-mode-line-height &optional window
652 This function returns the height in pixels of @var{window}'s mode line.
653 @var{window} must be a live window and defaults to the selected one. If
654 @var{window} has no mode line, the return value is zero.
657 @defun window-header-line-height &optional window
658 This function returns the height in pixels of @var{window}'s header
659 line. @var{window} must be a live window and defaults to the selected
660 one. If @var{window} has no header line, the return value is zero.
663 Functions for retrieving the height and/or width of window dividers
664 (@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
665 (@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
666 described in the corresponding sections.
668 If your Lisp program needs to make layout decisions, you will find the
669 following function useful:
671 @defun window-max-chars-per-line &optional window face
672 This function returns the number of characters displayed in the
673 specified face @var{face} in the specified window @var{window} (which
674 must be a live window). If @var{face} was remapped (@pxref{Face
675 Remapping}), the information is returned for the remapped face. If
676 omitted or @code{nil}, @var{face} defaults to the default face, and
677 @var{window} defaults to the selected window.
679 Unlike @code{window-body-width}, this function accounts for the actual
680 size of @var{face}'s font, instead of working in units of the canonical
681 character width of @var{window}'s frame (@pxref{Frame Font}). It also
682 accounts for space used by the continuation glyph, if @var{window} lacks
683 one or both of its fringes.
686 @cindex fixed-size window
687 @vindex window-min-height
688 @vindex window-min-width
689 Commands that change the size of windows (@pxref{Resizing Windows}),
690 or split them (@pxref{Splitting Windows}), obey the variables
691 @code{window-min-height} and @code{window-min-width}, which specify the
692 smallest allowable window height and width. They also obey the variable
693 @code{window-size-fixed}, with which a window can be @dfn{fixed} in
694 size (@pxref{Preserving Window Sizes}).
696 @defopt window-min-height
697 This option specifies the minimum total height, in lines, of any window.
698 Its value has to accommodate at least one text line as well as a mode
699 and header line, a horizontal scroll bar and a bottom divider, if
703 @defopt window-min-width
704 This option specifies the minimum total width, in columns, of any
705 window. Its value has to accommodate two text columns as well as
706 margins, fringes, a scroll bar and a right divider, if present.
709 The following function tells how small a specific window can get taking
710 into account the sizes of its areas and the values of
711 @code{window-min-height}, @code{window-min-width} and
712 @code{window-size-fixed} (@pxref{Preserving Window Sizes}).
714 @defun window-min-size &optional window horizontal ignore pixelwise
715 This function returns the minimum size of @var{window}. @var{window}
716 must be a valid window and defaults to the selected one. The optional
717 argument @var{horizontal} non-@code{nil} means to return the minimum
718 number of columns of @var{window}; otherwise return the minimum number
719 of @var{window}'s lines.
721 The return value makes sure that all components of @var{window} remain
722 fully visible if @var{window}'s size were actually set to it. With
723 @var{horizontal} @code{nil} it includes the mode and header line, the
724 horizontal scroll bar and the bottom divider, if present. With
725 @var{horizontal} non-@code{nil} it includes the margins and fringes, the
726 vertical scroll bar and the right divider, if present.
728 The optional argument @var{ignore}, if non-@code{nil}, means ignore
729 restrictions imposed by fixed size windows, @code{window-min-height} or
730 @code{window-min-width} settings. If @var{ignore} equals @code{safe},
731 live windows may get as small as @code{window-safe-min-height} lines and
732 @code{window-safe-min-width} columns. If @var{ignore} is a window,
733 ignore restrictions for that window only. Any other non-@code{nil}
734 value means ignore all of the above restrictions for all windows.
736 The optional argument @var{pixelwise} non-@code{nil} means to return the
737 minimum size of @var{window} counted in pixels.
740 @node Resizing Windows
741 @section Resizing Windows
742 @cindex window resizing
743 @cindex resize window
744 @cindex changing window size
745 @cindex window size, changing
747 This section describes functions for resizing a window without
748 changing the size of its frame. Because live windows do not overlap,
749 these functions are meaningful only on frames that contain two or more
750 windows: resizing a window also changes the size of a neighboring
751 window. If there is just one window on a frame, its size cannot be
752 changed except by resizing the frame (@pxref{Size and Position}).
754 Except where noted, these functions also accept internal windows as
755 arguments. Resizing an internal window causes its child windows to be
756 resized to fit the same space.
758 @defun window-resizable window delta &optional horizontal ignore pixelwise
759 This function returns @var{delta} if the size of @var{window} can be
760 changed vertically by @var{delta} lines. If the optional argument
761 @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
762 @var{window} can be resized horizontally by @var{delta} columns. It
763 does not actually change the window size.
765 If @var{window} is @code{nil}, it defaults to the selected window.
767 A positive value of @var{delta} means to check whether the window can be
768 enlarged by that number of lines or columns; a negative value of
769 @var{delta} means to check whether the window can be shrunk by that many
770 lines or columns. If @var{delta} is non-zero, a return value of 0 means
771 that the window cannot be resized.
773 Normally, the variables @code{window-min-height} and
774 @code{window-min-width} specify the smallest allowable window size
775 (@pxref{Window Sizes}). However, if the optional argument @var{ignore}
776 is non-@code{nil}, this function ignores @code{window-min-height} and
777 @code{window-min-width}, as well as @code{window-size-fixed}. Instead,
778 it considers the minimum-height window to be one consisting of a header
779 and a mode line, a horizontal scrollbar and a bottom divider (if any),
780 plus a text area one line tall; and a minimum-width window as one
781 consisting of fringes, margins, a scroll bar and a right divider (if
782 any), plus a text area two columns wide.
784 If the optional argument @var{pixelwise} is non-@code{nil},
785 @var{delta} is interpreted as pixels.
788 @defun window-resize window delta &optional horizontal ignore pixelwise
789 This function resizes @var{window} by @var{delta} increments. If
790 @var{horizontal} is @code{nil}, it changes the height by @var{delta}
791 lines; otherwise, it changes the width by @var{delta} columns. A
792 positive @var{delta} means to enlarge the window, and a negative
793 @var{delta} means to shrink it.
795 If @var{window} is @code{nil}, it defaults to the selected window. If
796 the window cannot be resized as demanded, an error is signaled.
798 The optional argument @var{ignore} has the same meaning as for the
799 function @code{window-resizable} above.
801 If the optional argument @var{pixelwise} is non-@code{nil},
802 @var{delta} will be interpreted as pixels.
804 The choice of which window edges this function alters depends on the
805 values of the option @code{window-combination-resize} and the
806 combination limits of the involved windows; in some cases, it may alter
807 both edges. @xref{Recombining Windows}. To resize by moving only the
808 bottom or right edge of a window, use the function
809 @code{adjust-window-trailing-edge}.
812 @c The commands enlarge-window, enlarge-window-horizontally,
813 @c shrink-window, and shrink-window-horizontally are documented in the
814 @c Emacs manual. They are not preferred for calling from Lisp.
816 @defun adjust-window-trailing-edge window delta &optional horizontal pixelwise
817 This function moves @var{window}'s bottom edge by @var{delta} lines.
818 If optional argument @var{horizontal} is non-@code{nil}, it instead
819 moves the right edge by @var{delta} columns. If @var{window} is
820 @code{nil}, it defaults to the selected window.
822 If the optional argument @var{pixelwise} is non-@code{nil},
823 @var{delta} is interpreted as pixels.
825 A positive @var{delta} moves the edge downwards or to the right; a
826 negative @var{delta} moves it upwards or to the left. If the edge
827 cannot be moved as far as specified by @var{delta}, this function
828 moves it as far as possible but does not signal a error.
830 This function tries to resize windows adjacent to the edge that is
831 moved. If this is not possible for some reason (e.g., if that adjacent
832 window is fixed-size), it may resize other windows.
835 @cindex pixelwise, resizing windows
836 @defopt window-resize-pixelwise
837 If the value of this option is non-@code{nil}, Emacs resizes windows in
838 units of pixels. This currently affects functions like
839 @code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
840 @code{minimize-window}, @code{fit-window-to-buffer},
841 @code{fit-frame-to-buffer} and
842 @code{shrink-window-if-larger-than-buffer} (all listed below).
844 Note that when a frame's pixel size is not a multiple of its character
845 size, at least one window may get resized pixelwise even if this
846 option is @code{nil}. The default value is @code{nil}.
849 The following commands resize windows in more specific ways. When
850 called interactively, they act on the selected window.
852 @deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size
853 This command adjusts the height or width of @var{window} to fit the text
854 in it. It returns non-@code{nil} if it was able to resize @var{window},
855 and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
856 defaults to the selected window. Otherwise, it should be a live window.
858 If @var{window} is part of a vertical combination, this function adjusts
859 @var{window}'s height. The new height is calculated from the actual
860 height of the accessible portion of its buffer. The optional argument
861 @var{max-height}, if non-@code{nil}, specifies the maximum total height
862 that this function can give @var{window}. The optional argument
863 @var{min-height}, if non-@code{nil}, specifies the minimum total height
864 that it can give, which overrides the variable @code{window-min-height}.
865 Both @var{max-height} and @var{min-height} are specified in lines and
866 include mode and header line and a bottom divider, if any.
868 If @var{window} is part of a horizontal combination and the value of the
869 option @code{fit-window-to-buffer-horizontally} (see below) is
870 non-@code{nil}, this function adjusts @var{window}'s height. The new
871 width of @var{window} is calculated from the maximum length of its
872 buffer's lines that follow the current start position of @var{window}.
873 The optional argument @var{max-width} specifies a maximum width and
874 defaults to the width of @var{window}'s frame. The optional argument
875 @var{min-width} specifies a minimum width and defaults to
876 @code{window-min-width}. Both @var{max-width} and @var{min-width} are
877 specified in columns and include fringes, margins and scrollbars, if
880 The optional argument @var{preserve-size}, if non-@code{nil}, will
881 install a parameter to preserve the size of @var{window} during future
882 resize operations (@pxref{Preserving Window Sizes}).
884 If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
885 this function will try to resize the frame of @var{window} to fit its
886 contents by calling @code{fit-frame-to-buffer} (see below).
889 @defopt fit-window-to-buffer-horizontally
890 If this is non-@code{nil}, @code{fit-window-to-buffer} can resize
891 windows horizontally. If this is @code{nil} (the default)
892 @code{fit-window-to-buffer} never resizes windows horizontally. If this
893 is @code{only}, it can resize windows horizontally only. Any other
894 value means @code{fit-window-to-buffer} can resize windows in both
898 @defopt fit-frame-to-buffer
899 If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a
900 frame to its buffer. A frame is fit if and only if its root window is a
901 live window and this option is non-@code{nil}. If this is
902 @code{horizontally}, frames are fit horizontally only. If this is
903 @code{vertically}, frames are fit vertically only. Any other
904 non-@code{nil} value means frames can be resized in both dimensions.
907 If you have a frame that displays only one window, you can fit that
908 frame to its buffer using the command @code{fit-frame-to-buffer}.
910 @deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
911 This command adjusts the size of @var{frame} to display the contents of
912 its buffer exactly. @var{frame} can be any live frame and defaults to
913 the selected one. Fitting is done only if @var{frame}'s root window is
914 live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
915 and @var{min-width} specify bounds on the new total size of
916 @var{frame}'s root window. @var{min-height} and @var{min-width} default
917 to the values of @code{window-min-height} and @code{window-min-width}
920 If the optional argument @var{only} is @code{vertically}, this function
921 may resize the frame vertically only. If @var{only} is
922 @code{horizontally}, it may resize the frame horizontally only.
925 The behavior of @code{fit-frame-to-buffer} can be controlled with the
926 help of the two options listed next.
928 @defopt fit-frame-to-buffer-margins
929 This option can be used to specify margins around frames to be fit by
930 @code{fit-frame-to-buffer}. Such margins can be useful to avoid, for
931 example, that such frames overlap the taskbar.
933 It specifies the numbers of pixels to be left free on the left, above,
934 the right, and below a frame that shall be fit. The default specifies
935 @code{nil} for each which means to use no margins. The value specified
936 here can be overridden for a specific frame by that frame's
937 @code{fit-frame-to-buffer-margins} parameter, if present.
940 @defopt fit-frame-to-buffer-sizes
941 This option specifies size boundaries for @code{fit-frame-to-buffer}.
942 It specifies the total maximum and minimum lines and maximum and minimum
943 columns of the root window of any frame that shall be fit to its buffer.
944 If any of these values is non-@code{nil}, it overrides the corresponding
945 argument of @code{fit-frame-to-buffer}.
948 @deffn Command shrink-window-if-larger-than-buffer &optional window
949 This command attempts to reduce @var{window}'s height as much as
950 possible while still showing its full buffer, but no less than
951 @code{window-min-height} lines. The return value is non-@code{nil} if
952 the window was resized, and @code{nil} otherwise. If @var{window} is
953 omitted or @code{nil}, it defaults to the selected window. Otherwise,
954 it should be a live window.
956 This command does nothing if the window is already too short to
957 display all of its buffer, or if any of the buffer is scrolled
958 off-screen, or if the window is the only live window in its frame.
960 This command calls @code{fit-window-to-buffer} (see above) to do its
965 @cindex balancing window sizes
966 @deffn Command balance-windows &optional window-or-frame
967 This function balances windows in a way that gives more space to
968 full-width and/or full-height windows. If @var{window-or-frame}
969 specifies a frame, it balances all windows on that frame. If
970 @var{window-or-frame} specifies a window, it balances only that window
971 and its siblings (@pxref{Windows and Frames}).
974 @deffn Command balance-windows-area
975 This function attempts to give all windows on the selected frame
976 approximately the same share of the screen area. Full-width or
977 full-height windows are not given more space than other windows.
980 @cindex maximizing windows
981 @deffn Command maximize-window &optional window
982 This function attempts to make @var{window} as large as possible, in
983 both dimensions, without resizing its frame or deleting other windows.
984 If @var{window} is omitted or @code{nil}, it defaults to the selected
988 @cindex minimizing windows
989 @deffn Command minimize-window &optional window
990 This function attempts to make @var{window} as small as possible, in
991 both dimensions, without deleting it or resizing its frame. If
992 @var{window} is omitted or @code{nil}, it defaults to the selected
997 @node Preserving Window Sizes
998 @section Preserving Window Sizes
999 @cindex preserving window sizes
1001 A window can get resized explicitly by using one of the functions from
1002 the preceding section or implicitly, for example, when resizing an
1003 adjacent window, when splitting or deleting a window (@pxref{Splitting
1004 Windows}, @pxref{Deleting Windows}) or when resizing the window's frame
1005 (@pxref{Size and Position}).
1007 It is possible to avoid implicit resizing of a specific window when
1008 there are one or more other resizable windows on the same frame. For
1009 this purpose, Emacs must be advised to @dfn{preserve} the size of that
1010 window. There are two basic ways to do that.
1012 @defvar window-size-fixed
1013 If this buffer-local variable is non-@code{nil}, the size of any window
1014 displaying the buffer cannot normally be changed. Deleting a window or
1015 changing the frame's size may still change the window's size, if there
1018 If the value is @code{height}, then only the window's height is fixed;
1019 if the value is @code{width}, then only the window's width is fixed.
1020 Any other non-@code{nil} value fixes both the width and the height.
1022 If this variable is @code{nil}, this does not necessarily mean that any
1023 window showing the buffer can be resized in the desired direction. To
1024 determine that, use the function @code{window-resizable}.
1025 @xref{Resizing Windows}.
1028 Often @code{window-size-fixed} is overly aggressive because it inhibits
1029 any attempt to explicitly resize or split an affected window as well.
1030 This may even happen after the window has been resized implicitly, for
1031 example, when deleting an adjacent window or resizing the window's
1032 frame. The following function tries hard to never disallow resizing
1033 such a window explicitly:
1035 @defun window-preserve-size &optional window horizontal preserve
1036 This function (un-)marks the height of window @var{window} as preserved
1037 for future resize operations. @var{window} must be a live window and
1038 defaults to the selected one. If the optional argument @var{horizontal}
1039 is non-@code{nil}, it (un-)marks the width of @var{window} as preserved.
1041 If the optional argument @var{preserve} is @code{t}, this means to
1042 preserve the current height/width of @var{window}'s body. The
1043 height/width of @var{window} will change only if Emacs has no better
1044 choice. Resizing a window whose height/width is preserved by this
1045 function never throws an error.
1047 If @var{preserve} is @code{nil}, this means to stop preserving the
1048 height/width of @var{window}, lifting any respective restraint induced
1049 by a previous call of this function for @var{window}. Calling
1050 @code{enlarge-window}, @code{shrink-window} or
1051 @code{fit-window-to-buffer} with @var{window} as argument may also
1052 remove the respective restraint.
1055 @code{window-preserve-size} is currently invoked by the following
1059 @item fit-window-to-buffer
1060 If the optional argument @var{preserve-size} of that function
1061 (@pxref{Resizing Windows}) is non-@code{nil}, the size established by
1062 that function is preserved.
1064 @item display-buffer
1065 If the @var{alist} argument of that function (@pxref{Choosing Window})
1066 contains a @code{preserve-size} entry, the size of the window produced
1067 by that function is preserved.
1070 @code{window-preserve-size} installs a window parameter (@pxref{Window
1071 Parameters}) called @code{preserved-size} which is consulted by the
1072 window resizing functions. This parameter will not prevent resizing the
1073 window when the window shows another buffer than the one when
1074 @code{window-preserve-size} was invoked or if its size has changed since
1077 The following function can be used to check whether the height of a
1078 particular window is preserved:
1080 @defun window-preserved-size &optional window horizontal
1081 This function returns the preserved height of window @var{window} in
1082 pixels. @var{window} must be a live window and defaults to the selected
1083 one. If the optional argument @var{horizontal} is non-@code{nil}, it
1084 returns the preserved width of @var{window}. It returns @code{nil} if
1085 the size of @var{window} is not preserved.
1089 @node Splitting Windows
1090 @section Splitting Windows
1091 @cindex splitting windows
1092 @cindex window splitting
1094 This section describes functions for creating a new window by
1095 @dfn{splitting} an existing one.
1097 @defun split-window &optional window size side pixelwise
1098 This function creates a new live window next to the window
1099 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
1100 to the selected window. That window is split, and reduced in
1101 size. The space is taken up by the new window, which is returned.
1103 The optional second argument @var{size} determines the sizes of
1104 @var{window} and/or the new window. If it is omitted or @code{nil},
1105 both windows are given equal sizes; if there is an odd line, it is
1106 allocated to the new window. If @var{size} is a positive number,
1107 @var{window} is given @var{size} lines (or columns, depending on the
1108 value of @var{side}). If @var{size} is a negative number, the new
1109 window is given @minus{}@var{size} lines (or columns).
1111 If @var{size} is @code{nil}, this function obeys the variables
1112 @code{window-min-height} and @code{window-min-width} (@pxref{Window
1113 Sizes}). Thus, it signals an error if splitting would result in making
1114 a window smaller than those variables specify. However, a
1115 non-@code{nil} value for @var{size} causes those variables to be
1116 ignored; in that case, the smallest allowable window is considered to be
1117 one that has space for a text area one line tall and/or two columns
1120 Hence, if @var{size} is specified, it's the caller's responsibility to
1121 check whether the emanating windows are large enough to encompass all
1122 areas like a mode line or a scroll bar. The function
1123 @code{window-min-size} (@pxref{Window Sizes}) can be used to determine
1124 the minimum requirements of @var{window} in this regard. Since the new
1125 window usually inherits areas like the mode line or the scroll bar
1126 from @var{window}, that function is also a good guess for the minimum
1127 size of the new window. The caller should specify a smaller size only
1128 if it correspondingly removes an inherited area before the next
1131 The optional third argument @var{side} determines the position of the
1132 new window relative to @var{window}. If it is @code{nil} or
1133 @code{below}, the new window is placed below @var{window}. If it is
1134 @code{above}, the new window is placed above @var{window}. In both
1135 these cases, @var{size} specifies a total window height, in lines.
1137 If @var{side} is @code{t} or @code{right}, the new window is placed on
1138 the right of @var{window}. If @var{side} is @code{left}, the new
1139 window is placed on the left of @var{window}. In both these cases,
1140 @var{size} specifies a total window width, in columns.
1142 The optional fourth argument @var{pixelwise}, if non-@code{nil}, means
1143 to interpret @var{size} in units of pixels, instead of lines and
1146 If @var{window} is a live window, the new window inherits various
1147 properties from it, including margins and scroll bars. If
1148 @var{window} is an internal window, the new window inherits the
1149 properties of the window selected within @var{window}'s frame.
1151 The behavior of this function may be altered by the window parameters
1152 of @var{window}, so long as the variable
1153 @code{ignore-window-parameters} is @code{nil}. If the value of
1154 the @code{split-window} window parameter is @code{t}, this function
1155 ignores all other window parameters. Otherwise, if the value of the
1156 @code{split-window} window parameter is a function, that function is
1157 called with the arguments @var{window}, @var{size}, and @var{side}, in
1158 lieu of the usual action of @code{split-window}. Otherwise, this
1159 function obeys the @code{window-atom} or @code{window-side} window
1160 parameter, if any. @xref{Window Parameters}.
1163 As an example, here is a sequence of @code{split-window} calls that
1164 yields the window configuration discussed in @ref{Windows and Frames}.
1165 This example demonstrates splitting a live window as well as splitting
1166 an internal window. We begin with a frame containing a single window
1167 (a live root window), which we denote by @var{W4}. Calling
1168 @code{(split-window W4)} yields this window configuration:
1172 ______________________________________
1173 | ____________________________________ |
1177 ||_________________W4_________________||
1178 | ____________________________________ |
1182 ||_________________W5_________________||
1183 |__________________W3__________________|
1189 The @code{split-window} call has created a new live window, denoted by
1190 @var{W5}. It has also created a new internal window, denoted by
1191 @var{W3}, which becomes the root window and the parent of both
1192 @var{W4} and @var{W5}.
1194 Next, we call @code{(split-window W3 nil 'left)}, passing the
1195 internal window @var{W3} as the argument. The result:
1199 ______________________________________
1200 | ______ ____________________________ |
1201 || || __________________________ ||
1205 || |||____________W4____________|||
1206 || || __________________________ ||
1209 || |||____________W5____________|||
1210 ||__W2__||_____________W3_____________ |
1211 |__________________W1__________________|
1216 A new live window @var{W2} is created, to the left of the internal
1217 window @var{W3}. A new internal window @var{W1} is created, becoming
1218 the new root window.
1220 For interactive use, Emacs provides two commands which always split
1221 the selected window. These call @code{split-window} internally.
1223 @deffn Command split-window-right &optional size
1224 This function splits the selected window into two side-by-side
1225 windows, putting the selected window on the left. If @var{size} is
1226 positive, the left window gets @var{size} columns; if @var{size} is
1227 negative, the right window gets @minus{}@var{size} columns.
1230 @deffn Command split-window-below &optional size
1231 This function splits the selected window into two windows, one above
1232 the other, leaving the upper window selected. If @var{size} is
1233 positive, the upper window gets @var{size} lines; if @var{size} is
1234 negative, the lower window gets @minus{}@var{size} lines.
1237 @defopt split-window-keep-point
1238 If the value of this variable is non-@code{nil} (the default),
1239 @code{split-window-below} behaves as described above.
1241 If it is @code{nil}, @code{split-window-below} adjusts point in each
1242 of the two windows to minimize redisplay. (This is useful on slow
1243 terminals.) It selects whichever window contains the screen line that
1244 point was previously on. Note that this only affects
1245 @code{split-window-below}, not the lower-level @code{split-window}
1250 @node Deleting Windows
1251 @section Deleting Windows
1252 @cindex deleting windows
1254 @dfn{Deleting} a window removes it from the frame's window tree. If
1255 the window is a live window, it disappears from the screen. If the
1256 window is an internal window, its child windows are deleted too.
1258 Even after a window is deleted, it continues to exist as a Lisp
1259 object, until there are no more references to it. Window deletion can
1260 be reversed, by restoring a saved window configuration (@pxref{Window
1263 @deffn Command delete-window &optional window
1264 This function removes @var{window} from display and returns
1265 @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
1266 the selected window. If deleting the window would leave no more
1267 windows in the window tree (e.g., if it is the only live window in the
1268 frame), an error is signaled.
1270 By default, the space taken up by @var{window} is given to one of its
1271 adjacent sibling windows, if any. However, if the variable
1272 @code{window-combination-resize} is non-@code{nil}, the space is
1273 proportionally distributed among any remaining windows in the same
1274 window combination. @xref{Recombining Windows}.
1276 The behavior of this function may be altered by the window parameters
1277 of @var{window}, so long as the variable
1278 @code{ignore-window-parameters} is @code{nil}. If the value of
1279 the @code{delete-window} window parameter is @code{t}, this function
1280 ignores all other window parameters. Otherwise, if the value of the
1281 @code{delete-window} window parameter is a function, that function is
1282 called with the argument @var{window}, in lieu of the usual action of
1283 @code{delete-window}. Otherwise, this function obeys the
1284 @code{window-atom} or @code{window-side} window parameter, if any.
1285 @xref{Window Parameters}.
1288 @deffn Command delete-other-windows &optional window
1289 This function makes @var{window} fill its frame, by deleting other
1290 windows as necessary. If @var{window} is omitted or @code{nil}, it
1291 defaults to the selected window. The return value is @code{nil}.
1293 The behavior of this function may be altered by the window parameters
1294 of @var{window}, so long as the variable
1295 @code{ignore-window-parameters} is @code{nil}. If the value of
1296 the @code{delete-other-windows} window parameter is @code{t}, this
1297 function ignores all other window parameters. Otherwise, if the value
1298 of the @code{delete-other-windows} window parameter is a function,
1299 that function is called with the argument @var{window}, in lieu of the
1300 usual action of @code{delete-other-windows}. Otherwise, this function
1301 obeys the @code{window-atom} or @code{window-side} window parameter,
1302 if any. @xref{Window Parameters}.
1305 @deffn Command delete-windows-on &optional buffer-or-name frame
1306 This function deletes all windows showing @var{buffer-or-name}, by
1307 calling @code{delete-window} on those windows. @var{buffer-or-name}
1308 should be a buffer, or the name of a buffer; if omitted or @code{nil},
1309 it defaults to the current buffer. If there are no windows showing
1310 the specified buffer, this function does nothing. If the specified
1311 buffer is a minibuffer, an error is signaled.
1313 If there is a dedicated window showing the buffer, and that window is
1314 the only one on its frame, this function also deletes that frame if it
1315 is not the only frame on the terminal.
1317 The optional argument @var{frame} specifies which frames to operate
1322 means operate on all frames.
1324 means operate on the selected frame.
1325 @item @code{visible}
1326 means operate on all visible frames.
1328 means operate on all visible or iconified frames.
1330 means operate on that frame.
1333 Note that this argument does not have the same meaning as in other
1334 functions which scan all live windows (@pxref{Cyclic Window
1335 Ordering}). Specifically, the meanings of @code{t} and @code{nil} here
1336 are the opposite of what they are in those other functions.
1340 @node Recombining Windows
1341 @section Recombining Windows
1342 @cindex recombining windows
1343 @cindex windows, recombining
1345 When deleting the last sibling of a window @var{W}, its parent window
1346 is deleted too, with @var{W} replacing it in the window tree. This
1347 means that @var{W} must be recombined with its parent's siblings to
1348 form a new window combination (@pxref{Windows and Frames}). In some
1349 occasions, deleting a live window may even entail the deletion of two
1354 ______________________________________
1355 | ______ ____________________________ |
1356 || || __________________________ ||
1357 || ||| ___________ ___________ |||
1359 || ||||____W6_____||_____W7____||||
1360 || |||____________W4____________|||
1361 || || __________________________ ||
1364 || |||____________W5____________|||
1365 ||__W2__||_____________W3_____________ |
1366 |__________________W1__________________|
1372 Deleting @var{W5} in this configuration normally causes the deletion of
1373 @var{W3} and @var{W4}. The remaining live windows @var{W2},
1374 @var{W6} and @var{W7} are recombined to form a new horizontal
1375 combination with parent @var{W1}.
1377 Sometimes, however, it makes sense to not delete a parent window like
1378 @var{W4}. In particular, a parent window should not be removed when it
1379 was used to preserve a combination embedded in a combination of the same
1380 type. Such embeddings make sense to assure that when you split a window
1381 and subsequently delete the new window, Emacs reestablishes the layout
1382 of the associated frame as it existed before the splitting.
1384 Consider a scenario starting with two live windows @var{W2} and
1385 @var{W3} and their parent @var{W1}.
1389 ______________________________________
1390 | ____________________________________ |
1397 ||_________________W2_________________||
1398 | ____________________________________ |
1401 ||_________________W3_________________||
1402 |__________________W1__________________|
1408 Split @var{W2} to make a new window @var{W4} as follows.
1412 ______________________________________
1413 | ____________________________________ |
1416 ||_________________W2_________________||
1417 | ____________________________________ |
1420 ||_________________W4_________________||
1421 | ____________________________________ |
1424 ||_________________W3_________________||
1425 |__________________W1__________________|
1431 Now, when enlarging a window vertically, Emacs tries to obtain the
1432 corresponding space from its lower sibling, provided such a window
1433 exists. In our scenario, enlarging @var{W4} will steal space from
1438 ______________________________________
1439 | ____________________________________ |
1442 ||_________________W2_________________||
1443 | ____________________________________ |
1448 ||_________________W4_________________||
1449 | ____________________________________ |
1450 ||_________________W3_________________||
1451 |__________________W1__________________|
1457 Deleting @var{W4} will now give its entire space to @var{W2},
1458 including the space earlier stolen from @var{W3}.
1462 ______________________________________
1463 | ____________________________________ |
1472 ||_________________W2_________________||
1473 | ____________________________________ |
1474 ||_________________W3_________________||
1475 |__________________W1__________________|
1481 This can be counterintuitive, in particular if @var{W4} were used for
1482 displaying a buffer only temporarily (@pxref{Temporary Displays}), and
1483 you want to continue working with the initial layout.
1485 The behavior can be fixed by making a new parent window when splitting
1486 @var{W2}. The variable described next allows that to be done.
1488 @defopt window-combination-limit
1489 This variable controls whether splitting a window shall make a new
1490 parent window. The following values are recognized:
1494 This means that the new live window is allowed to share the existing
1495 parent window, if one exists, provided the split occurs in the same
1496 direction as the existing window combination (otherwise, a new internal
1497 window is created anyway).
1500 In this case @code{display-buffer} makes a new parent window if it is
1501 passed a @code{window-height} or @code{window-width} entry in the
1502 @var{alist} argument (@pxref{Display Action Functions}).
1505 This value causes the creation of a new parent window when a window is
1506 split for showing a temporary buffer (@pxref{Temporary Displays}) only.
1508 @item display-buffer
1509 This means that when @code{display-buffer} (@pxref{Choosing Window})
1510 splits a window it always makes a new parent window.
1513 In this case a new parent window is always created when splitting a
1514 window. Thus, if the value of this variable is at all times @code{t},
1515 then at all times every window tree is a binary tree (a tree where each
1516 window except the root window has exactly one sibling).
1519 The default is @code{nil}. Other values are reserved for future use.
1521 If, as a consequence of this variable's setting, @code{split-window}
1522 makes a new parent window, it also calls
1523 @code{set-window-combination-limit} (see below) on the newly-created
1524 internal window. This affects how the window tree is rearranged when
1525 the child windows are deleted (see below).
1528 If @code{window-combination-limit} is @code{t}, splitting @var{W2} in
1529 the initial configuration of our scenario would have produced this:
1533 ______________________________________
1534 | ____________________________________ |
1535 || __________________________________ ||
1537 |||________________W2________________|||
1538 || __________________________________ ||
1540 |||________________W4________________|||
1541 ||_________________W5_________________||
1542 | ____________________________________ |
1545 ||_________________W3_________________||
1546 |__________________W1__________________|
1552 A new internal window @var{W5} has been created; its children are
1553 @var{W2} and the new live window @var{W4}. Now, @var{W2} is the only
1554 sibling of @var{W4}, so enlarging @var{W4} will try to shrink
1555 @var{W2}, leaving @var{W3} unaffected. Observe that @var{W5}
1556 represents a vertical combination of two windows embedded in the
1557 vertical combination @var{W1}.
1559 @cindex window combination limit
1560 @defun set-window-combination-limit window limit
1561 This function sets the @dfn{combination limit} of the window
1562 @var{window} to @var{limit}. This value can be retrieved via the
1563 function @code{window-combination-limit}. See below for its effects;
1564 note that it is only meaningful for internal windows. The
1565 @code{split-window} function automatically calls this function, passing
1566 it @code{t} as @var{limit}, provided the value of the variable
1567 @code{window-combination-limit} is @code{t} when it is called.
1570 @defun window-combination-limit window
1571 This function returns the combination limit for @var{window}.
1573 The combination limit is meaningful only for an internal window. If it
1574 is @code{nil}, then Emacs is allowed to automatically delete
1575 @var{window}, in response to a window deletion, in order to group the
1576 child windows of @var{window} with its sibling windows to form a new
1577 window combination. If the combination limit is @code{t}, the child
1578 windows of @var{window} are never automatically recombined with its
1581 If, in the configuration shown at the beginning of this section, the
1582 combination limit of @var{W4} (the parent window of @var{W6} and
1583 @var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete
1587 Alternatively, the problems sketched above can be avoided by always
1588 resizing all windows in the same combination whenever one of its windows
1589 is split or deleted. This also permits splitting windows that would be
1590 otherwise too small for such an operation.
1592 @defopt window-combination-resize
1593 If this variable is @code{nil}, @code{split-window} can only split a
1594 window (denoted by @var{window}) if @var{window}'s screen area is large
1595 enough to accommodate both itself and the new window.
1597 If this variable is @code{t}, @code{split-window} tries to resize all
1598 windows that are part of the same combination as @var{window}, in order
1599 to accommodate the new window. In particular, this may allow
1600 @code{split-window} to succeed even if @var{window} is a fixed-size
1601 window or too small to ordinarily split. Furthermore, subsequently
1602 resizing or deleting @var{window} may resize all other windows in its
1605 The default is @code{nil}. Other values are reserved for future use.
1606 The value of this variable is ignored when
1607 @code{window-combination-limit} is non-@code{nil}.
1610 To illustrate the effect of @code{window-combination-resize}, consider
1611 the following frame layout.
1615 ______________________________________
1616 | ____________________________________ |
1621 ||_________________W2_________________||
1622 | ____________________________________ |
1627 ||_________________W3_________________||
1628 |__________________W1__________________|
1634 If @code{window-combination-resize} is @code{nil}, splitting window
1635 @var{W3} leaves the size of @var{W2} unchanged:
1639 ______________________________________
1640 | ____________________________________ |
1645 ||_________________W2_________________||
1646 | ____________________________________ |
1648 ||_________________W3_________________||
1649 | ____________________________________ |
1651 ||_________________W4_________________||
1652 |__________________W1__________________|
1658 If @code{window-combination-resize} is @code{t}, splitting @var{W3}
1659 instead leaves all three live windows with approximately the same
1664 ______________________________________
1665 | ____________________________________ |
1668 ||_________________W2_________________||
1669 | ____________________________________ |
1672 ||_________________W3_________________||
1673 | ____________________________________ |
1676 ||_________________W4_________________||
1677 |__________________W1__________________|
1683 Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will
1684 distribute its space proportionally among the two remaining live
1688 @node Selecting Windows
1689 @section Selecting Windows
1690 @cindex selecting a window
1692 @defun select-window window &optional norecord
1693 This function makes @var{window} the selected window and the window
1694 selected within its frame (@pxref{Basic Windows}) and selects that
1695 frame. It also makes @var{window}'s buffer (@pxref{Buffers and
1696 Windows}) current and sets that buffer's value of @code{point} to the
1697 value of @code{window-point} (@pxref{Window Point}) in @var{window}.
1698 @var{window} must be a live window. The return value is @var{window}.
1700 By default, this function also moves @var{window}'s buffer to the front
1701 of the buffer list (@pxref{Buffer List}), and makes @var{window} the
1702 most recently selected window. However, if the optional argument
1703 @var{norecord} is non-@code{nil}, these additional actions are omitted.
1705 This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
1706 unless @var{norecord} is non-@code{nil}. Note that applications and
1707 internal routines often temporarily select a window in order to simplify
1708 coding. As a rule, such selections (including those made by the macros
1709 @code{save-selected-window} and @code{with-selected-window} below) are
1710 not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
1711 Selections that really count are those causing a visible change in
1712 the next redisplay of @var{window}'s frame and should be always
1713 recorded. This also means that to run a function each time a window
1714 gets selected, putting it on @code{buffer-list-update-hook} should be
1718 @cindex most recently selected windows
1719 The sequence of calls to @code{select-window} with a non-@code{nil}
1720 @var{norecord} argument determines an ordering of windows by their
1721 selection time. The function @code{get-lru-window} can be used to
1722 retrieve the least recently selected live window (@pxref{Cyclic Window
1725 @defmac save-selected-window forms@dots{}
1726 This macro records the selected frame, as well as the selected window
1727 of each frame, executes @var{forms} in sequence, then restores the
1728 earlier selected frame and windows. It also saves and restores the
1729 current buffer. It returns the value of the last form in @var{forms}.
1731 This macro does not save or restore anything about the sizes,
1732 arrangement or contents of windows; therefore, if @var{forms} change
1733 them, the change persists. If the previously selected window of some
1734 frame is no longer live at the time of exit from @var{forms}, that
1735 frame's selected window is left alone. If the previously selected
1736 window is no longer live, then whatever window is selected at the end of
1737 @var{forms} remains selected. The current buffer is restored if and
1738 only if it is still live when exiting @var{forms}.
1740 This macro changes neither the ordering of recently selected windows nor
1744 @defmac with-selected-window window forms@dots{}
1745 This macro selects @var{window}, executes @var{forms} in sequence, then
1746 restores the previously selected window and current buffer. The ordering
1747 of recently selected windows and the buffer list remain unchanged unless
1748 you deliberately change them within @var{forms}; for example, by calling
1749 @code{select-window} with argument @var{norecord} @code{nil}.
1751 This macro does not change the order of recently selected windows or
1755 @defun frame-selected-window &optional frame
1756 This function returns the window on @var{frame} that is selected
1757 within that frame. @var{frame} should be a live frame; if omitted or
1758 @code{nil}, it defaults to the selected frame.
1761 @defun set-frame-selected-window frame window &optional norecord
1762 This function makes @var{window} the window selected within the frame
1763 @var{frame}. @var{frame} should be a live frame; if @code{nil}, it
1764 defaults to the selected frame. @var{window} should be a live window;
1765 if @code{nil}, it defaults to the selected window.
1767 If @var{frame} is the selected frame, this makes @var{window} the
1770 If the optional argument @var{norecord} is non-@code{nil}, this
1771 function does not alter the list of most recently selected windows,
1772 nor the buffer list.
1775 @cindex window use time
1776 @cindex use time of window
1777 @cindex window order by time of last use
1778 @defun window-use-time &optional window
1779 This functions returns the use time of window @var{window}.
1780 @var{window} must be a live window and defaults to the selected one.
1782 The @dfn{use time} of a window is not really a time value, but an
1783 integer that does increase monotonically with each call of
1784 @code{select-window} with a @code{nil} @var{norecord} argument. The
1785 window with the lowest use time is usually called the least recently
1786 used window while the window with the highest use time is called the
1787 most recently used one (@pxref{Cyclic Window Ordering}).
1791 @node Cyclic Window Ordering
1792 @section Cyclic Ordering of Windows
1793 @cindex cyclic ordering of windows
1794 @cindex ordering of windows, cyclic
1795 @cindex window ordering, cyclic
1797 When you use the command @kbd{C-x o} (@code{other-window}) to select
1798 some other window, it moves through live windows in a specific order.
1799 For any given configuration of windows, this order never varies. It
1800 is called the @dfn{cyclic ordering of windows}.
1802 The ordering is determined by a depth-first traversal of each frame's
1803 window tree, retrieving the live windows which are the leaf nodes of the
1804 tree (@pxref{Windows and Frames}). If the minibuffer is active, the
1805 minibuffer window is included too. The ordering is cyclic, so the last
1806 window in the sequence is followed by the first one.
1808 @defun next-window &optional window minibuf all-frames
1809 @cindex minibuffer window, and @code{next-window}
1810 This function returns a live window, the one following @var{window} in
1811 the cyclic ordering of windows. @var{window} should be a live window;
1812 if omitted or @code{nil}, it defaults to the selected window.
1814 The optional argument @var{minibuf} specifies whether minibuffer windows
1815 should be included in the cyclic ordering. Normally, when @var{minibuf}
1816 is @code{nil}, a minibuffer window is included only if it is currently
1817 active; this matches the behavior of @kbd{C-x o}. (Note that a
1818 minibuffer window is active as long as its minibuffer is in use; see
1821 If @var{minibuf} is @code{t}, the cyclic ordering includes all
1822 minibuffer windows. If @var{minibuf} is neither @code{t} nor
1823 @code{nil}, minibuffer windows are not included even if they are active.
1825 The optional argument @var{all-frames} specifies which frames to
1830 means to consider windows on @var{window}'s frame. If the minibuffer
1831 window is considered (as specified by the @var{minibuf} argument),
1832 then frames that share the minibuffer window are considered too.
1835 means to consider windows on all existing frames.
1837 @item @code{visible}
1838 means to consider windows on all visible frames.
1841 means to consider windows on all visible or iconified frames.
1844 means to consider windows on that specific frame.
1847 means to consider windows on @var{window}'s frame, and no others.
1850 If more than one frame is considered, the cyclic ordering is obtained
1851 by appending the orderings for those frames, in the same order as the
1852 list of all live frames (@pxref{Finding All Frames}).
1855 @defun previous-window &optional window minibuf all-frames
1856 This function returns a live window, the one preceding @var{window} in
1857 the cyclic ordering of windows. The other arguments are handled like
1858 in @code{next-window}.
1861 @deffn Command other-window count &optional all-frames
1862 This function selects a live window, one @var{count} places from the
1863 selected window in the cyclic ordering of windows. If @var{count} is
1864 a positive number, it skips @var{count} windows forwards; if
1865 @var{count} is negative, it skips @minus{}@var{count} windows
1866 backwards; if @var{count} is zero, that simply re-selects the selected
1867 window. When called interactively, @var{count} is the numeric prefix
1870 The optional argument @var{all-frames} has the same meaning as in
1871 @code{next-window}, like a @code{nil} @var{minibuf} argument to
1874 This function does not select a window that has a non-@code{nil}
1875 @code{no-other-window} window parameter (@pxref{Window Parameters}).
1878 @defun walk-windows fun &optional minibuf all-frames
1879 This function calls the function @var{fun} once for each live window,
1880 with the window as the argument.
1882 It follows the cyclic ordering of windows. The optional arguments
1883 @var{minibuf} and @var{all-frames} specify the set of windows
1884 included; these have the same arguments as in @code{next-window}. If
1885 @var{all-frames} specifies a frame, the first window walked is the
1886 first window on that frame (the one returned by
1887 @code{frame-first-window}), not necessarily the selected window.
1889 If @var{fun} changes the window configuration by splitting or deleting
1890 windows, that does not alter the set of windows walked, which is
1891 determined prior to calling @var{fun} for the first time.
1894 @defun one-window-p &optional no-mini all-frames
1895 This function returns @code{t} if the selected window is the only live
1896 window, and @code{nil} otherwise.
1898 If the minibuffer window is active, it is normally considered (so that
1899 this function returns @code{nil}). However, if the optional argument
1900 @var{no-mini} is non-@code{nil}, the minibuffer window is ignored even
1901 if active. The optional argument @var{all-frames} has the same
1902 meaning as for @code{next-window}.
1905 @cindex finding windows
1906 The following functions return a window which satisfies some
1907 criterion, without selecting it:
1909 @cindex least recently used window
1910 @defun get-lru-window &optional all-frames dedicated not-selected
1911 This function returns a live window which is heuristically the least
1912 recently used. The optional argument @var{all-frames} has
1913 the same meaning as in @code{next-window}.
1915 If any full-width windows are present, only those windows are
1916 considered. A minibuffer window is never a candidate. A dedicated
1917 window (@pxref{Dedicated Windows}) is never a candidate unless the
1918 optional argument @var{dedicated} is non-@code{nil}. The selected
1919 window is never returned, unless it is the only candidate. However, if
1920 the optional argument @var{not-selected} is non-@code{nil}, this
1921 function returns @code{nil} in that case.
1924 @cindex most recently used window
1925 @defun get-mru-window &optional all-frames dedicated not-selected
1926 This function is like @code{get-lru-window}, but it returns the most
1927 recently used window instead. The meaning of the arguments is the
1928 same as described for @code{get-lru-window}.
1931 @cindex largest window
1932 @defun get-largest-window &optional all-frames dedicated not-selected
1933 This function returns the window with the largest area (height times
1934 width). The optional argument @var{all-frames} specifies the windows to
1935 search, and has the same meaning as in @code{next-window}.
1937 A minibuffer window is never a candidate. A dedicated window
1938 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1939 argument @var{dedicated} is non-@code{nil}. The selected window is not
1940 a candidate if the optional argument @var{not-selected} is
1941 non-@code{nil}. If the optional argument @var{not-selected} is
1942 non-@code{nil} and the selected window is the only candidate, this
1943 function returns @code{nil}.
1945 If there are two candidate windows of the same size, this function
1946 prefers the one that comes first in the cyclic ordering of windows,
1947 starting from the selected window.
1950 @cindex window that satisfies a predicate
1951 @cindex conditional selection of windows
1952 @defun get-window-with-predicate predicate &optional minibuf all-frames default
1953 This function calls the function @var{predicate} for each of the
1954 windows in the cyclic order of windows in turn, passing it the window
1955 as an argument. If the predicate returns non-@code{nil} for any
1956 window, this function stops and returns that window. If no such
1957 window is found, the return value is @var{default} (which defaults to
1960 The optional arguments @var{minibuf} and @var{all-frames} specify the
1961 windows to search, and have the same meanings as in
1966 @node Buffers and Windows
1967 @section Buffers and Windows
1968 @cindex examining windows
1969 @cindex windows, controlling precisely
1970 @cindex buffers, controlled in windows
1972 This section describes low-level functions for examining and setting
1973 the contents of windows. @xref{Switching Buffers}, for higher-level
1974 functions for displaying a specific buffer in a window.
1976 @defun window-buffer &optional window
1977 This function returns the buffer that @var{window} is displaying. If
1978 @var{window} is omitted or @code{nil} it defaults to the selected
1979 window. If @var{window} is an internal window, this function returns
1983 @defun set-window-buffer window buffer-or-name &optional keep-margins
1984 This function makes @var{window} display @var{buffer-or-name}.
1985 @var{window} should be a live window; if @code{nil}, it defaults to
1986 the selected window. @var{buffer-or-name} should be a buffer, or the
1987 name of an existing buffer. This function does not change which
1988 window is selected, nor does it directly change which buffer is
1989 current (@pxref{Current Buffer}). Its return value is @code{nil}.
1991 If @var{window} is @dfn{strongly dedicated} to a buffer and
1992 @var{buffer-or-name} does not specify that buffer, this function
1993 signals an error. @xref{Dedicated Windows}.
1995 By default, this function resets @var{window}'s position, display
1996 margins, fringe widths, and scroll bar settings, based on the local
1997 variables in the specified buffer. However, if the optional argument
1998 @var{keep-margins} is non-@code{nil}, it leaves the display margins
1999 and fringe widths unchanged.
2001 When writing an application, you should normally use the higher-level
2002 functions described in @ref{Switching Buffers}, instead of calling
2003 @code{set-window-buffer} directly.
2005 This runs @code{window-scroll-functions}, followed by
2006 @code{window-configuration-change-hook}. @xref{Window Hooks}.
2009 @defvar buffer-display-count
2010 This buffer-local variable records the number of times a buffer has been
2011 displayed in a window. It is incremented each time
2012 @code{set-window-buffer} is called for the buffer.
2015 @defvar buffer-display-time
2016 This buffer-local variable records the time at which a buffer was last
2017 displayed in a window. The value is @code{nil} if the buffer has
2018 never been displayed. It is updated each time
2019 @code{set-window-buffer} is called for the buffer, with the value
2020 returned by @code{current-time} (@pxref{Time of Day}).
2023 @defun get-buffer-window &optional buffer-or-name all-frames
2024 This function returns the first window displaying @var{buffer-or-name}
2025 in the cyclic ordering of windows, starting from the selected window
2026 (@pxref{Cyclic Window Ordering}). If no such window exists, the
2027 return value is @code{nil}.
2029 @var{buffer-or-name} should be a buffer or the name of a buffer; if
2030 omitted or @code{nil}, it defaults to the current buffer. The
2031 optional argument @var{all-frames} specifies which windows to
2036 @code{t} means consider windows on all existing frames.
2038 @code{visible} means consider windows on all visible frames.
2040 0 means consider windows on all visible or iconified frames.
2042 A frame means consider windows on that frame only.
2044 Any other value means consider windows on the selected frame.
2047 Note that these meanings differ slightly from those of the
2048 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
2049 Ordering}). This function may be changed in a future version of Emacs
2050 to eliminate this discrepancy.
2053 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
2054 This function returns a list of all windows currently displaying
2055 @var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the
2056 name of an existing buffer. If omitted or @code{nil}, it defaults to
2057 the current buffer. If the currently selected window displays
2058 @var{buffer-or-name}, it will be the first in the list returned by
2061 The arguments @var{minibuf} and @var{all-frames} have the same
2062 meanings as in the function @code{next-window} (@pxref{Cyclic Window
2063 Ordering}). Note that the @var{all-frames} argument does @emph{not}
2064 behave exactly like in @code{get-buffer-window}.
2067 @deffn Command replace-buffer-in-windows &optional buffer-or-name
2068 This command replaces @var{buffer-or-name} with some other buffer, in
2069 all windows displaying it. @var{buffer-or-name} should be a buffer, or
2070 the name of an existing buffer; if omitted or @code{nil}, it defaults to
2073 The replacement buffer in each window is chosen via
2074 @code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated
2075 window displaying @var{buffer-or-name} is deleted if possible
2076 (@pxref{Dedicated Windows}). If such a window is the only window on its
2077 frame and there are other frames on the same terminal, the frame is
2078 deleted as well. If the dedicated window is the only window on the only
2079 frame on its terminal, the buffer is replaced anyway.
2083 @node Switching Buffers
2084 @section Switching to a Buffer in a Window
2085 @cindex switching to a buffer
2086 @cindex displaying a buffer
2088 This section describes high-level functions for switching to a specified
2089 buffer in some window. In general, ``switching to a buffer'' means to
2090 (1) show the buffer in some window, (2) make that window the selected
2091 window (and its frame the selected frame), and (3) make the buffer the
2094 Do @emph{not} use these functions to make a buffer temporarily
2095 current just so a Lisp program can access or modify it. They have
2096 side-effects, such as changing window histories (@pxref{Window
2097 History}), which will surprise the user if used that way. If you want
2098 to make a buffer current to modify it in Lisp, use
2099 @code{with-current-buffer}, @code{save-current-buffer}, or
2100 @code{set-buffer}. @xref{Current Buffer}.
2102 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
2103 This command attempts to display @var{buffer-or-name} in the selected
2104 window and make it the current buffer. It is often used interactively
2105 (as the binding of @kbd{C-x b}), as well as in Lisp programs. The
2106 return value is the buffer switched to.
2108 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2109 returned by @code{other-buffer} (@pxref{Buffer List}). If
2110 @var{buffer-or-name} is a string that is not the name of any existing
2111 buffer, this function creates a new buffer with that name; the new
2112 buffer's major mode is determined by the variable @code{major-mode}
2113 (@pxref{Major Modes}).
2115 Normally, the specified buffer is put at the front of the buffer
2116 list---both the global buffer list and the selected frame's buffer
2117 list (@pxref{Buffer List}). However, this is not done if the
2118 optional argument @var{norecord} is non-@code{nil}.
2120 Sometimes, the selected window may not be suitable for displaying the
2121 buffer. This happens if the selected window is a minibuffer window, or
2122 if the selected window is strongly dedicated to its buffer
2123 (@pxref{Dedicated Windows}). In such cases, the command normally tries
2124 to display the buffer in some other window, by invoking
2125 @code{pop-to-buffer} (see below).
2127 If the optional argument @var{force-same-window} is non-@code{nil} and
2128 the selected window is not suitable for displaying the buffer, this
2129 function always signals an error when called non-interactively. In
2130 interactive use, if the selected window is a minibuffer window, this
2131 function will try to use some other window instead. If the selected
2132 window is strongly dedicated to its buffer, the option
2133 @code{switch-to-buffer-in-dedicated-window} described next can be used
2137 @defopt switch-to-buffer-in-dedicated-window
2138 This option, if non-@code{nil}, allows @code{switch-to-buffer} to
2139 proceed when called interactively and the selected window is strongly
2140 dedicated to its buffer.
2142 The following values are respected:
2146 Disallows switching and signals an error as in non-interactive use.
2149 Prompts the user whether to allow switching.
2152 Invokes @code{pop-to-buffer} to proceed.
2155 Marks the selected window as non-dedicated and proceeds.
2158 This option does not affect non-interactive calls of
2159 @code{switch-to-buffer}.
2162 By default, @code{switch-to-buffer} shows the buffer at its position of
2163 @code{point}. This behavior can be tuned using the following option.
2165 @defopt switch-to-buffer-preserve-window-point
2166 If this variable is @code{nil}, @code{switch-to-buffer} displays the
2167 buffer specified by @var{buffer-or-name} at the position of that
2168 buffer's @code{point}. If this variable is @code{already-displayed}, it
2169 tries to display the buffer at its previous position in the selected
2170 window, provided the buffer is currently displayed in some other window
2171 on any visible or iconified frame. If this variable is @code{t},
2172 @code{switch-to-buffer} unconditionally tries to display the buffer at
2173 its previous position in the selected window.
2175 This variable is ignored if the buffer is already displayed in the
2176 selected window or never appeared in it before, or if
2177 @code{switch-to-buffer} calls @code{pop-to-buffer} to display the
2181 The next two commands are similar to @code{switch-to-buffer}, except for
2182 the described features.
2184 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
2185 This function displays the buffer specified by @var{buffer-or-name} in
2186 some window other than the selected window. It uses the function
2187 @code{pop-to-buffer} internally (see below).
2189 If the selected window already displays the specified buffer, it
2190 continues to do so, but another window is nonetheless found to display
2193 The @var{buffer-or-name} and @var{norecord} arguments have the same
2194 meanings as in @code{switch-to-buffer}.
2197 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
2198 This function displays the buffer specified by @var{buffer-or-name} in a
2199 new frame. It uses the function @code{pop-to-buffer} internally (see
2202 If the specified buffer is already displayed in another window, in any
2203 frame on the current terminal, this switches to that window instead of
2204 creating a new frame. However, the selected window is never used for
2207 The @var{buffer-or-name} and @var{norecord} arguments have the same
2208 meanings as in @code{switch-to-buffer}.
2211 The above commands use the function @code{pop-to-buffer}, which
2212 flexibly displays a buffer in some window and selects that window for
2213 editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for
2214 displaying the buffer. Hence, all the variables affecting
2215 @code{display-buffer} will affect it as well. @xref{Choosing Window},
2216 for the documentation of @code{display-buffer}.
2218 @deffn Command pop-to-buffer buffer-or-name &optional action norecord
2219 This function makes @var{buffer-or-name} the current buffer and
2220 displays it in some window, preferably not the window currently
2221 selected. It then selects the displaying window. If that window is
2222 on a different graphical frame, that frame is given input focus if
2223 possible (@pxref{Input Focus}). The return value is the buffer that
2226 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2227 returned by @code{other-buffer} (@pxref{Buffer List}). If
2228 @var{buffer-or-name} is a string that is not the name of any existing
2229 buffer, this function creates a new buffer with that name; the new
2230 buffer's major mode is determined by the variable @code{major-mode}
2231 (@pxref{Major Modes}).
2233 If @var{action} is non-@code{nil}, it should be a display action to
2234 pass to @code{display-buffer} (@pxref{Choosing Window}).
2235 Alternatively, a non-@code{nil}, non-list value means to pop to a
2236 window other than the selected one---even if the buffer is already
2237 displayed in the selected window.
2239 Like @code{switch-to-buffer}, this function updates the buffer list
2240 unless @var{norecord} is non-@code{nil}.
2244 @node Choosing Window
2245 @section Choosing a Window for Display
2247 The command @code{display-buffer} flexibly chooses a window for
2248 display, and displays a specified buffer in that window. It can be
2249 called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
2250 used as a subroutine by many functions and commands, including
2251 @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
2254 @cindex display action
2255 @cindex action function, for @code{display-buffer}
2256 @cindex action alist, for @code{display-buffer}
2257 This command performs several complex steps to find a window to
2258 display in. These steps are described by means of @dfn{display
2259 actions}, which have the form @code{(@var{function} . @var{alist})}.
2260 Here, @var{function} is either a function or a list of functions,
2261 which we refer to as @dfn{action functions}; @var{alist} is an
2262 association list, which we refer to as an @dfn{action alist}.
2264 An action function accepts two arguments: the buffer to display and
2265 an action alist. It attempts to display the buffer in some window,
2266 picking or creating a window according to its own criteria. If
2267 successful, it returns the window; otherwise, it returns @code{nil}.
2268 @xref{Display Action Functions}, for a list of predefined action
2271 @code{display-buffer} works by combining display actions from
2272 several sources, and calling the action functions in turn, until one
2273 of them manages to display the buffer and returns a non-@code{nil}
2276 @deffn Command display-buffer buffer-or-name &optional action frame
2277 This command makes @var{buffer-or-name} appear in some window, without
2278 selecting the window or making the buffer current. The argument
2279 @var{buffer-or-name} must be a buffer or the name of an existing
2280 buffer. The return value is the window chosen to display the buffer.
2282 The optional argument @var{action}, if non-@code{nil}, should normally
2283 be a display action (described above). @code{display-buffer} builds a
2284 list of action functions and an action alist, by consolidating display
2285 actions from the following sources (in order):
2289 The variable @code{display-buffer-overriding-action}.
2292 The user option @code{display-buffer-alist}.
2295 The @var{action} argument.
2298 The user option @code{display-buffer-base-action}.
2301 The constant @code{display-buffer-fallback-action}.
2305 Each action function is called in turn, passing the buffer as the
2306 first argument and the combined action alist as the second argument,
2307 until one of the functions returns non-@code{nil}. The caller can
2308 pass @code{(allow-no-window . t)} as an element of the action alist to
2309 indicate its readiness to handle the case of not displaying the
2312 The argument @var{action} can also have a non-@code{nil}, non-list
2313 value. This has the special meaning that the buffer should be
2314 displayed in a window other than the selected one, even if the
2315 selected window is already displaying it. If called interactively
2316 with a prefix argument, @var{action} is @code{t}.
2318 The optional argument @var{frame}, if non-@code{nil}, specifies which
2319 frames to check when deciding whether the buffer is already displayed.
2320 It is equivalent to adding an element @code{(reusable-frames
2321 . @var{frame})} to the action alist of @var{action}. @xref{Display
2325 @defvar display-buffer-overriding-action
2326 The value of this variable should be a display action, which is
2327 treated with the highest priority by @code{display-buffer}. The
2328 default value is empty, i.e., @code{(nil . nil)}.
2331 @defopt display-buffer-alist
2332 The value of this option is an alist mapping conditions to display
2333 actions. Each condition may be either a regular expression matching a
2334 buffer name or a function that takes two arguments: a buffer name and
2335 the @var{action} argument passed to @code{display-buffer}. If the name
2336 of the buffer passed to @code{display-buffer} either matches a regular
2337 expression in this alist or the function specified by a condition
2338 returns non-@code{nil}, then @code{display-buffer} uses the
2339 corresponding display action to display the buffer.
2342 @defopt display-buffer-base-action
2343 The value of this option should be a display action. This option can
2344 be used to define a standard display action for calls to
2345 @code{display-buffer}.
2348 @defvr Constant display-buffer-fallback-action
2349 This display action specifies the fallback behavior for
2350 @code{display-buffer} if no other display actions are given.
2354 @node Display Action Functions
2355 @section Action Functions for @code{display-buffer}
2357 The following basic action functions are defined in Emacs. Each of
2358 these functions takes two arguments: @var{buffer}, the buffer to
2359 display, and @var{alist}, an action alist. Each action function
2360 returns the window if it succeeds, and @code{nil} if it fails.
2362 @defun display-buffer-same-window buffer alist
2363 This function tries to display @var{buffer} in the selected window.
2364 It fails if the selected window is a minibuffer window or is dedicated
2365 to another buffer (@pxref{Dedicated Windows}). It also fails if
2366 @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
2369 @defun display-buffer-reuse-window buffer alist
2370 This function tries to display @var{buffer} by finding a window
2371 that is already displaying it.
2373 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2374 the selected window is not eligible for reuse. If @var{alist}
2375 contains a @code{reusable-frames} entry, its value determines which
2376 frames to search for a reusable window:
2380 @code{nil} means consider windows on the selected frame.
2381 (Actually, the last non-minibuffer frame.)
2383 @code{t} means consider windows on all frames.
2385 @code{visible} means consider windows on all visible frames.
2387 0 means consider windows on all visible or iconified frames.
2389 A frame means consider windows on that frame only.
2392 Note that these meanings differ slightly from those of the
2393 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
2396 If @var{alist} contains no @code{reusable-frames} entry, this function
2397 normally searches just the selected frame; however, if the variable
2398 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
2399 current terminal. @xref{Choosing Window Options}.
2401 If this function chooses a window on another frame, it makes that frame
2402 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
2403 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
2406 @defun display-buffer-pop-up-frame buffer alist
2407 This function creates a new frame, and displays the buffer in that
2408 frame's window. It actually performs the frame creation by calling
2409 the function specified in @code{pop-up-frame-function}
2410 (@pxref{Choosing Window Options}). If @var{alist} contains a
2411 @code{pop-up-frame-parameters} entry, the associated value
2412 is added to the newly created frame's parameters.
2415 @defun display-buffer-use-some-frame buffer alist
2416 This function tries to display @var{buffer} by trying to find a
2417 frame that meets a predicate (by default any frame other than the
2420 If this function chooses a window on another frame, it makes that frame
2421 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
2422 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
2424 If @var{alist} has a non-@code{nil} @code{frame-predicate} entry, its
2425 value is a function taking one argument (a frame), returning
2426 non-@code{nil} if the frame is a candidate; this function replaces the
2429 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2430 the selected window is used; thus if the selected frame has a single
2431 window, it is not used.
2434 @defun display-buffer-pop-up-window buffer alist
2435 This function tries to display @var{buffer} by splitting the largest
2436 or least recently-used window (typically one on the selected frame).
2437 It actually performs the split by calling the function specified in
2438 @code{split-window-preferred-function} (@pxref{Choosing Window
2441 The size of the new window can be adjusted by supplying
2442 @code{window-height} and @code{window-width} entries in @var{alist}. To
2443 adjust the window's height, use an entry whose @sc{car} is
2444 @code{window-height} and whose @sc{cdr} is one of:
2448 @code{nil} means to leave the height of the new window alone.
2451 A number specifies the desired height of the new window. An integer
2452 specifies the number of lines of the window. A floating-point
2453 number gives the fraction of the window's height with respect to the
2454 height of the frame's root window.
2457 If the @sc{cdr} specifies a function, that function is called with one
2458 argument: the new window. The function is supposed to adjust the
2459 height of the window; its return value is ignored. Suitable functions
2460 are @code{shrink-window-if-larger-than-buffer} and
2461 @code{fit-window-to-buffer}, see @ref{Resizing Windows}.
2464 To adjust the window's width, use an entry whose @sc{car} is
2465 @code{window-width} and whose @sc{cdr} is one of:
2469 @code{nil} means to leave the width of the new window alone.
2472 A number specifies the desired width of the new window. An integer
2473 specifies the number of columns of the window. A floating-point
2474 number gives the fraction of the window's width with respect to the
2475 width of the frame's root window.
2478 If the @sc{cdr} specifies a function, that function is called with one
2479 argument: the new window. The function is supposed to adjust the width
2480 of the window; its return value is ignored.
2483 If @var{alist} contains a @code{preserve-size} entry, Emacs will try to
2484 preserve the size of the new window during future resize operations
2485 (@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a
2486 cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width
2487 of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve
2488 the height of the window.
2490 This function can fail if no window splitting can be performed for some
2491 reason (e.g., if the selected frame has an @code{unsplittable} frame
2492 parameter; @pxref{Buffer Parameters}).
2495 @defun display-buffer-below-selected buffer alist
2496 This function tries to display @var{buffer} in a window below the
2497 selected window. This means to either split the selected window or use
2498 the window below the selected one. If it does create a new window, it
2499 will also adjust its size provided @var{alist} contains a suitable
2500 @code{window-height} or @code{window-width} entry, see above.
2503 @defun display-buffer-in-previous-window buffer alist
2504 This function tries to display @var{buffer} in a window previously
2505 showing it. If @var{alist} has a non-@code{nil}
2506 @code{inhibit-same-window} entry, the selected window is not eligible
2507 for reuse. If @var{alist} contains a @code{reusable-frames} entry, its
2508 value determines which frames to search for a suitable window as with
2509 @code{display-buffer-reuse-window}.
2511 If @var{alist} has a @code{previous-window} entry, the window
2512 specified by that entry will override any other window found by the
2513 methods above, even if that window never showed @var{buffer} before.
2516 @defun display-buffer-at-bottom buffer alist
2517 This function tries to display @var{buffer} in a window at the bottom
2518 of the selected frame.
2520 This either splits the window at the bottom of the frame or the
2521 frame's root window, or reuses an existing window at the bottom of the
2525 @defun display-buffer-use-some-window buffer alist
2526 This function tries to display @var{buffer} by choosing an existing
2527 window and displaying the buffer in that window. It can fail if all
2528 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
2531 @defun display-buffer-no-window buffer alist
2532 If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then
2533 this function does not display @code{buffer}. This allows you to
2534 override the default action and avoid displaying the buffer. It is
2535 assumed that when the caller specifies a non-@code{nil}
2536 @code{allow-no-window} value it can handle a @code{nil} value returned
2537 from @code{display-buffer} in this case.
2540 To illustrate the use of action functions, consider the following
2546 (get-buffer-create "*foo*")
2547 '((display-buffer-reuse-window
2548 display-buffer-pop-up-window
2549 display-buffer-pop-up-frame)
2550 (reusable-frames . 0)
2551 (window-height . 10) (window-width . 40)))
2556 Evaluating the form above will cause @code{display-buffer} to proceed as
2557 follows: If a buffer called *foo* already appears on a visible or
2558 iconified frame, it will reuse its window. Otherwise, it will try to
2559 pop up a new window or, if that is impossible, a new frame and show the
2560 buffer there. If all these steps fail, it will proceed using whatever
2561 @code{display-buffer-base-action} and
2562 @code{display-buffer-fallback-action} prescribe.
2564 Furthermore, @code{display-buffer} will try to adjust a reused window
2565 (provided *foo* was put by @code{display-buffer} there before) or a
2566 popped-up window as follows: If the window is part of a vertical
2567 combination, it will set its height to ten lines. Note that if, instead
2568 of the number 10, we specified the function
2569 @code{fit-window-to-buffer}, @code{display-buffer} would come up with a
2570 one-line window to fit the empty buffer. If the window is part of a
2571 horizontal combination, it sets its width to 40 columns. Whether a new
2572 window is vertically or horizontally combined depends on the shape of
2573 the window split and the values of
2574 @code{split-window-preferred-function}, @code{split-height-threshold}
2575 and @code{split-width-threshold} (@pxref{Choosing Window Options}).
2577 Now suppose we combine this call with a preexisting setup for
2578 @code{display-buffer-alist} as follows.
2582 (let ((display-buffer-alist
2585 (display-buffer-reuse-window display-buffer-below-selected)
2587 (window-height . 5))
2588 display-buffer-alist)))
2590 (get-buffer-create "*foo*")
2591 '((display-buffer-reuse-window
2592 display-buffer-pop-up-window
2593 display-buffer-pop-up-frame)
2594 (reusable-frames . 0)
2595 (window-height . 10) (window-width . 40))))
2600 This form will have @code{display-buffer} first try reusing a window
2601 that shows *foo* on the selected frame. If there's no such window, it
2602 will try to split the selected window or, if that is impossible, use the
2603 window below the selected window.
2605 If there's no window below the selected one, or the window below the
2606 selected one is dedicated to its buffer, @code{display-buffer} will
2607 proceed as described in the previous example. Note, however, that when
2608 it tries to adjust the height of any reused or popped-up window, it will
2609 in any case try to set its number of lines to 5 since that value
2610 overrides the corresponding specification in the @var{action} argument
2611 of @code{display-buffer}.
2614 @node Choosing Window Options
2615 @section Additional Options for Displaying Buffers
2617 The behavior of the standard display actions of @code{display-buffer}
2618 (@pxref{Choosing Window}) can be modified by a variety of user
2621 @defopt pop-up-windows
2622 If the value of this variable is non-@code{nil}, @code{display-buffer}
2623 is allowed to split an existing window to make a new window for
2624 displaying in. This is the default.
2626 This variable is provided mainly for backward compatibility. It is
2627 obeyed by @code{display-buffer} via a special mechanism in
2628 @code{display-buffer-fallback-action}, which only calls the action
2629 function @code{display-buffer-pop-up-window} (@pxref{Display Action
2630 Functions}) when the value is @code{nil}. It is not consulted by
2631 @code{display-buffer-pop-up-window} itself, which the user may specify
2632 directly in @code{display-buffer-alist} etc.
2635 @defopt split-window-preferred-function
2636 This variable specifies a function for splitting a window, in order to
2637 make a new window for displaying a buffer. It is used by the
2638 @code{display-buffer-pop-up-window} action function to actually split
2639 the window (@pxref{Display Action Functions}).
2641 The default value is @code{split-window-sensibly}, which is documented
2642 below. The value must be a function that takes one argument, a window,
2643 and return either a new window (which will be used to display the
2644 desired buffer) or @code{nil} (which means the splitting failed).
2647 @defun split-window-sensibly &optional window
2648 This function tries to split @var{window}, and return the newly created
2649 window. If @var{window} cannot be split, it returns @code{nil}. If
2650 @var{window} is omitted or @code{nil}, it defaults to the selected
2653 This function obeys the usual rules that determine when a window may
2654 be split (@pxref{Splitting Windows}). It first tries to split by
2655 placing the new window below, subject to the restriction imposed by
2656 @code{split-height-threshold} (see below), in addition to any other
2657 restrictions. If that fails, it tries to split by placing the new
2658 window to the right, subject to @code{split-width-threshold} (see
2659 below). If that fails, and the window is the only window on its
2660 frame, this function again tries to split and place the new window
2661 below, disregarding @code{split-height-threshold}. If this fails as
2662 well, this function gives up and returns @code{nil}.
2665 @defopt split-height-threshold
2666 This variable, used by @code{split-window-sensibly}, specifies whether
2667 to split the window placing the new window below. If it is an
2668 integer, that means to split only if the original window has at least
2669 that many lines. If it is @code{nil}, that means not to split this
2673 @defopt split-width-threshold
2674 This variable, used by @code{split-window-sensibly}, specifies whether
2675 to split the window placing the new window to the right. If the value
2676 is an integer, that means to split only if the original window has at
2677 least that many columns. If the value is @code{nil}, that means not
2681 @defopt even-window-sizes
2682 This variable, if non-@code{nil}, causes @code{display-buffer} to even
2683 window sizes whenever it reuses an existing window and that window is
2684 adjacent to the selected one.
2686 If its value is @code{width-only}, sizes are evened only if the reused
2687 window is on the left or right of the selected one and the selected
2688 window is wider than the reused one. If its value is @code{height-only}
2689 sizes are evened only if the reused window is above or beneath the
2690 selected window and the selected window is higher than the reused one.
2691 Any other non-@code{nil} value means to even sizes in any of these cases
2692 provided the selected window is larger than the reused one in the sense
2693 of their combination.
2696 @defopt pop-up-frames
2697 If the value of this variable is non-@code{nil}, that means
2698 @code{display-buffer} may display buffers by making new frames. The
2699 default is @code{nil}.
2701 A non-@code{nil} value also means that when @code{display-buffer} is
2702 looking for a window already displaying @var{buffer-or-name}, it can
2703 search any visible or iconified frame, not just the selected frame.
2705 This variable is provided mainly for backward compatibility. It is
2706 obeyed by @code{display-buffer} via a special mechanism in
2707 @code{display-buffer-fallback-action}, which calls the action function
2708 @code{display-buffer-pop-up-frame} (@pxref{Display Action Functions})
2709 if the value is non-@code{nil}. (This is done before attempting to
2710 split a window.) This variable is not consulted by
2711 @code{display-buffer-pop-up-frame} itself, which the user may specify
2712 directly in @code{display-buffer-alist} etc.
2715 @defopt pop-up-frame-function
2716 This variable specifies a function for creating a new frame, in order
2717 to make a new window for displaying a buffer. It is used by the
2718 @code{display-buffer-pop-up-frame} action function (@pxref{Display
2721 The value should be a function that takes no arguments and returns a
2722 frame, or @code{nil} if no frame could be created. The default value
2723 is a function that creates a frame using the parameters specified by
2724 @code{pop-up-frame-alist} (see below).
2727 @defopt pop-up-frame-alist
2728 This variable holds an alist of frame parameters (@pxref{Frame
2729 Parameters}), which is used by the default function in
2730 @code{pop-up-frame-function} to make a new frame. The default is
2734 @defopt same-window-buffer-names
2735 A list of buffer names for buffers that should be displayed in the
2736 selected window. If a buffer's name is in this list,
2737 @code{display-buffer} handles the buffer by showing it in the selected
2741 @defopt same-window-regexps
2742 A list of regular expressions that specify buffers that should be
2743 displayed in the selected window. If the buffer's name matches any of
2744 the regular expressions in this list, @code{display-buffer} handles the
2745 buffer by showing it in the selected window.
2748 @defun same-window-p buffer-name
2749 This function returns @code{t} if displaying a buffer
2750 named @var{buffer-name} with @code{display-buffer} would
2751 put it in the selected window.
2754 @node Window History
2755 @section Window History
2756 @cindex window history
2758 Each window remembers in a list the buffers it has previously displayed,
2759 and the order in which these buffers were removed from it. This history
2760 is used, for example, by @code{replace-buffer-in-windows}
2761 (@pxref{Buffers and Windows}). The list is automatically maintained by
2762 Emacs, but you can use the following functions to explicitly inspect or
2765 @defun window-prev-buffers &optional window
2766 This function returns a list specifying the previous contents of
2767 @var{window}. The optional argument @var{window} should be a live
2768 window and defaults to the selected one.
2770 Each list element has the form @code{(@var{buffer} @var{window-start}
2771 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
2772 the window, @var{window-start} is the window start position
2773 (@pxref{Window Start and End}) when that buffer was last shown, and
2774 @var{window-pos} is the point position (@pxref{Window Point}) when
2775 that buffer was last shown in @var{window}.
2777 The list is ordered so that earlier elements correspond to more
2778 recently-shown buffers, and the first element usually corresponds to the
2779 buffer most recently removed from the window.
2782 @defun set-window-prev-buffers window prev-buffers
2783 This function sets @var{window}'s previous buffers to the value of
2784 @var{prev-buffers}. The argument @var{window} must be a live window
2785 and defaults to the selected one. The argument @var{prev-buffers}
2786 should be a list of the same form as that returned by
2787 @code{window-prev-buffers}.
2790 In addition, each buffer maintains a list of @dfn{next buffers}, which
2791 is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
2792 below). This list is mainly used by @code{switch-to-prev-buffer} and
2793 @code{switch-to-next-buffer} for choosing buffers to switch to.
2795 @defun window-next-buffers &optional window
2796 This function returns the list of buffers recently re-shown in
2797 @var{window} via @code{switch-to-prev-buffer}. The @var{window}
2798 argument must denote a live window or @code{nil} (meaning the selected
2802 @defun set-window-next-buffers window next-buffers
2803 This function sets the next buffer list of @var{window} to
2804 @var{next-buffers}. The @var{window} argument should be a live window
2805 or @code{nil} (meaning the selected window). The argument
2806 @var{next-buffers} should be a list of buffers.
2809 The following commands can be used to cycle through the global buffer
2810 list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
2811 they cycle according to the specified window's history list, rather
2812 than the global buffer list. In addition, they restore
2813 window-specific window start and point positions, and may show a
2814 buffer even if it is already shown in another window. The
2815 @code{switch-to-prev-buffer} command, in particular, is used by
2816 @code{replace-buffer-in-windows}, @code{bury-buffer} and
2817 @code{quit-window} to find a replacement buffer for a window.
2819 @deffn Command switch-to-prev-buffer &optional window bury-or-kill
2820 This command displays the previous buffer in @var{window}. The
2821 argument @var{window} should be a live window or @code{nil} (meaning
2822 the selected window). If the optional argument @var{bury-or-kill} is
2823 non-@code{nil}, this means that the buffer currently shown in
2824 @var{window} is about to be buried or killed and consequently should
2825 not be switched to in future invocations of this command.
2827 The previous buffer is usually the buffer shown before the buffer
2828 currently shown in @var{window}. However, a buffer that has been buried
2829 or killed, or has been already shown by a recent invocation of
2830 @code{switch-to-prev-buffer}, does not qualify as previous buffer.
2832 If repeated invocations of this command have already shown all buffers
2833 previously shown in @var{window}, further invocations will show buffers
2834 from the buffer list of the frame @var{window} appears on (@pxref{Buffer
2835 List}), trying to skip buffers that are already shown in another window
2839 @deffn Command switch-to-next-buffer &optional window
2840 This command switches to the next buffer in @var{window}, thus undoing
2841 the effect of the last @code{switch-to-prev-buffer} command in
2842 @var{window}. The argument @var{window} must be a live window and
2843 defaults to the selected one.
2845 If there is no recent invocation of @code{switch-to-prev-buffer} that
2846 can be undone, this function tries to show a buffer from the buffer list
2847 of the frame @var{window} appears on (@pxref{Buffer List}).
2850 By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
2851 can switch to a buffer that is already shown in another window on the
2852 same frame. The following option can be used to override this behavior.
2854 @defopt switch-to-visible-buffer
2855 If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
2856 @code{switch-to-next-buffer} may switch to a buffer that is already
2857 visible on the same frame, provided the buffer was shown in the
2858 relevant window before. If it is @code{nil},
2859 @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always
2860 try to avoid switching to a buffer that is already visible in another
2861 window on the same frame. The default is @code{t}.
2865 @node Dedicated Windows
2866 @section Dedicated Windows
2867 @cindex dedicated window
2869 Functions for displaying a buffer can be told to not use specific
2870 windows by marking these windows as @dfn{dedicated} to their buffers.
2871 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
2872 window for displaying another buffer in it. @code{get-lru-window} and
2873 @code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not
2874 consider dedicated windows as candidates when their @var{dedicated}
2875 argument is non-@code{nil}. The behavior of @code{set-window-buffer}
2876 (@pxref{Buffers and Windows}) with respect to dedicated windows is
2877 slightly different, see below.
2879 Functions supposed to remove a buffer from a window or a window from
2880 a frame can behave specially when a window they operate on is dedicated.
2881 We will distinguish three basic cases, namely where (1) the window is
2882 not the only window on its frame, (2) the window is the only window on
2883 its frame but there are other frames on the same terminal left, and (3)
2884 the window is the only window on the only frame on the same terminal.
2886 In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
2887 handles case (2) by deleting the associated frame and case (3) by
2888 showing another buffer in that frame's only window. The function
2889 @code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
2890 called when a buffer gets killed, deletes the window in case (1) and
2891 behaves like @code{delete-windows-on} otherwise.
2892 @c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
2894 When @code{bury-buffer} (@pxref{Buffer List}) operates on the
2895 selected window (which shows the buffer that shall be buried), it
2896 handles case (2) by calling @code{frame-auto-hide-function}
2897 (@pxref{Quitting Windows}) to deal with the selected frame. The other
2898 two cases are handled as with @code{replace-buffer-in-windows}.
2900 @defun window-dedicated-p &optional window
2901 This function returns non-@code{nil} if @var{window} is dedicated to its
2902 buffer and @code{nil} otherwise. More precisely, the return value is
2903 the value assigned by the last call of @code{set-window-dedicated-p} for
2904 @var{window}, or @code{nil} if that function was never called with
2905 @var{window} as its argument. The default for @var{window} is the
2909 @defun set-window-dedicated-p window flag
2910 This function marks @var{window} as dedicated to its buffer if
2911 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
2913 As a special case, if @var{flag} is @code{t}, @var{window} becomes
2914 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
2915 signals an error when the window it acts upon is strongly dedicated to
2916 its buffer and does not already display the buffer it is asked to
2917 display. Other functions do not treat @code{t} differently from any
2918 non-@code{nil} value.
2922 @node Quitting Windows
2923 @section Quitting Windows
2925 When you want to get rid of a window used for displaying a buffer, you
2926 can call @code{delete-window} or @code{delete-windows-on}
2927 (@pxref{Deleting Windows}) to remove that window from its frame. If the
2928 buffer is shown on a separate frame, you might want to call
2929 @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
2930 hand, a window has been reused for displaying the buffer, you might
2931 prefer showing the buffer previously shown in that window, by calling the
2932 function @code{switch-to-prev-buffer} (@pxref{Window History}).
2933 Finally, you might want to either bury (@pxref{Buffer List}) or kill
2934 (@pxref{Killing Buffers}) the window's buffer.
2936 The following command uses information on how the window for
2937 displaying the buffer was obtained in the first place, thus attempting
2938 to automate the above decisions for you.
2940 @deffn Command quit-window &optional kill window
2941 This command quits @var{window} and buries its buffer. The argument
2942 @var{window} must be a live window and defaults to the selected one.
2943 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
2944 instead of burying it. It calls the function @code{quit-restore-window}
2945 described next to deal with the window and its buffer.
2948 @defun quit-restore-window &optional window bury-or-kill
2949 This function tries to restore the state of @var{window} that existed
2950 before its buffer was displayed in it. The optional argument
2951 @var{window} must be a live window and defaults to the selected one.
2953 If @var{window} was created specially for displaying its buffer, this
2954 function deletes @var{window} provided its frame contains at least one
2955 other live window. If @var{window} is the only window on its frame and
2956 there are other frames on the frame's terminal, the value of the
2957 optional argument @var{bury-or-kill} determines how to proceed with the
2958 window. If @var{bury-or-kill} equals @code{kill}, the frame is deleted
2959 unconditionally. Otherwise, the fate of the frame is determined by
2960 calling @code{frame-auto-hide-function} (see below) with that frame as
2963 Otherwise, this function tries to redisplay the buffer previously shown
2964 in @var{window}. It also tries to restore the window start
2965 (@pxref{Window Start and End}) and point (@pxref{Window Point})
2966 positions of the previously shown buffer. If, in addition,
2967 @var{window}'s buffer was temporarily resized, this function will also
2968 try to restore the original height of @var{window}.
2970 The cases described so far require that the buffer shown in @var{window}
2971 is still the buffer displayed by the last buffer display function for
2972 this window. If another buffer has been shown in the meantime, or the
2973 buffer previously shown no longer exists, this function calls
2974 @code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
2977 The optional argument @var{bury-or-kill} specifies how to deal with
2978 @var{window}'s buffer. The following values are handled:
2982 This means to not deal with the buffer in any particular way. As a
2983 consequence, if @var{window} is not deleted, invoking
2984 @code{switch-to-prev-buffer} will usually show the buffer again.
2987 This means that if @var{window} is not deleted, its buffer is moved to
2988 the end of @var{window}'s list of previous buffers, so it's less likely
2989 that a future invocation of @code{switch-to-prev-buffer} will switch to
2990 it. Also, it moves the buffer to the end of the frame's buffer list.
2993 This means that if @var{window} is not deleted, its buffer is removed
2994 from @var{window}'s list of previous buffers. Also, it moves the buffer
2995 to the end of the frame's buffer list. This value provides the most
2996 reliable remedy to not have @code{switch-to-prev-buffer} switch to this
2997 buffer again without killing the buffer.
3000 This means to kill @var{window}'s buffer.
3003 @code{quit-restore-window} bases its decisions on information stored in
3004 @var{window}'s @code{quit-restore} window parameter (@pxref{Window
3005 Parameters}), and resets that parameter to @code{nil} after it's done.
3008 The following option specifies how to deal with a frame containing just
3009 one window that should be either quit, or whose buffer should be buried.
3011 @defopt frame-auto-hide-function
3012 The function specified by this option is called to automatically hide
3013 frames. This function is called with one argument---a frame.
3015 The function specified here is called by @code{bury-buffer}
3016 (@pxref{Buffer List}) when the selected window is dedicated and shows
3017 the buffer to bury. It is also called by @code{quit-restore-window}
3018 (see above) when the frame of the window to quit has been specially
3019 created for displaying that window's buffer and the buffer is not
3022 The default is to call @code{iconify-frame} (@pxref{Visibility of
3023 Frames}). Alternatively, you may specify either @code{delete-frame}
3024 (@pxref{Deleting Frames}) to remove the frame from its display,
3025 @code{ignore} to leave the frame unchanged, or any other function that
3026 can take a frame as its sole argument.
3028 Note that the function specified by this option is called only if the
3029 specified frame contains just one live window and there is at least one
3030 other frame on the same terminal.
3035 @section Windows and Point
3036 @cindex window position
3037 @cindex window point
3038 @cindex position in window
3039 @cindex point in window
3041 Each window has its own value of point (@pxref{Point}), independent of
3042 the value of point in other windows displaying the same buffer. This
3043 makes it useful to have multiple windows showing one buffer.
3047 The window point is established when a window is first created; it is
3048 initialized from the buffer's point, or from the window point of another
3049 window opened on the buffer if such a window exists.
3052 Selecting a window sets the value of point in its buffer from the
3053 window's value of point. Conversely, deselecting a window sets the
3054 window's value of point from that of the buffer. Thus, when you switch
3055 between windows that display a given buffer, the point value for the
3056 selected window is in effect in the buffer, while the point values for
3057 the other windows are stored in those windows.
3060 As long as the selected window displays the current buffer, the window's
3061 point and the buffer's point always move together; they remain equal.
3065 As far as the user is concerned, point is where the cursor is, and
3066 when the user switches to another buffer, the cursor jumps to the
3067 position of point in that buffer.
3069 @defun window-point &optional window
3070 This function returns the current position of point in @var{window}.
3071 For a nonselected window, this is the value point would have (in that
3072 window's buffer) if that window were selected. The default for
3073 @var{window} is the selected window.
3075 When @var{window} is the selected window, the value returned is the
3076 value of point in that window's buffer. Strictly speaking, it would be
3077 more correct to return the top-level value of point, outside of any
3078 @code{save-excursion} forms. But that value is hard to find.
3081 @defun set-window-point window position
3082 This function positions point in @var{window} at position
3083 @var{position} in @var{window}'s buffer. It returns @var{position}.
3085 If @var{window} is selected, this simply does @code{goto-char} in
3086 @var{window}'s buffer.
3089 @defvar window-point-insertion-type
3090 This variable specifies the marker insertion type (@pxref{Marker
3091 Insertion Types}) of @code{window-point}. The default is @code{nil},
3092 so @code{window-point} will stay behind text inserted there.
3095 @node Window Start and End
3096 @section The Window Start and End Positions
3097 @cindex window start position
3098 @cindex display-start position
3100 Each window maintains a marker used to keep track of a buffer position
3101 that specifies where in the buffer display should start. This position
3102 is called the @dfn{display-start} position of the window (or just the
3103 @dfn{start}). The character after this position is the one that appears
3104 at the upper left corner of the window. It is usually, but not
3105 inevitably, at the beginning of a text line.
3107 After switching windows or buffers, and in some other cases, if the
3108 window start is in the middle of a line, Emacs adjusts the window
3109 start to the start of a line. This prevents certain operations from
3110 leaving the window start at a meaningless point within a line. This
3111 feature may interfere with testing some Lisp code by executing it
3112 using the commands of Lisp mode, because they trigger this
3113 readjustment. To test such code, put it into a command and bind the
3116 @defun window-start &optional window
3117 @cindex window top line
3118 This function returns the display-start position of window
3119 @var{window}. If @var{window} is @code{nil}, the selected window is
3122 When you create a window, or display a different buffer in it, the
3123 display-start position is set to a display-start position recently used
3124 for the same buffer, or to @code{point-min} if the buffer doesn't have
3127 Redisplay updates the window-start position (if you have not specified
3128 it explicitly since the previous redisplay)---to make sure point appears
3129 on the screen. Nothing except redisplay automatically changes the
3130 window-start position; if you move point, do not expect the window-start
3131 position to change in response until after the next redisplay.
3134 @defun window-group-start &optional window
3135 @vindex window-group-start-function
3136 This function is like @code{window-start}, except that when
3137 @var{window} is a part of a group of windows (@pxref{Window Group}),
3138 @code{window-group-start} returns the start position of the entire
3139 group. This condition holds when the buffer local variable
3140 @code{window-group-start-function} is set to a function. In this
3141 case, @code{window-group-start} calls the function with the single
3142 argument @var{window}, then returns its result.
3145 @cindex window end position
3146 @defun window-end &optional window update
3147 This function returns the position where display of its buffer ends in
3148 @var{window}. The default for @var{window} is the selected window.
3150 Simply changing the buffer text or moving point does not update the
3151 value that @code{window-end} returns. The value is updated only when
3152 Emacs redisplays and redisplay completes without being preempted.
3154 If the last redisplay of @var{window} was preempted, and did not finish,
3155 Emacs does not know the position of the end of display in that window.
3156 In that case, this function returns @code{nil}.
3158 If @var{update} is non-@code{nil}, @code{window-end} always returns an
3159 up-to-date value for where display ends, based on the current
3160 @code{window-start} value. If a previously saved value of that position
3161 is still valid, @code{window-end} returns that value; otherwise it
3162 computes the correct value by scanning the buffer text.
3164 Even if @var{update} is non-@code{nil}, @code{window-end} does not
3165 attempt to scroll the display if point has moved off the screen, the
3166 way real redisplay would do. It does not alter the
3167 @code{window-start} value. In effect, it reports where the displayed
3168 text will end if scrolling is not required.
3171 @vindex window-group-end-function
3172 @defun window-group-end &optional window update
3173 This function is like @code{window-end}, except that when @var{window}
3174 is a part of a group of windows (@pxref{Window Group}),
3175 @code{window-group-end} returns the end position of the entire group.
3176 This condition holds when the buffer local variable
3177 @code{window-group-end-function} is set to a function. In this case,
3178 @code{window-group-end} calls the function with the two arguments
3179 @var{window} and @var{update}, then returns its result. The argument
3180 @var{update} has the same meaning as in @code{window-end}.
3183 @defun set-window-start window position &optional noforce
3184 This function sets the display-start position of @var{window} to
3185 @var{position} in @var{window}'s buffer. It returns @var{position}.
3187 The display routines insist that the position of point be visible when a
3188 buffer is displayed. Normally, they change the display-start position
3189 (that is, scroll the window) whenever necessary to make point visible.
3190 However, if you specify the start position with this function using
3191 @code{nil} for @var{noforce}, it means you want display to start at
3192 @var{position} even if that would put the location of point off the
3193 screen. If this does place point off screen, the display routines move
3194 point to the left margin on the middle line in the window.
3196 For example, if point @w{is 1} and you set the start of the window
3197 @w{to 37}, the start of the next line, point will be above the top
3198 of the window. The display routines will automatically move point if
3199 it is still 1 when redisplay occurs. Here is an example:
3203 ;; @r{Here is what @samp{foo} looks like before executing}
3204 ;; @r{the @code{set-window-start} expression.}
3208 ---------- Buffer: foo ----------
3209 @point{}This is the contents of buffer foo.
3215 ---------- Buffer: foo ----------
3229 ;; @r{Here is what @samp{foo} looks like after executing}
3230 ;; @r{the @code{set-window-start} expression.}
3231 ---------- Buffer: foo ----------
3237 ---------- Buffer: foo ----------
3241 If @var{noforce} is non-@code{nil}, and @var{position} would place point
3242 off screen at the next redisplay, then redisplay computes a new window-start
3243 position that works well with point, and thus @var{position} is not used.
3246 @vindex set-window-group-start-function
3247 @defun set-window-group-start window position &optional noforce
3248 This function is like @code{set-window-start}, except that when
3249 @var{window} is a part of a group of windows (@pxref{Window Group}),
3250 @code{set-window-group-start} sets the start position of the entire
3251 group. This condition holds when the buffer local variable
3252 @code{set-window-group-start-function} is set to a function. In this
3253 case, @code{set-window-group-start} calls the function with the three
3254 arguments @var{window}, @var{position}, and @var{noforce}, then
3255 returns its result. The arguments @var{position} and @var{noforce} in
3256 this function have the same meaning as in @code{set-window-start}.
3259 @defun pos-visible-in-window-p &optional position window partially
3260 This function returns non-@code{nil} if @var{position} is within the
3261 range of text currently visible on the screen in @var{window}. It
3262 returns @code{nil} if @var{position} is scrolled vertically out of
3263 view. Locations that are partially obscured are not considered
3264 visible unless @var{partially} is non-@code{nil}. The argument
3265 @var{position} defaults to the current position of point in
3266 @var{window}; @var{window} defaults to the selected window. If
3267 @var{position} is @code{t}, that means to check either the first
3268 visible position of the last screen line in @var{window}, or the
3269 end-of-buffer position, whichever comes first.
3271 This function considers only vertical scrolling. If @var{position} is
3272 out of view only because @var{window} has been scrolled horizontally,
3273 @code{pos-visible-in-window-p} returns non-@code{nil} anyway.
3274 @xref{Horizontal Scrolling}.
3276 If @var{position} is visible, @code{pos-visible-in-window-p} returns
3277 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
3278 non-@code{nil}, and the character following @var{position} is fully
3279 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
3280 @var{x} and @var{y} are the pixel coordinates relative to the top left
3281 corner of the window; otherwise it returns an extended list of the form
3282 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
3283 where @var{rtop} and @var{rbot} specify the number of off-window pixels
3284 at the top and bottom of the row at @var{position}, @var{rowh} specifies
3285 the visible height of that row, and @var{vpos} specifies the vertical
3286 position (zero-based row number) of that row.
3292 ;; @r{If point is off the screen now, recenter it now.}
3293 (or (pos-visible-in-window-p
3294 (point) (selected-window))
3300 @vindex pos-visible-in-window-group-p-function
3301 @defun pos-visible-in-window-group-p &optional position window partially
3302 This function is like @code{pos-visible-in-window-p}, except that when
3303 @var{window} is a part of a group of windows (@pxref{Window Group}),
3304 @code{pos-visible-in-window-group-p} tests the visibility of @var{pos}
3305 in the entire group, not just in the single @var{window}. This
3306 condition holds when the buffer local variable
3307 @code{pos-visible-in-window-group-p-function} is set to a function.
3308 In this case @code{pos-visible-in-window-group-p} calls the function
3309 with the three arguments @var{position}, @var{window}, and
3310 @var{partially}, then returns its result. The arguments
3311 @var{position} and @var{partially} have the same meaning as in
3312 @code{pos-visible-in-window-p}.
3315 @defun window-line-height &optional line window
3316 This function returns the height of text line @var{line} in
3317 @var{window}. If @var{line} is one of @code{header-line} or
3318 @code{mode-line}, @code{window-line-height} returns information about
3319 the corresponding line of the window. Otherwise, @var{line} is a text
3320 line number starting from 0. A negative number counts from the end of
3321 the window. The default for @var{line} is the current line in
3322 @var{window}; the default for @var{window} is the selected window.
3324 If the display is not up to date, @code{window-line-height} returns
3325 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
3326 to obtain related information.
3328 If there is no line corresponding to the specified @var{line},
3329 @code{window-line-height} returns @code{nil}. Otherwise, it returns
3330 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
3331 where @var{height} is the height in pixels of the visible part of the
3332 line, @var{vpos} and @var{ypos} are the vertical position in lines and
3333 pixels of the line relative to the top of the first text line, and
3334 @var{offbot} is the number of off-window pixels at the bottom of the
3335 text line. If there are off-window pixels at the top of the (first)
3336 text line, @var{ypos} is negative.
3339 @node Textual Scrolling
3340 @section Textual Scrolling
3341 @cindex textual scrolling
3342 @cindex scrolling textually
3344 @dfn{Textual scrolling} means moving the text up or down through a
3345 window. It works by changing the window's display-start location. It
3346 may also change the value of @code{window-point} to keep point on the
3347 screen (@pxref{Window Point}).
3349 The basic textual scrolling functions are @code{scroll-up} (which
3350 scrolls forward) and @code{scroll-down} (which scrolls backward). In
3351 these function names, ``up'' and ``down'' refer to the direction of
3352 motion of the buffer text relative to the window. Imagine that the
3353 text is written on a long roll of paper and that the scrolling
3354 commands move the paper up and down. Thus, if you are looking at the
3355 middle of a buffer and repeatedly call @code{scroll-down}, you will
3356 eventually see the beginning of the buffer.
3358 Unfortunately, this sometimes causes confusion, because some people
3359 tend to think in terms of the opposite convention: they
3360 imagine the window moving over text that remains in place, so that
3361 ``down'' commands take you to the end of the buffer. This convention
3362 is consistent with fact that such a command is bound to a key named
3363 @key{PageDown} on modern keyboards.
3365 We have not switched to this convention as that is likely to break
3366 existing Emacs Lisp code.
3369 Textual scrolling functions (aside from @code{scroll-other-window})
3370 have unpredictable results if the current buffer is not the one
3371 displayed in the selected window. @xref{Current Buffer}.
3373 If the window contains a row taller than the height of the window
3374 (for example in the presence of a large image), the scroll functions
3375 will adjust the window's vertical scroll position to scroll the
3376 partially visible row. Lisp callers can disable this feature by
3377 binding the variable @code{auto-window-vscroll} to @code{nil}
3378 (@pxref{Vertical Scrolling}).
3380 @deffn Command scroll-up &optional count
3381 This function scrolls forward by @var{count} lines in the selected
3384 If @var{count} is negative, it scrolls backward instead. If
3385 @var{count} is @code{nil} (or omitted), the distance scrolled is
3386 @code{next-screen-context-lines} lines less than the height of the
3389 If the selected window cannot be scrolled any further, this function
3390 signals an error. Otherwise, it returns @code{nil}.
3393 @deffn Command scroll-down &optional count
3394 This function scrolls backward by @var{count} lines in the selected
3397 If @var{count} is negative, it scrolls forward instead. In other
3398 respects, it behaves the same way as @code{scroll-up} does.
3401 @deffn Command scroll-up-command &optional count
3402 This behaves like @code{scroll-up}, except that if the selected window
3403 cannot be scrolled any further and the value of the variable
3404 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3405 end of the buffer instead. If point is already there, it signals an
3409 @deffn Command scroll-down-command &optional count
3410 This behaves like @code{scroll-down}, except that if the selected
3411 window cannot be scrolled any further and the value of the variable
3412 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3413 beginning of the buffer instead. If point is already there, it
3417 @deffn Command scroll-other-window &optional count
3418 This function scrolls the text in another window upward @var{count}
3419 lines. Negative values of @var{count}, or @code{nil}, are handled
3420 as in @code{scroll-up}.
3422 You can specify which buffer to scroll by setting the variable
3423 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
3424 already displayed, @code{scroll-other-window} displays it in some
3427 When the selected window is the minibuffer, the next window is normally
3428 the leftmost one immediately above it. You can specify a different
3429 window to scroll, when the minibuffer is selected, by setting the variable
3430 @code{minibuffer-scroll-window}. This variable has no effect when any
3431 other window is selected. When it is non-@code{nil} and the
3432 minibuffer is selected, it takes precedence over
3433 @code{other-window-scroll-buffer}. @xref{Definition of
3434 minibuffer-scroll-window}.
3436 When the minibuffer is active, it is the next window if the selected
3437 window is the one at the bottom right corner. In this case,
3438 @code{scroll-other-window} attempts to scroll the minibuffer. If the
3439 minibuffer contains just one line, it has nowhere to scroll to, so the
3440 line reappears after the echo area momentarily displays the message
3441 @samp{End of buffer}.
3444 @defvar other-window-scroll-buffer
3445 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
3446 which buffer's window to scroll.
3449 @defopt scroll-margin
3450 This option specifies the size of the scroll margin---a minimum number
3451 of lines between point and the top or bottom of a window. Whenever
3452 point gets within this many lines of the top or bottom of the window,
3453 redisplay scrolls the text automatically (if possible) to move point
3454 out of the margin, closer to the center of the window.
3457 @defopt scroll-conservatively
3458 This variable controls how scrolling is done automatically when point
3459 moves off the screen (or into the scroll margin). If the value is a
3460 positive integer @var{n}, then redisplay scrolls the text up to
3461 @var{n} lines in either direction, if that will bring point back into
3462 proper view. This behavior is called @dfn{conservative scrolling}.
3463 Otherwise, scrolling happens in the usual way, under the control of
3464 other variables such as @code{scroll-up-aggressively} and
3465 @code{scroll-down-aggressively}.
3467 The default value is zero, which means that conservative scrolling
3471 @defopt scroll-down-aggressively
3472 The value of this variable should be either @code{nil} or a fraction
3473 @var{f} between 0 and 1. If it is a fraction, that specifies where on
3474 the screen to put point when scrolling down. More precisely, when a
3475 window scrolls down because point is above the window start, the new
3476 start position is chosen to put point @var{f} part of the window
3477 height from the top. The larger @var{f}, the more aggressive the
3480 A value of @code{nil} is equivalent to .5, since its effect is to center
3481 point. This variable automatically becomes buffer-local when set in any
3485 @defopt scroll-up-aggressively
3486 Likewise, for scrolling up. The value, @var{f}, specifies how far
3487 point should be placed from the bottom of the window; thus, as with
3488 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
3492 This variable is an older variant of @code{scroll-conservatively}.
3493 The difference is that if its value is @var{n}, that permits scrolling
3494 only by precisely @var{n} lines, not a smaller number. This feature
3495 does not work with @code{scroll-margin}. The default value is zero.
3498 @cindex @code{scroll-command} property
3499 @defopt scroll-preserve-screen-position
3500 If this option is @code{t}, whenever a scrolling command moves point
3501 off-window, Emacs tries to adjust point to keep the cursor at its old
3502 vertical position in the window, rather than the window edge.
3504 If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
3505 to keep the cursor at the same vertical position, even if the
3506 scrolling command didn't move point off-window.
3508 This option affects all scroll commands that have a non-@code{nil}
3509 @code{scroll-command} symbol property.
3512 @defopt next-screen-context-lines
3513 The value of this variable is the number of lines of continuity to
3514 retain when scrolling by full screens. For example, @code{scroll-up}
3515 with an argument of @code{nil} scrolls so that this many lines at the
3516 bottom of the window appear instead at the top. The default value is
3520 @defopt scroll-error-top-bottom
3521 If this option is @code{nil} (the default), @code{scroll-up-command}
3522 and @code{scroll-down-command} simply signal an error when no more
3523 scrolling is possible.
3525 If the value is @code{t}, these commands instead move point to the
3526 beginning or end of the buffer (depending on scrolling direction);
3527 only if point is already on that position do they signal an error.
3530 @deffn Command recenter &optional count
3531 @cindex centering point
3532 This function scrolls the text in the selected window so that point is
3533 displayed at a specified vertical position within the window. It does
3534 not move point with respect to the text.
3536 If @var{count} is a non-negative number, that puts the line containing
3537 point @var{count} lines down from the top of the window. If
3538 @var{count} is a negative number, then it counts upward from the
3539 bottom of the window, so that @minus{}1 stands for the last usable
3542 If @var{count} is @code{nil} (or a non-@code{nil} list),
3543 @code{recenter} puts the line containing point in the middle of the
3544 window. If @var{count} is @code{nil}, this function may redraw the
3545 frame, according to the value of @code{recenter-redisplay}.
3547 When @code{recenter} is called interactively, @var{count} is the raw
3548 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
3549 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
3550 @var{count} to 4, which positions the current line four lines from the
3553 With an argument of zero, @code{recenter} positions the current line at
3554 the top of the window. The command @code{recenter-top-bottom} offers
3555 a more convenient way to achieve this.
3558 @vindex recenter-window-group-function
3559 @defun recenter-window-group &optional count
3560 This function is like @code{recenter}, except that when the selected
3561 window is part of a group of windows (@pxref{Window Group}),
3562 @code{recenter-window-group} scrolls the entire group. This condition
3563 holds when the buffer local variable
3564 @code{recenter-window-group-function} is set to a function. In this
3565 case, @code{recenter-window-group} calls the function with the
3566 argument @var{count}, then returns its result. The argument
3567 @var{count} has the same meaning as in @code{recenter}, but with
3568 respect to the entire window group.
3571 @defopt recenter-redisplay
3572 If this variable is non-@code{nil}, calling @code{recenter} with a
3573 @code{nil} argument redraws the frame. The default value is
3574 @code{tty}, which means only redraw the frame if it is a tty frame.
3577 @deffn Command recenter-top-bottom &optional count
3578 This command, which is the default binding for @kbd{C-l}, acts like
3579 @code{recenter}, except if called with no argument. In that case,
3580 successive calls place point according to the cycling order defined
3581 by the variable @code{recenter-positions}.
3584 @defopt recenter-positions
3585 This variable controls how @code{recenter-top-bottom} behaves when
3586 called with no argument. The default value is @code{(middle top
3587 bottom)}, which means that successive calls of
3588 @code{recenter-top-bottom} with no argument cycle between placing
3589 point at the middle, top, and bottom of the window.
3593 @node Vertical Scrolling
3594 @section Vertical Fractional Scrolling
3595 @cindex vertical fractional scrolling
3596 @cindex vertical scroll position
3598 @dfn{Vertical fractional scrolling} means shifting text in a window
3599 up or down by a specified multiple or fraction of a line. Each window
3600 has a @dfn{vertical scroll position}, which is a number, never less than
3601 zero. It specifies how far to raise the contents of the window.
3602 Raising the window contents generally makes all or part of some lines
3603 disappear off the top, and all or part of some other lines appear at the
3604 bottom. The usual value is zero.
3606 The vertical scroll position is measured in units of the normal line
3607 height, which is the height of the default font. Thus, if the value is
3608 .5, that means the window contents are scrolled up half the normal line
3609 height. If it is 3.3, that means the window contents are scrolled up
3610 somewhat over three times the normal line height.
3612 What fraction of a line the vertical scrolling covers, or how many
3613 lines, depends on what the lines contain. A value of .5 could scroll a
3614 line whose height is very short off the screen, while a value of 3.3
3615 could scroll just part of the way through a tall line or an image.
3617 @defun window-vscroll &optional window pixels-p
3618 This function returns the current vertical scroll position of
3619 @var{window}. The default for @var{window} is the selected window.
3620 If @var{pixels-p} is non-@code{nil}, the return value is measured in
3621 pixels, rather than in units of the normal line height.
3631 @defun set-window-vscroll window lines &optional pixels-p
3632 This function sets @var{window}'s vertical scroll position to
3633 @var{lines}. If @var{window} is @code{nil}, the selected window is
3634 used. The argument @var{lines} should be zero or positive; if not, it
3638 The actual vertical scroll position must always correspond
3639 to an integral number of pixels, so the value you specify
3640 is rounded accordingly.
3642 The return value is the result of this rounding.
3646 (set-window-vscroll (selected-window) 1.2)
3651 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
3652 pixels. In this case, the return value is @var{lines}.
3655 @defvar auto-window-vscroll
3656 If this variable is non-@code{nil}, the @code{line-move},
3657 @code{scroll-up}, and @code{scroll-down} functions will automatically
3658 modify the vertical scroll position to scroll through display rows
3659 that are taller than the height of the window, for example in the
3660 presence of large images.
3663 @node Horizontal Scrolling
3664 @section Horizontal Scrolling
3665 @cindex horizontal scrolling
3667 @dfn{Horizontal scrolling} means shifting the image in the window left
3668 or right by a specified multiple of the normal character width. Each
3669 window has a @dfn{horizontal scroll position}, which is a number, never
3670 less than zero. It specifies how far to shift the contents left.
3671 Shifting the window contents left generally makes all or part of some
3672 characters disappear off the left, and all or part of some other
3673 characters appear at the right. The usual value is zero.
3675 The horizontal scroll position is measured in units of the normal
3676 character width, which is the width of space in the default font. Thus,
3677 if the value is 5, that means the window contents are scrolled left by 5
3678 times the normal character width. How many characters actually
3679 disappear off to the left depends on their width, and could vary from
3682 Because we read from side to side in the inner loop, and from top
3683 to bottom in the outer loop, the effect of horizontal scrolling is
3684 not like that of textual or vertical scrolling. Textual scrolling
3685 involves selection of a portion of text to display, and vertical
3686 scrolling moves the window contents contiguously; but horizontal
3687 scrolling causes part of @emph{each line} to go off screen.
3689 Usually, no horizontal scrolling is in effect; then the leftmost
3690 column is at the left edge of the window. In this state, scrolling to
3691 the right is meaningless, since there is no data to the left of the edge
3692 to be revealed by it; so this is not allowed. Scrolling to the left is
3693 allowed; it scrolls the first columns of text off the edge of the window
3694 and can reveal additional columns on the right that were truncated
3695 before. Once a window has a nonzero amount of leftward horizontal
3696 scrolling, you can scroll it back to the right, but only so far as to
3697 reduce the net horizontal scroll to zero. There is no limit to how far
3698 left you can scroll, but eventually all the text will disappear off the
3701 @vindex auto-hscroll-mode
3702 If @code{auto-hscroll-mode} is set, redisplay automatically alters
3703 the horizontal scrolling of a window as necessary to ensure that point
3704 is always visible. However, you can still set the horizontal
3705 scrolling value explicitly. The value you specify serves as a lower
3706 bound for automatic scrolling, i.e., automatic scrolling will not
3707 scroll a window to a column less than the specified one.
3709 @deffn Command scroll-left &optional count set-minimum
3710 This function scrolls the selected window @var{count} columns to the
3711 left (or to the right if @var{count} is negative). The default
3712 for @var{count} is the window width, minus 2.
3714 The return value is the total amount of leftward horizontal scrolling in
3715 effect after the change---just like the value returned by
3716 @code{window-hscroll} (below).
3718 Note that text in paragraphs whose base direction is right-to-left
3719 (@pxref{Bidirectional Display}) moves in the opposite direction: e.g.,
3720 it moves to the right when @code{scroll-left} is invoked with a
3721 positive value of @var{count}.
3723 Once you scroll a window as far right as it can go, back to its normal
3724 position where the total leftward scrolling is zero, attempts to scroll
3725 any farther right have no effect.
3727 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
3728 the lower bound for automatic scrolling; that is, automatic scrolling
3729 will not scroll a window to a column less than the value returned by
3730 this function. Interactive calls pass non-@code{nil} for
3734 @deffn Command scroll-right &optional count set-minimum
3735 This function scrolls the selected window @var{count} columns to the
3736 right (or to the left if @var{count} is negative). The default
3737 for @var{count} is the window width, minus 2. Aside from the direction
3738 of scrolling, this works just like @code{scroll-left}.
3741 @defun window-hscroll &optional window
3742 This function returns the total leftward horizontal scrolling of
3743 @var{window}---the number of columns by which the text in @var{window}
3744 is scrolled left past the left margin. (In right-to-left paragraphs,
3745 the value is the total amount of the rightward scrolling instead.)
3746 The default for @var{window} is the selected window.
3748 The return value is never negative. It is zero when no horizontal
3749 scrolling has been done in @var{window} (which is usually the case).
3768 @defun set-window-hscroll window columns
3769 This function sets horizontal scrolling of @var{window}. The value of
3770 @var{columns} specifies the amount of scrolling, in terms of columns
3771 from the left margin (right margin in right-to-left paragraphs). The
3772 argument @var{columns} should be zero or positive; if not, it is taken
3773 as zero. Fractional values of @var{columns} are not supported at
3776 Note that @code{set-window-hscroll} may appear not to work if you test
3777 it by evaluating a call with @kbd{M-:} in a simple way. What happens
3778 is that the function sets the horizontal scroll value and returns, but
3779 then redisplay adjusts the horizontal scrolling to make point visible,
3780 and this overrides what the function did. You can observe the
3781 function's effect if you call it while point is sufficiently far from
3782 the left margin that it will remain visible.
3784 The value returned is @var{columns}.
3788 (set-window-hscroll (selected-window) 10)
3794 Here is how you can determine whether a given position @var{position}
3795 is off the screen due to horizontal scrolling:
3797 @c FIXME: Maybe hscroll-on-screen-p is a better name?
3800 (defun hscroll-on-screen (window position)
3802 (goto-char position)
3804 (>= (- (current-column) (window-hscroll window)) 0)
3805 (< (- (current-column) (window-hscroll window))
3806 (window-width window)))))
3811 @node Coordinates and Windows
3812 @section Coordinates and Windows
3813 @cindex frame-relative coordinate
3814 @cindex coordinate, relative to frame
3815 @cindex window position
3817 This section describes functions that report the position of a window.
3818 Most of these functions report positions relative to an origin at the
3819 native position of the window's frame (@pxref{Frame Geometry}). Some
3820 functions report positions relative to the origin of the display of the
3821 window's frame. In any case, the origin has the coordinates (0, 0) and
3822 X and Y coordinates increase rightward and downward
3825 For the following functions, X and Y coordinates are reported in
3826 integer character units, i.e., numbers of lines and columns
3827 respectively. On a graphical display, each ``line'' and ``column''
3828 corresponds to the height and width of the default character specified by
3829 the frame's default font (@pxref{Frame Font}).
3831 @defun window-edges &optional window body absolute pixelwise
3832 This function returns a list of the edge coordinates of @var{window}.
3833 If @var{window} is omitted or @code{nil}, it defaults to the selected
3836 The return value has the form @code{(@var{left} @var{top} @var{right}
3837 @var{bottom})}. These list elements are, respectively, the X
3838 coordinate of the leftmost column occupied by the window, the Y
3839 coordinate of the topmost row, the X coordinate one column to the
3840 right of the rightmost column, and the Y coordinate one row down from
3843 Note that these are the actual outer edges of the window, including any
3844 header line, mode line, scroll bar, fringes, window divider and display
3845 margins. On a text terminal, if the window has a neighbor on its right,
3846 its right edge includes the separator line between the window and its
3849 If the optional argument @var{body} is @code{nil}, this means to
3850 return the edges corresponding to the total size of @var{window}.
3851 @var{body} non-@code{nil} means to return the edges of @var{window}'s
3852 body (aka text area). If @var{body} is non-@code{nil}, @var{window}
3853 must specify a live window.
3855 If the optional argument @var{absolute} is @code{nil}, this means to
3856 return edges relative to the native position of @var{window}'s frame.
3857 @var{absolute} non-@code{nil} means to return coordinates relative to
3858 the origin (0, 0) of @var{window}'s display. On non-graphical systems
3859 this argument has no effect.
3861 If the optional argument @var{pixelwise} is @code{nil}, this means to
3862 return the coordinates in terms of the default character width and
3863 height of @var{window}'s frame (@pxref{Frame Font}), rounded if
3864 necessary. @var{pixelwise} non-@code{nil} means to return the
3865 coordinates in pixels. Note that the pixel specified by @var{right} and
3866 @var{bottom} is immediately outside of these edges. If @var{absolute}
3867 is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too.
3870 @defun window-body-edges &optional window
3871 This function returns the edges of @var{window}'s body (@pxref{Window
3872 Sizes}). Calling @code{(window-body-edges window)} is equivalent to
3873 calling @code{(window-edges window t)}, see above.
3876 @comment The following two functions are confusing and hardly used.
3878 @defun window-left-column &optional window
3879 This function returns the leftmost column of @var{window}. This value
3880 equals the @var{left} entry in the list returned by @code{(window-edges
3881 window)} minus the number of columns occupied by the internal border of
3882 @var{window}'s frame.
3885 @defun window-top-line &optional window
3886 This function returns the topmost row of @var{window}. This value is
3887 equal to the @var{top} entry in the list returned by @code{(window-edges
3888 window)} minus the number of lines occupied by the internal border of
3889 @var{window}'s frame.
3893 The following functions can be used to relate a set of
3894 frame-relative coordinates to a window:
3896 @defun window-at x y &optional frame
3897 This function returns the live window at the coordinates @var{x} and
3898 @var{y} given in default character sizes (@pxref{Frame Font}) relative
3899 to the native position of @var{frame} (@pxref{Frame Geometry}).
3901 If there is no window at that position, the return value is @code{nil}.
3902 If @var{frame} is omitted or @code{nil}, it defaults to the selected
3906 @defun coordinates-in-window-p coordinates window
3907 This function checks whether a window @var{window} occupies the frame
3908 relative coordinates @var{coordinates}, and if so, which part of the
3909 window that is. @var{window} should be a live window.
3911 @var{coordinates} should be a cons cell of the form @code{(@var{x}
3912 . @var{y})}, where @var{x} and @var{y} are given in default character
3913 sizes (@pxref{Frame Font}) relative to the native position of
3914 @var{window}'s frame (@pxref{Frame Geometry}).
3916 If there is no window at the specified position, the return value is
3917 @code{nil} . Otherwise, the return value is one of the following:
3920 @item (@var{relx} . @var{rely})
3921 The coordinates are inside @var{window}. The numbers @var{relx} and
3922 @var{rely} are the equivalent window-relative coordinates for the
3923 specified position, counting from 0 at the top left corner of the
3927 The coordinates are in the mode line of @var{window}.
3930 The coordinates are in the header line of @var{window}.
3933 The coordinates are in the divider separating @var{window} from a
3934 window on the right.
3936 @item bottom-divider
3937 The coordinates are in the divider separating @var{window} from a
3941 The coordinates are in the vertical line between @var{window} and its
3942 neighbor to the right. This value occurs only if the window doesn't
3943 have a scroll bar; positions in a scroll bar are considered outside the
3944 window for these purposes.
3948 The coordinates are in the left or right fringe of the window.
3952 The coordinates are in the left or right margin of the window.
3955 The coordinates are not in any part of @var{window}.
3958 The function @code{coordinates-in-window-p} does not require a frame as
3959 argument because it always uses the frame that @var{window} is on.
3962 The following functions return window positions in pixels, rather
3963 than character units. Though mostly useful on graphical displays,
3964 they can also be called on text terminals, where the screen area of
3965 each text character is taken to be one pixel.
3967 @defun window-pixel-edges &optional window
3968 This function returns a list of pixel coordinates for the edges of
3969 @var{window}. Calling @code{(window-pixel-edges window)} is equivalent
3970 to calling @code{(window-edges window nil nil t)}, see above.
3973 @comment The following two functions are confusing and hardly used.
3975 @defun window-pixel-left &optional window
3976 This function returns the left pixel edge of window @var{window}. This
3977 value equals the @var{left} entry in the list returned by
3978 @code{(window-pixel-edges window)} minus the number of pixels occupied
3979 by the internal border of @var{window}'s frame. @var{window} must be a
3980 valid window and defaults to the selected one.
3983 @defun window-pixel-top &optional window
3984 This function returns the top pixel edge of window @var{window}. This
3985 value is equal to the @var{top} entry in the list returned by
3986 @code{(window-pixel-edges window)} minus the number of pixels occupied
3987 by the internal border of @var{window}'s frame. @var{window} must be a
3988 valid window and defaults to the selected one.
3992 @defun window-body-pixel-edges &optional window
3993 This function returns the pixel edges of @var{window}'s body. Calling
3994 @code{(window-body-pixel-edges window)} is equivalent to calling
3995 @code{(window-edges window t nil t)}, see above.
3998 The following functions return window positions in pixels, relative to
3999 the origin of the display screen rather than that of the frame:
4001 @defun window-absolute-pixel-edges &optional window
4002 This function returns the pixel coordinates of @var{WINDOW} relative to
4003 an origin at (0, 0) of the display of @var{window}'s frame. Calling
4004 @code{(window-absolute-pixel-edges)} is equivalent to calling
4005 @code{(window-edges window nil t t)}, see above.
4008 @defun window-absolute-body-pixel-edges &optional window
4009 This function returns the pixel coordinates of @var{WINDOW}'s body
4010 relative to an origin at (0, 0) of the display of @var{window}'s frame.
4011 Calling @code{(window-absolute-body-pixel-edges window)} is equivalent
4012 to calling @code{(window-edges window t t t)}, see above.
4014 Combined with @code{set-mouse-absolute-pixel-position}, this function
4015 can be used to move the mouse pointer to an arbitrary buffer position
4016 visible in some window:
4020 (let ((edges (window-absolute-body-pixel-edges))
4021 (position (pos-visible-in-window-p nil nil t)))
4022 (set-mouse-absolute-pixel-position
4023 (+ (nth 0 edges) (nth 0 position))
4024 (+ (nth 1 edges) (nth 1 position))))
4028 On a graphical terminal this form ``warps'' the mouse cursor to the
4029 upper left corner of the glyph at the selected window's point. A
4030 position calculated this way can be also used to show a tooltip window
4034 The following function returns the screen coordinates of a buffer
4035 position visible in a window:
4037 @defun window-absolute-pixel-position &optional position window
4038 If the buffer position @var{position} is visible in window @var{window},
4039 this function returns the display coordinates of the upper/left corner
4040 of the glyph at @var{position}. The return value is a cons of the X-
4041 and Y-coordinates of that corner, relative to an origin at (0, 0) of
4042 @var{window}'s display. It returns @code{nil} if @var{position} is not
4043 visible in @var{window}.
4045 @var{window} must be a live window and defaults to the selected
4046 window. @var{position} defaults to the value of @code{window-point}
4049 This means that in order to move the mouse pointer to the position of
4050 point in the selected window, it's sufficient to write:
4054 (let ((position (window-absolute-pixel-position)))
4055 (set-mouse-absolute-pixel-position
4056 (car position) (cdr position)))
4062 @node Window Configurations
4063 @section Window Configurations
4064 @cindex window configurations
4065 @cindex saving window information
4067 A @dfn{window configuration} records the entire layout of one
4068 frame---all windows, their sizes, which buffers they contain, how those
4069 buffers are scrolled, and their value of point; also their
4070 fringes, margins, and scroll bar settings. It also includes the value
4071 of @code{minibuffer-scroll-window}. As a special exception, the window
4072 configuration does not record the value of point in the selected window
4073 for the current buffer.
4075 You can bring back an entire frame layout by restoring a previously
4076 saved window configuration. If you want to record the layout of all
4077 frames instead of just one, use a frame configuration instead of a
4078 window configuration. @xref{Frame Configurations}.
4080 @defun current-window-configuration &optional frame
4081 This function returns a new object representing @var{frame}'s current
4082 window configuration. The default for @var{frame} is the selected
4083 frame. The variable @code{window-persistent-parameters} specifies
4084 which window parameters (if any) are saved by this function.
4085 @xref{Window Parameters}.
4088 @defun set-window-configuration configuration
4089 This function restores the configuration of windows and buffers as
4090 specified by @var{configuration}, for the frame that @var{configuration}
4093 The argument @var{configuration} must be a value that was previously
4094 returned by @code{current-window-configuration}. The configuration is
4095 restored in the frame from which @var{configuration} was made, whether
4096 that frame is selected or not. This always counts as a window size
4097 change and triggers execution of the @code{window-size-change-functions}
4098 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
4099 know how to tell whether the new configuration actually differs from the
4102 If the frame from which @var{configuration} was saved is dead, all this
4103 function does is restore the three variables @code{window-min-height},
4104 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
4105 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
4107 Here is a way of using this function to get the same effect
4108 as @code{save-window-excursion}:
4112 (let ((config (current-window-configuration)))
4114 (progn (split-window-below nil)
4116 (set-window-configuration config)))
4121 @defmac save-window-excursion forms@dots{}
4122 This macro records the window configuration of the selected frame,
4123 executes @var{forms} in sequence, then restores the earlier window
4124 configuration. The return value is the value of the final form in
4127 Most Lisp code should not use this macro; @code{save-selected-window}
4128 is typically sufficient. In particular, this macro cannot reliably
4129 prevent the code in @var{forms} from opening new windows, because new
4130 windows might be opened in other frames (@pxref{Choosing Window}), and
4131 @code{save-window-excursion} only saves and restores the window
4132 configuration on the current frame.
4134 Do not use this macro in @code{window-size-change-functions}; exiting
4135 the macro triggers execution of @code{window-size-change-functions},
4136 leading to an endless loop.
4139 @defun window-configuration-p object
4140 This function returns @code{t} if @var{object} is a window configuration.
4143 @defun compare-window-configurations config1 config2
4144 This function compares two window configurations as regards the
4145 structure of windows, but ignores the values of point and the
4146 saved scrolling positions---it can return @code{t} even if those
4149 The function @code{equal} can also compare two window configurations; it
4150 regards configurations as unequal if they differ in any respect, even a
4154 @defun window-configuration-frame config
4155 This function returns the frame for which the window configuration
4156 @var{config} was made.
4159 Other primitives to look inside of window configurations would make
4160 sense, but are not implemented because we did not need them. See the
4161 file @file{winner.el} for some more operations on windows
4164 The objects returned by @code{current-window-configuration} die
4165 together with the Emacs process. In order to store a window
4166 configuration on disk and read it back in another Emacs session, you
4167 can use the functions described next. These functions are also useful
4168 to clone the state of a frame into an arbitrary live window
4169 (@code{set-window-configuration} effectively clones the windows of a
4170 frame into the root window of that very frame only).
4172 @cindex window state
4173 @defun window-state-get &optional window writable
4174 This function returns the state of @var{window} as a Lisp object. The
4175 argument @var{window} must be a valid window and defaults to the root
4176 window of the selected frame.
4178 If the optional argument @var{writable} is non-@code{nil}, this means to
4179 not use markers for sampling positions like @code{window-point} or
4180 @code{window-start}. This argument should be non-@code{nil} when the
4181 state will be written to disk and read back in another session.
4183 Together, the argument @var{writable} and the variable
4184 @code{window-persistent-parameters} specify which window parameters are
4185 saved by this function. @xref{Window Parameters}.
4188 The value returned by @code{window-state-get} can be used in the same
4189 session to make a clone of a window in another window. It can be also
4190 written to disk and read back in another session. In either case, use
4191 the following function to restore the state of the window.
4193 @defun window-state-put state &optional window ignore
4194 This function puts the window state @var{state} into @var{window}.
4195 The argument @var{state} should be the state of a window returned by
4196 an earlier invocation of @code{window-state-get}, see above. The
4197 optional argument @var{window} can be either a live window or an
4198 internal window (@pxref{Windows and Frames}) and defaults to the
4199 selected one. If @var{window} is not live, it is replaced by a live
4200 window before putting @var{state} into it.
4202 If the optional argument @var{ignore} is non-@code{nil}, it means to ignore
4203 minimum window sizes and fixed-size restrictions. If @var{ignore}
4204 is @code{safe}, this means windows can get as small as one line
4209 @node Window Parameters
4210 @section Window Parameters
4211 @cindex window parameters
4213 This section describes how window parameters can be used to associate
4214 additional information with windows.
4216 @defun window-parameter window parameter
4217 This function returns @var{window}'s value for @var{parameter}. The
4218 default for @var{window} is the selected window. If @var{window} has no
4219 setting for @var{parameter}, this function returns @code{nil}.
4222 @defun window-parameters &optional window
4223 This function returns all parameters of @var{window} and their values.
4224 The default for @var{window} is the selected window. The return value
4225 is either @code{nil}, or an association list whose elements have the form
4226 @code{(@var{parameter} . @var{value})}.
4229 @defun set-window-parameter window parameter value
4230 This function sets @var{window}'s value of @var{parameter} to
4231 @var{value} and returns @var{value}. The default for @var{window}
4232 is the selected window.
4235 By default, the functions that save and restore window configurations or the
4236 states of windows (@pxref{Window Configurations}) do not care about
4237 window parameters. This means that when you change the value of a
4238 parameter within the body of a @code{save-window-excursion}, the
4239 previous value is not restored when that macro exits. It also means
4240 that when you restore via @code{window-state-put} a window state saved
4241 earlier by @code{window-state-get}, all cloned windows have their
4242 parameters reset to @code{nil}. The following variable allows you to
4243 override the standard behavior:
4245 @defvar window-persistent-parameters
4246 This variable is an alist specifying which parameters get saved by
4247 @code{current-window-configuration} and @code{window-state-get}, and
4248 subsequently restored by @code{set-window-configuration} and
4249 @code{window-state-put}. @xref{Window Configurations}.
4251 The @sc{car} of each entry of this alist is a symbol specifying the
4252 parameter. The @sc{cdr} should be one of the following:
4256 This value means the parameter is saved neither by
4257 @code{window-state-get} nor by @code{current-window-configuration}.
4260 This value specifies that the parameter is saved by
4261 @code{current-window-configuration} and (provided its @var{writable}
4262 argument is @code{nil}) by @code{window-state-get}.
4264 @item @code{writable}
4265 This means that the parameter is saved unconditionally by both
4266 @code{current-window-configuration} and @code{window-state-get}. This
4267 value should not be used for parameters whose values do not have a read
4268 syntax. Otherwise, invoking @code{window-state-put} in another session
4269 may fail with an @code{invalid-read-syntax} error.
4273 Some functions (notably @code{delete-window},
4274 @code{delete-other-windows} and @code{split-window}), may behave specially
4275 when their @var{window} argument has a parameter set. You can override
4276 such special behavior by binding the following variable to a
4277 non-@code{nil} value:
4279 @defvar ignore-window-parameters
4280 If this variable is non-@code{nil}, some standard functions do not
4281 process window parameters. The functions currently affected by this are
4282 @code{split-window}, @code{delete-window}, @code{delete-other-windows},
4283 and @code{other-window}.
4285 An application can bind this variable to a non-@code{nil} value around
4286 calls to these functions. If it does so, the application is fully
4287 responsible for correctly assigning the parameters of all involved
4288 windows when exiting that function.
4291 The following parameters are currently used by the window management
4295 @item @code{delete-window}
4296 This parameter affects the execution of @code{delete-window}
4297 (@pxref{Deleting Windows}).
4299 @item @code{delete-other-windows}
4300 This parameter affects the execution of @code{delete-other-windows}
4301 (@pxref{Deleting Windows}).
4303 @item @code{split-window}
4304 This parameter affects the execution of @code{split-window}
4305 (@pxref{Splitting Windows}).
4307 @item @code{other-window}
4308 This parameter affects the execution of @code{other-window}
4309 (@pxref{Cyclic Window Ordering}).
4311 @item @code{no-other-window}
4312 This parameter marks the window as not selectable by @code{other-window}
4313 (@pxref{Cyclic Window Ordering}).
4315 @item @code{clone-of}
4316 This parameter specifies the window that this one has been cloned
4317 from. It is installed by @code{window-state-get} (@pxref{Window
4320 @item @code{preserved-size}
4321 This parameter specifies a buffer, a direction where @code{nil} means
4322 vertical and @code{t} horizontal, and a size in pixels. If this window
4323 displays the specified buffer and its size in the indicated direction
4324 equals the size specified by this parameter, then Emacs will try to
4325 preserve the size of this window in the indicated direction. This
4326 parameter is installed and updated by the function
4327 @code{window-preserve-size} (@pxref{Preserving Window Sizes}).
4329 @item @code{quit-restore}
4330 This parameter is installed by the buffer display functions
4331 (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
4332 (@pxref{Quitting Windows}). It contains four elements:
4334 The first element is one of the symbols @code{window}, meaning that the
4335 window has been specially created by @code{display-buffer}; @code{frame},
4336 a separate frame has been created; @code{same}, the window has
4337 displayed the same buffer before; or @code{other}, the window showed
4338 another buffer before.
4340 The second element is either one of the symbols @code{window} or
4341 @code{frame}, or a list whose elements are the buffer shown in the
4342 window before, that buffer's window start and window point positions,
4343 and the window's height at that time.
4345 The third element is the window selected at the time the parameter was
4346 created. The function @code{quit-restore-window} tries to reselect that
4347 window when it deletes the window passed to it as argument.
4349 The fourth element is the buffer whose display caused the creation of
4350 this parameter. @code{quit-restore-window} deletes the specified window
4351 only if it still shows that buffer.
4354 There are additional parameters @code{window-atom} and @code{window-side};
4355 these are reserved and should not be used by applications.
4359 @section Hooks for Window Scrolling and Changes
4360 @cindex hooks for window operations
4362 This section describes how a Lisp program can take action whenever a
4363 window displays a different part of its buffer or a different buffer.
4364 There are three actions that can change this: scrolling the window,
4365 switching buffers in the window, and changing the size of the window.
4366 The first two actions run @code{window-scroll-functions}; the last runs
4367 @code{window-size-change-functions}.
4369 @defvar window-scroll-functions
4370 This variable holds a list of functions that Emacs should call before
4371 redisplaying a window with scrolling. Displaying a different buffer in
4372 the window also runs these functions.
4374 This variable is not a normal hook, because each function is called with
4375 two arguments: the window, and its new display-start position.
4377 These functions must take care when using @code{window-end}
4378 (@pxref{Window Start and End}); if you need an up-to-date value, you
4379 must use the @var{update} argument to ensure you get it.
4381 @strong{Warning:} don't use this feature to alter the way the window
4382 is scrolled. It's not designed for that, and such use probably won't
4386 @defvar window-size-change-functions
4387 This variable holds a list of functions to be called if the size of
4388 any window changes for any reason. The functions are called at the
4389 beginning of a redisplay cycle, and just once for each frame on which
4390 size changes have occurred.
4392 Each function receives the frame as its sole argument. There is no
4393 direct way to find out which windows on that frame have changed size, or
4394 precisely how. However, if a size-change function records, at each
4395 call, the existing windows and their sizes, it can also compare the
4396 present sizes and the previous sizes.
4398 Creating or deleting windows counts as a size change, and therefore
4399 causes these functions to be called. Changing the frame size also
4400 counts, because it changes the sizes of the existing windows.
4402 You may use @code{save-selected-window} in these functions
4403 (@pxref{Selecting Windows}). However, do not use
4404 @code{save-window-excursion} (@pxref{Window Configurations}); exiting
4405 that macro counts as a size change, which would cause these functions
4406 to be called over and over.
4409 @defvar window-configuration-change-hook
4410 A normal hook that is run every time you change the window configuration
4411 of an existing frame. This includes splitting or deleting windows,
4412 changing the sizes of windows, or displaying a different buffer in a
4415 The buffer-local part of this hook is run once for each window on the
4416 affected frame, with the relevant window selected and its buffer
4417 current. The global part is run once for the modified frame, with that
4421 In addition, you can use @code{jit-lock-register} to register a Font
4422 Lock fontification function, which will be called whenever parts of a
4423 buffer are (re)fontified because a window was scrolled or its size
4424 changed. @xref{Other Font Lock Variables}.