2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2011
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/windows
7 @node Windows, Frames, Buffers, Top
10 This chapter describes the functions and variables related to Emacs
11 windows. @xref{Frames}, for how windows are assigned an area of screen
12 available for Emacs to use. @xref{Display}, for information on how text
13 is displayed in windows.
16 * Basic Windows:: Basic information on using windows.
17 * Windows and Frames:: Relating windows to the frame they appear on.
18 * Window Sizes:: Accessing a window's size.
19 * Resizing Windows:: Changing the sizes of windows.
20 * Splitting Windows:: Splitting one window into two windows.
21 * Deleting Windows:: Deleting a window gives its space to other windows.
22 * Selecting Windows:: The selected window is the one that you edit in.
23 * Cyclic Window Ordering:: Moving around the existing windows.
24 * Buffers and Windows:: Each window displays the contents of a buffer.
25 * Switching Buffers:: Higher-level functions for switching to a buffer.
26 * Choosing Window:: How to choose a window for displaying a buffer.
27 * Display Action Functions:: Subroutines for @code{display-buffer}.
28 * Choosing Window Options:: Extra options affecting how buffers are displayed.
29 * Window History:: Each window remembers the buffers displayed in it.
30 * Dedicated Windows:: How to avoid displaying another buffer in
32 * Quitting Windows:: How to restore the state prior to displaying a
34 * Window Point:: Each window has its own location of point.
35 * Window Start and End:: Buffer positions indicating which text is
36 on-screen in a window.
37 * Textual Scrolling:: Moving text up and down through the window.
38 * Vertical Scrolling:: Moving the contents up and down on the window.
39 * Horizontal Scrolling:: Moving the contents sideways on the window.
40 * Coordinates and Windows:: Converting coordinates to windows.
41 * Window Configurations:: Saving and restoring the state of the screen.
42 * Window Parameters:: Associating additional information with windows.
43 * Window Hooks:: Hooks for scrolling, window size changes,
44 redisplay going past a certain point,
45 or window configuration changes.
50 @section Basic Concepts of Emacs Windows
53 A @dfn{window} is a area of the screen which is used to display a
54 buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a
55 special Lisp object type.
57 @cindex multiple windows
58 Windows are grouped into frames (@pxref{Frames}). Each frame
59 contains at least one window; the user can subdivide it into multiple,
60 non-overlapping windows to view several buffers at once. Lisp
61 programs can use multiple windows for a variety of purposes. In
62 Rmail, for example, you can view a summary of message titles in one
63 window, and the contents of the selected message in another window.
65 @cindex terminal screen
66 @cindex screen of terminal
67 Emacs uses the word ``window'' with a different meaning than in
68 graphical desktop environments and window systems, such as the X
69 Window System. When Emacs is run on X, each of its graphical X
70 windows is an Emacs frame (containing one or more Emacs windows).
71 When Emacs is run on a text-only terminal, the frame fills the entire
75 Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
76 within the area of the frame. When a window is created, resized, or
77 deleted, the change in window space is taken from or given to the
78 adjacent windows, so that the total area of the frame is unchanged.
81 @cindex internal windows
82 A @dfn{live window} is one that is actually displaying a buffer in a
83 frame. Such a window can be @dfn{deleted}, i.e. removed from the
84 frame (@pxref{Deleting Windows}); then it is no longer live, but the
85 Lisp object representing it might be still referenced from other Lisp
86 objects. A deleted window may be brought back to life by restoring a
87 saved window configuration (@pxref{Window Configurations}).
90 This function returns @code{t} if @var{object} is a window (whether or
91 not it is live). Otherwise, it returns @code{nil}.
94 @defun window-live-p object
95 This function returns @code{t} if @var{object} is a live window and
96 @code{nil} otherwise. A live window is one that displays a buffer.
99 The windows in each frame are organized into a @dfn{window tree}.
100 @xref{Windows and Frames}. The leaf nodes of each window tree are
101 live windows---the ones actually displaying buffers. The internal
102 nodes of the window tree are internal windows, which are not live.
103 You can distinguish internal windows from deleted windows with
104 @code{window-valid-p}.
106 @defun window-valid-p object
107 This function returns @code{t} if @var{object} is a live window, or an
108 internal window in a window tree. Otherwise, it returns @code{nil},
109 including for the case where @var{object} is a deleted window.
112 @cindex selected window
113 In each frame, at any time, exactly one Emacs window is designated
114 as @dfn{selected within the frame}. For the selected frame, that
115 window is called the @dfn{selected window}---the one in which most
116 editing takes place, and in which the cursor for selected windows
117 appears (@pxref{Cursor Parameters}). The selected window's buffer is
118 usually also the current buffer, except when @code{set-buffer} has
119 been used (@pxref{Current Buffer}). As for non-selected frames, the
120 window selected within the frame becomes the selected window if the
121 frame is ever selected. @xref{Selecting Windows}.
123 @defun selected-window
124 This function returns the selected window (which is always a live
128 @node Windows and Frames
129 @section Windows and Frames
131 Each window belongs to exactly one frame (@pxref{Frames}).
133 @defun window-frame window
134 This function returns the frame that the window @var{window} belongs
135 to. If @var{window} is @code{nil}, it defaults to the selected
139 @defun window-list &optional frame minibuffer window
140 This function returns a list of live windows belonging to the frame
141 @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
144 The optional argument @var{minibuffer} specifies whether to include
145 the minibuffer window in the returned list. If @var{minibuffer} is
146 @code{t}, the minibuffer window is included. If @var{minibuffer} is
147 @code{nil} or omitted, the minibuffer window is included only if it is
148 active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the
149 minibuffer window is never included.
151 The optional argument @var{window}, if non-@code{nil}, should be a
152 live window on the specified frame; then @var{window} will be the
153 first element in the returned list. If @var{window} is omitted or
154 @code{nil}, the window selected within the frame is first element.
159 Windows in the same frame are organized into a @dfn{window tree},
160 whose leaf nodes are the live windows. The internal nodes of a window
161 tree are not live; they exist for the purpose of organizing the
162 relationships between live windows. The root node of a window tree is
163 called the @dfn{root window}. It can be either a live window (if the
164 frame has just one window), or an internal window.
166 A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
167 frame's window tree unless the frame is a minibuffer-only frame.
168 Nonetheless, most of the functions in this section accept the
169 minibuffer window as an argument. Also, the function
170 @code{window-tree} described at the end of this section lists the
171 minibuffer window alongside the actual window tree.
173 @defun frame-root-window &optional frame-or-window
174 This function returns the root window for @var{frame-or-window}. The
175 argument @var{frame-or-window} should be either a window or a frame;
176 if omitted or @code{nil}, it defaults to the selected frame. If
177 @var{frame-or-window} is a window, the return value is the root window
178 of that window's frame.
181 @cindex parent window
183 @cindex sibling window
184 When a window is split, there are two live windows where previously
185 there was one. One of these is represented by the same Lisp window
186 object as the original window, and the other is represented by a
187 newly-created Lisp window object. Both of these live windows become
188 leaf nodes of the window tree, as @dfn{child windows} of a single
189 internal window. If necessary, Emacs automatically creates this
190 internal window, which is also called the @dfn{parent window}, and
191 assigns it to the appropriate position in the window tree. A set of
192 windows that share the same parent are called @dfn{siblings}.
194 @cindex parent window
195 @defun window-parent &optional window
196 This function returns the parent window of @var{window}. If
197 @var{window} is omitted or @code{nil}, it defaults to the selected
198 window. The return value is @code{nil} if @var{window} has no parent
199 (i.e. it is a minibuffer window or the root window of its frame).
202 Each internal window always has at least two child windows. If this
203 number falls to one as a result of window deletion, Emacs
204 automatically deletes the internal window, and its sole remaining
205 child window takes its place in the window tree.
207 Each child window can be either a live window, or an internal window
208 (which in turn would have its own child windows). Therefore, each
209 internal window can be thought of as occupying a certain rectangular
210 @dfn{screen area}---the union of the areas occupied by the live
211 windows that are ultimately descended from it.
213 @cindex window combination
214 @cindex vertical combination
215 @cindex horizontal combination
216 For each internal window, the screen areas of the immediate children
217 are arranged either vertically or horizontally (never both). If the
218 child windows are arranged one above the other, they are said to form
219 a @dfn{vertical combination}; if they are arranged side by side, they
220 are said to form a @dfn{horizontal combination}. Consider the
225 ______________________________________
226 | ______ ____________________________ |
227 || || __________________________ ||
231 || |||____________W4____________|||
232 || || __________________________ ||
235 || |||____________W5____________|||
236 ||__W2__||_____________W3_____________ |
237 |__________________W1__________________|
243 The root window of this frame is an internal window, @code{W1}. Its
244 child windows form a horizontal combination, consisting of the live
245 window @code{W2} and the internal window @code{W3}. The child windows
246 of @code{W3} form a vertical combination, consisting of the live
247 windows @code{W4} and @code{W5}. Hence, the live windows in this
248 window tree are @code{W2} @code{W4}, and @code{W5}.
250 The following functions can be used to retrieve a child window of an
251 internal window, and the siblings of a child window.
253 @defun window-top-child window
254 This function returns the topmost child window of @var{window}, if
255 @var{window} is an internal window whose children form a vertical
256 combination. For any other type of window, the return value is
260 @defun window-left-child window
261 This function returns the leftmost child window of @var{window}, if
262 @var{window} is an internal window whose children form a horizontal
263 combination. For any other type of window, the return value is
267 @defun window-child window
268 This function returns the first child window of the internal window
269 @var{window}---the topmost child window for a vertical combination, or
270 the leftmost child window for a horizontal combination. If
271 @var{window} is a live window, the return value is @code{nil}.
274 @defun window-combined-p &optional window horizontal
275 This function returns a non-@code{nil} value if and only if
276 @var{window} is part of a vertical combination. If @var{window} is
277 omitted or nil, it defaults to the selected one.
279 If the optional argument @var{horizontal} is non-@code{nil}, this
280 means to return non-@code{nil} if and only if @var{window} is part of
281 a horizontal combination.
284 @defun window-next-sibling &optional window
285 This function returns the next sibling of the window @var{window}. If
286 omitted or @code{nil}, @var{window} defaults to the selected window.
287 The return value is @code{nil} if @var{window} is the last child of
291 @defun window-prev-sibling &optional window
292 This function returns the previous sibling of the window @var{window}.
293 If omitted or @code{nil}, @var{window} defaults to the selected
294 window. The return value is @code{nil} if @var{window} is the first
298 The functions @code{window-next-sibling} and
299 @code{window-prev-sibling} should not be confused with the functions
300 @code{next-window} and @code{previous-window} which respectively
301 return the next and previous window in the cyclic ordering of windows
302 (@pxref{Cyclic Window Ordering}).
304 You can use the following functions to find the first live window on
305 a frame, and to retrieve the entire window tree of a frame:
307 @defun frame-first-window &optional frame-or-window
308 This function returns the live window at the upper left corner of the
309 frame specified by @var{frame-or-window}. The argument
310 @var{frame-or-window} must denote a window or a live frame and defaults
311 to the selected frame. If @var{frame-or-window} specifies a window,
312 this function returns the first window on that window's frame. Under
313 the assumption that the frame from our canonical example is selected
314 @code{(frame-first-window)} returns @code{W2}.
317 @defun window-tree &optional frame
318 This function returns a list representing the window tree for frame
319 @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
322 The return value is a list of the form @code{(@var{root} @var{mini})},
323 where @var{root} represents the window tree of the frame's root
324 window, and @var{mini} is the frame's minibuffer window.
326 If the root window is live, @var{root} is that window itself.
327 Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
328 @var{w2} ...)} where @var{dir} is @code{nil} for a horizontal
329 combination and @code{t} for a vertical combination, @var{edges} gives
330 the size and position of the combination, and the remaining elements
331 are the child windows. Each child window may again be a window object
332 (for a live window) or a list with the same format as above (for an
333 internal window). The @var{edges} element is a list @code{(@var{left}
334 @var{top} @var{right} @var{bottom})}, similar to the value returned by
335 @code{window-edges} (@pxref{Coordinates and Windows}).
339 @section Window Sizes
341 @cindex size of window
343 Emacs windows are rectangular. The structure of a live window can be
344 roughly sketched as follows:
348 _________________________________________
349 ^ |______________ Header Line_______________|
350 | |LS|LF|LM| |RM|RF|RS| ^
352 Window | | | | Text Area | | | | Window
353 Total | | | | (Window Body) | | | | Body
354 Height | | | | | | | | Height
355 | | | | |<- Window Body Width ->| | | | |
356 | |__|__|__|_______________________|__|__|__| v
357 v |_______________ Mode Line _______________|
359 <----------- Window Total Width -------->
365 @cindex body of a window
366 The text area constitutes the body of the window. In its most simple
367 form, a window consists of its body alone. LS and RS stand for the left
368 and right scroll bar (@pxref{Scroll Bars}) respectively. Only one of
369 them can be present at any time. LF and RF denote the left and right
370 fringe, see @ref{Fringes}. LM and RM, finally, stand for the left and
371 right display margin, see @ref{Display Margins}. The header line, if
372 present, is located above theses areas, the mode line below, see
373 @ref{Mode Line Format}.
375 @cindex window height
376 @cindex total window height
377 @cindex height of a window
378 @cindex total height of a window
379 The @dfn{total height of a window} is specified as the total number of
380 lines occupied by the window. Any mode or header line is included in a
381 window's total height. For an internal window, the total height is
382 calculated recursively from the total heights of its child windows.
385 @cindex total window width
386 @cindex width of a window
387 @cindex total width of a window
388 The @dfn{total width of a window} denotes the total number of columns of
389 the window. Any scroll bar and the column of @samp{|} characters that
390 separate the window from its right sibling are included in a window's
391 total width. On a window-system, fringes and display margins are
392 included in a window's total width too. For an internal window, the
393 total width is calculated recursively from the total widths of its child
396 @cindex total size of a window
397 @cindex total window size
398 The following function is the standard interface for getting the total
401 @defun window-total-size &optional window &optional horizontal
402 This function returns the total number of lines of @var{window}. The
403 argument @var{window} can denote any window and defaults to the selected
404 one. If @var{window} is live, the return value includes any header or
405 mode lines of @var{window}. If @var{window} is internal, the return
406 value is the sum of the total heights of @var{window}'s child windows
407 provided these are vertically combined and the height of @var{window}'s
408 first child if they are horizontally combined.
410 If the optional argument @var{horizontal} is non-@code{nil}, this
411 function returns the total number of columns of @var{window}. If
412 @var{window} is live, the return value includes any vertical divider
413 column or scroll bars of @var{window}. On a window-system, the return
414 value includes the space occupied by any margins and fringes of
415 @var{window} too. If @var{window} is internal, the return value is the
416 sum of the total widths of @var{window}'s child windows provided these
417 are horizontally combined and the width of @var{window}'s first child
421 Alternatively, the following two functions can be used to retrieve
422 either the total height or the total width of a window:
424 @defun window-total-height &optional window
425 This function returns the total number of lines of @var{window}.
426 @var{window} can be any window and defaults to the selected one. The
427 return value includes @var{window}'s mode line and header line, if any.
428 If @var{window} is internal the return value is the sum of heights of
429 @var{window}'s child windows for a vertical combination and the height
430 of @var{window}'s first child otherwise.
433 @defun window-total-width &optional window
434 This function returns the total number of columns of @var{window}.
435 @var{window} can be any window and defaults to the selected one. The
436 return value includes any vertical dividers or scrollbars of
437 @var{window}. On a window-system the return value also includes the
438 space occupied by any margins and fringes of @var{window}. If
439 @var{window} is internal, the return value is the sum of the widths of
440 @var{window}'s child windows for a horizontal combination and the width
441 of @var{window}'s first child otherwise.
444 The total height of any window is usually less than the height of the
445 window's frame, because the latter may also include the minibuffer
446 window. Depending on the toolkit in use, the frame height can also
447 include the menu bar and the tool bar (@pxref{Size and Position}).
448 Therefore, in general it is not straightforward to compare window and
449 frame heights. The following function is useful to determine whether
450 there are no other windows above or below a specified window.
452 @cindex full-height window
453 @defun window-full-height-p &optional window
454 This function returns non-@code{nil} if there is no other window above
455 or below @var{window} on the containing frame. More precisely, this
456 function returns @code{t} if and only if the total height of
457 @var{window} equals the total height of the root window (@pxref{Windows
458 and Frames}) of @var{window}'s frame. The @var{window} argument may
459 denote any window and defaults to the selected one.
462 @cindex full-width window
463 The following function can be used to determine whether there are no
464 other windows on the left or right of a specified window.
466 @defun window-full-width-p &optional window
467 This function returns non-@code{nil} if there are no other windows on
468 the left or right of @var{window}; @code{nil} otherwise. More
469 precisely, this function returns @code{t} if and only if the total width
470 of @var{window} equals the total width of the root window
471 (@pxref{Windows and Frames}) of @var{window}'s frame. The @var{window}
472 argument may denote any window and defaults to the selected one.
475 @cindex top line of window
476 @cindex left column of window
477 The windows of a frame are unambiguously characterized by the
478 combination of their top line and left column within that frame.
480 @defun window-top-line &optional window
481 This function returns the top line of @var{window}. The argument
482 @var{window} can denote any window and defaults to the selected one.
485 @defun window-left-column &optional window
486 This function returns the left column of @var{window}. The argument
487 @var{window} can denote any window and defaults to the selected one.
490 For a frame displaying one window only, that window's top line and left
491 column are both zero. When a frame displays a window @var{WB} below a
492 window @var{WA}, the top line of @var{WB} can be calculated by adding
493 the total height of @var{WA} to the top line of @var{WA}. When a frame
494 displays a window @var{WR} on the right of a window @var{WL}, the left
495 column of @var{WR} can be calculated by adding the total width of
496 @var{WL} to the left column of @var{WL}.
498 @cindex window body height
499 @cindex body height of a window
500 The @dfn{body height of a window} is specified as the total number of
501 lines occupied by the window's text area. Mode or header lines are not
502 included in a window's body height.
504 @cindex window body width
505 @cindex body width of a window
506 The @dfn{body width of a window} denotes the total number of columns
507 occupied by the window's text area. Scroll bars or columns of @samp{|}
508 characters that separate side-by-side windows are not included in a
511 @cindex body size of a window
512 @cindex window body size
513 @cindex canonical units of window/frame size
514 The following functions retrieve height and width of the body of a
515 live window. Note that the values these functions return are measured
516 in @dfn{canonical units}, i.e.@: for the default frame's face. If the
517 window shows some characters with non-default face, e.g., if the font
518 of some characters is larger or smaller than the default font, the
519 values returned by these functions will not match the actual number of
520 lines or characters per line shown in the window. To get the actual
521 number of columns and lines, move to the last character in the line
522 (e.g., with @code{end-of-visual-line}) or to the last line of the
523 window (e.g., with @code{window-end}), and use @code{posn-at-point} to
524 find the line or column there.
526 @defun window-body-size &optional window horizontal
527 This function returns the number of lines of @var{window}'s text area.
528 @var{window} must be a live window and defaults to the selected one.
529 The return value does not count any mode or header line of @var{window}.
531 Optional argument @var{horizontal} non-@code{nil} means to return the
532 number of columns of @var{window}'s text area. In this case the return
533 value does not include any vertical divider or scroll bar owned by
534 @var{window}. On a window-system the return value does not include the
535 number of columns used for @var{window}'s fringes or display margins
539 @defun window-body-height &optional window
540 This function returns the number of lines of @var{window}'s body.
541 @var{window} must be a live window and defaults to the selected one.
543 The return value does not include @var{window}'s mode line and header
544 line, if any. If a line at the bottom of the window is only partially
545 visible, that line is included in the return value. If you do not
546 want to include a partially visible bottom line in the return value,
547 use @code{window-text-height} instead.
550 @defun window-body-width &optional window
551 This function returns the number of columns of @var{window}'s body.
552 @var{window} must be a live window and defaults to the selected one.
554 The return value does not include any vertical dividers or scroll bars
555 owned by @var{window}. On a window-system the return value does not
556 include the number of columns used for @var{window}'s fringes or
557 display margins either.
560 The following functions have been used in earlier versions of Emacs.
561 They are still supported but due to the confusing nomenclature they
562 should not be used any more in future code.
564 @defun window-height &optional window
565 This function is an alias for `window-total-height', see above.
568 @defun window-width &optional window
569 This function is an alias for `window-body-width', see above.
572 @cindex minimum window size
573 The following two options constrain the sizes of windows to a minimum
574 height and width. Their values are honored when windows are split
575 (@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}). Any
576 request to make a window smaller than specified here will usually result
579 @defopt window-min-height
580 The value of this variable specifies how short a window may be. The
581 value is measured in line units and has to account for any header or
582 mode line. The default value for this option is @code{4}. Values less
583 than @code{1} are ignored.
586 @defopt window-min-width
587 The value of this variable specifies how narrow a window may be. The
588 value is measured in characters and includes any margins, fringes,
589 scroll bar and vertical divider column. The default value for this
590 option is @code{10}. A value less than @code{2} is ignored.
593 Applications should not rebind these variables. To shrink a specific
594 window to a height or width less than the one specified here, they
595 should rather invoke @code{window-resize} (@pxref{Resizing Windows})
596 with a non-@code{nil} @var{ignore} argument. The function
597 @code{split-window} (@pxref{Splitting Windows}) can make a window
598 smaller than specified here by calling it with a non-@code{nil}
599 @var{size} argument. Interactively, the values specified here cannot be
602 Earlier versions of Emacs could delete a window when its size dropped
603 below @code{window-min-height} or @code{window-min-width}. As a rule,
604 the current version of Emacs does no more delete windows by side-effect.
605 The only exception to this rule are requests to resize a frame which may
606 implicitly delete windows when they do not fit on the frame any more,
607 see @ref{Size and Position}.
609 The size of a window can be fixed which means that it cannot be split
610 (@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}).
612 @cindex fixed-size window
613 @defvar window-size-fixed
614 If this variable is non-@code{nil}, in a given buffer, then the size of
615 any window displaying that buffer remains fixed unless you either
616 explicitly change it or Emacs has no other choice.
618 If the value is @code{height}, then only the window's height is fixed;
619 if the value is @code{width}, then only the window's width is fixed.
620 Any other non-@code{nil} value fixes both the width and the height.
622 This variable automatically becomes buffer-local when set.
625 Commands supposed to explicitly change the size of windows such as
626 @code{enlarge-window} (@pxref{Resizing Windows}) get an error if they
627 had to change a window size which is fixed. Other functions like
628 @code{window-resize} (@pxref{Resizing Windows}) have an optional
629 @var{ignore} argument which allows to change the size of fixed-size
632 Deleting a window or changing a frame's size may change the size of a
633 fixed-size window, if there is no other alternative.
635 The height of a vertical combination of windows cannot be changed
636 when the height of all these windows is fixed. Its width cannot be
637 changed if the width of at least one of these windows is fixed.
638 Similarly, the width of a horizontal combination of windows cannot be
639 changed when the width of all these windows is fixed. Its height cannot
640 be changed if the height of at least one of these windows is fixed.
642 The next function allows to check whether the size of an arbitrary
645 @defun window-size-fixed-p &optional window horizontal
646 This function returns non-@code{nil} if @var{window}'s height is fixed.
647 The argument @var{window} can be an arbitrary window and defaults to the
648 selected one. Optional argument @var{horizontal} non-@code{nil} means
649 return non-@code{nil} if @var{window}'s width is fixed.
651 If this function returns @code{nil}, this does not necessarily mean that
652 @var{window} can be resized in the desired direction. The function
653 @code{window-resizable} (@pxref{Resizing Windows}) can tell that.
657 @node Resizing Windows
658 @section Resizing Windows
659 @cindex window resizing
660 @cindex resize window
661 @cindex changing window size
662 @cindex window size, changing
664 Emacs does not permit overlapping windows or gaps between windows, so
665 changing the size of a window always affects at least one other window.
666 When a frame contains just one window, that window can be resized only
667 by resizing the window's frame. The functions described below are
668 therefore meaningful only in the context of a frame containing at least
669 two windows. The size of the corresponding frame never changes when
670 invoking a function described in this section.
672 The routines changing window sizes always operate in one dimension at
673 a time. This means that windows can be resized only either vertically
674 or horizontally. If a window shall be resized in both dimensions, it
675 must be resized in one dimension first and in the other dimension
676 afterwards. If the second resize operation fails, the frame might end
677 up in an unsatisfactory state. To avoid such states, it might be useful
678 to save the current window configuration (@pxref{Window Configurations})
679 before attempting the first resize operation and restore the saved
680 configuration in case the second resize operation fails.
682 Functions that resize windows are supposed to obey restrictions
683 imposed by window minimum sizes and fixed-size windows, see @ref{Window
684 Sizes}. In order to determine whether resizing a specific window is
685 possible in the first place, the following function can be used:
687 @defun window-resizable window delta &optional horizontal ignore side noup nodown
688 This function returns @var{delta} if the size of @var{window} can be
689 changed vertically by @var{delta} lines. Optional argument
690 @var{horizontal} non-@code{nil} means to return @var{delta} if
691 @var{window} can be resized horizontally by @var{delta} columns. A
692 return value of zero means that @var{window} is not resizable.
694 If @var{delta} is a positive number, this means that @var{window} shall
695 be enlarged by @var{delta} lines or columns. If @var{window} cannot be
696 enlarged by @var{delta} lines or columns, this function returns the
697 maximum value in the range from 0 to @var{delta} by which @var{window}
700 If @var{delta} is a negative number, this means that @var{window} shall
701 be shrunk by -@var{delta} lines or columns. If @var{window} cannot be
702 shrunk by -@var{delta} lines or columns, this function returns the
703 minimum value in the range from @var{delta} to 0 that can be used for
704 shrinking @var{window}.
706 Optional argument @var{ignore} non-@code{nil} means ignore any
707 restrictions imposed by the variables @code{window-min-height} or
708 @code{window-min-width} and @code{window-size-fixed}. In this case the
709 minimum height of a window is specified as the minimum number of lines
710 that allow viewing any header or mode line and at least one line of the
711 text area of window. The minimum width of a window includes any
712 fringes, margins and the scroll bar as well as two text columns.
714 If @var{ignore} denotes a window, this means to ignore restrictions for
715 that window only. If @var{ignore} equals the constant @code{safe}, this
716 means a live window may get as small as one line or two columns.
718 Optional argument @var{noup} non-@code{nil} means don't go up in the
719 window tree but try to steal or distribute the space needed for the
720 resize operation among the other windows within @var{window}'s
721 combination. Optional argument @var{nodown} non-@code{nil} means don't
722 check whether @var{window} itself and its subwindows can be resized.
725 The function @code{window-resizable} does not change any window sizes.
726 The following function does:
728 @defun window-resize window delta &optional horizontal ignore
729 This function resizes @var{window} vertically by @var{delta} lines. The
730 argument @var{window} can denote an arbitrary window and defaults to the
731 selected one. An attempt to resize the root window of a frame will
734 Second argument @var{delta} a positive number means @var{window} shall
735 be enlarged by @var{delta} lines. If @var{delta} is negative, that
736 means @var{window} shall be shrunk by -@var{delta} lines.
738 Optional argument @var{horizontal} non-@code{nil} means to resize
739 @var{window} horizontally by @var{delta} columns. In this case a
740 positive @var{delta} means enlarge @var{window} by @var{delta} columns.
741 A negative @var{delta} means @var{window} shall be shrunk by
742 -@var{delta} columns.
744 Optional argument @var{ignore} has the same meaning as for the function
745 @code{window-resizable} above.
747 This function can simultaneously move two edges of WINDOW. Exactly
748 which edges of @var{window} are moved and which other windows are
749 resized along with @var{window} is determined by the splits and nest
750 status of the involved windows (@pxref{Splitting Windows}). If only the
751 low (right) edge of @var{window} shall be moved, the function
752 @code{adjust-window-trailing-edge} described below should be used.
755 The next four commands are simple interfaces to @code{window-resize}.
756 They always operate on the selected window, never delete any window, and
757 always raise an error when resizing would violate a restriction imposed
758 by @code{window-min-height}, @code{window-min-width}, or
759 @code{window-size-fixed}.
761 @deffn Command enlarge-window delta &optional horizontal
762 This function makes the selected window @var{delta} lines taller.
763 Interactively, if no argument is given, it makes the selected window one
764 line taller. If optional argument @var{horizontal} is non-@code{nil},
765 it makes the selected window wider by @var{delta} columns. If
766 @var{delta} is negative, it shrinks the selected window by -@var{delta}
767 lines or columns. The return value is @code{nil}.
770 @deffn Command enlarge-window-horizontally delta
771 This function makes the selected window @var{delta} columns wider.
772 Interactively, if no argument is given, it makes the selected window one
776 @deffn Command shrink-window delta &optional horizontal
777 This function makes the selected window @var{delta} lines smaller.
778 Interactively, if no argument is given, it makes the selected window one
779 line smaller. If optional argument @var{horizontal} is non-@code{nil},
780 it makes the selected window narrower by @var{delta} columns. If
781 @var{delta} is negative, it enlarges the selected window by -@var{delta}
782 lines or columns. The return value is @code{nil}.
785 @deffn Command shrink-window-horizontally delta
786 This function makes the selected window @var{delta} columns narrower.
787 Interactively, if no argument is given, it makes the selected window one
791 The following function is useful for moving the line dividing two
794 @defun adjust-window-trailing-edge window delta &optional horizontal
795 This function moves @var{window}'s bottom edge by @var{delta} lines.
796 Optional argument @var{horizontal} non-@code{nil} means to move
797 @var{window}'s right edge by @var{delta} columns. The argument
798 @var{window} defaults to the selected window.
800 If @var{delta} is greater zero, this moves the edge downwards or to the
801 right. If @var{delta} is less than zero, this moves the edge upwards or
802 to the left. If the edge can't be moved by @var{delta} lines or columns,
803 it is moved as far as possible in the desired direction but no error is
806 This function tries to resize windows adjacent to the edge that is
807 moved. Only if this is insufficient, it will also resize windows not
808 adjacent to that edge. As a consequence, if you move an edge in one
809 direction and back in the other direction by the same amount, the
810 resulting window configuration will not be necessarily identical to the
811 one before the first move. So if your intend to just resize
812 @var{window}, you should not use this function but call
813 @code{window-resize} (see above) instead.
816 @deffn Command fit-window-to-buffer &optional window max-height min-height override
817 This command makes @var{window} the right height to display its
818 contents exactly. The default for @var{window} is the selected window.
820 The optional argument @var{max-height} specifies the maximum total
821 height the window is allowed to be; @code{nil} means use the maximum
822 permissible height of a window on @var{window}'s frame. The optional
823 argument @var{min-height} specifies the minimum toatl height for the
824 window; @code{nil} means use @code{window-min-height}. All these height
825 values include the mode line and/or header line.
827 If the optional argument @var{override} is non-@code{nil}, this means to
828 ignore any restrictions imposed by @code{window-min-height} and
829 @code{window-min-width} on the size of @var{window}.
831 This function returns non-@code{nil} if it orderly resized @var{window},
832 and @code{nil} otherwise.
835 @deffn Command shrink-window-if-larger-than-buffer &optional window
836 This command shrinks @var{window} vertically to be as small as possible
837 while still showing the full contents of its buffer---but not less than
838 @code{window-min-height} lines. The argument @var{window} must denote
839 a live window and defaults to the selected one.
841 However, this command does nothing if the window is already too small to
842 display the whole text of the buffer, or if part of the contents are
843 currently scrolled off screen, or if the window is not the full width of
844 its frame, or if the window is the only window in its frame.
846 This command returns non-@code{nil} if it actually shrank the window
847 and @code{nil} otherwise.
850 @cindex balancing window sizes
851 Emacs provides two functions to balance windows, that is, to even out
852 the sizes of all windows on the same frame. The minibuffer window and
853 fixed-size windows are not resized by these functions.
855 @deffn Command balance-windows &optional window-or-frame
856 This function balances windows in a way that gives more space to
857 full-width and/or full-height windows. If @var{window-or-frame}
858 specifies a frame, it balances all windows on that frame. If
859 @var{window-or-frame} specifies a window, it balances that window and
860 its siblings (@pxref{Windows and Frames}) only.
863 @deffn Command balance-windows-area
864 This function attempts to give all windows on the selected frame
865 approximately the same share of the screen area. This means that
866 full-width or full-height windows are not given more space than other
870 @cindex maximizing windows
871 The following function can be used to give a window the maximum possible
872 size without deleting other ones.
874 @deffn Command maximize-window &optional window
875 This function maximizes @var{window}. More precisely, this makes
876 @var{window} as large as possible without resizing its frame or deleting
877 other windows. @var{window} can be any window and defaults to the
881 @cindex minimizing windows
882 To make a window as small as possible without deleting it the
883 following function can be used.
885 @deffn Command minimize-window &optional window
886 This function minimizes @var{window}. More precisely, this makes
887 @var{window} as small as possible without deleting it or resizing its
888 frame. @var{window} can be any window and defaults to the selected one.
892 @node Splitting Windows
893 @section Splitting Windows
894 @cindex splitting windows
895 @cindex window splitting
897 The functions described below are the primitives needed for creating a
898 new window. They do not accept a buffer as an argument. Rather, they
899 ``split'' an existing window into two halves, both displaying the buffer
900 previously visible in the window that was split.
902 @deffn Command split-window &optional window size side
903 This function creates a new window adjacent to @var{window}. It returns
904 the new window which is always a live window. The argument @var{window}
905 can denote any window and defaults to the selected one. This function
906 does not change the selected window.
908 Optional second argument @var{size} a positive number means make
909 @var{window} @var{size} lines (or columns) tall. If @var{size} is
910 negative, make the new window @minus{}@var{size} lines (or columns)
911 tall. If @var{size} is omitted or @code{nil}, then @var{window} is
912 divided evenly into two parts. (If there is an odd line, it is
913 allocated to the new window.)
915 If splitting would result in making a window smaller than
916 @code{window-min-height} or @code{window-min-width} (@pxref{Window
917 Sizes}), this function usually signals an error. However, if @var{size}
918 is non-@code{nil} and valid, a new window of the requested size is
919 created. (A size value would be invalid if it assigned less than one
920 line or less than two columns to the new window.)
922 Optional third argument @var{side} @code{nil} (or @code{below})
923 specifies that the new window shall be located below @var{window}. The
924 value @code{above} means the new window will be located above
925 @var{window}. In both cases @var{size} specifies the new number of
926 lines for @var{window} (or the new window if @var{size} is negative)
927 including space reserved for the mode and/or header line.
929 If @var{side} is @code{t} or @code{right} the new window will be
930 positioned on the right side of @var{window}. The value @code{left}
931 means the new window will be located on the left side of @var{window}.
932 In both cases @var{size} specifies the new number of columns for
933 @var{window} (or the new window provided @var{size} is negative)
934 including space reserved for margins, fringes and the scroll bar or a
937 Any other non-@code{nil} value for @var{side} is currently handled like
938 @code{t} (or @code{right}). Since this might change in the future,
939 application programs should refrain from using other values.
941 If @var{window} is live, properties of the new window like margins and
942 scroll bars are inherited from @var{window}. If @var{window} is an
943 internal window, these properties, as well as the buffer shown in the
944 new window, are inherited from the window selected on @var{window}'s
947 If @code{ignore-window-parameters} is non-@code{nil}, this function
948 ignores window parameters (@pxref{Window Parameters}). Otherwise, if
949 the @code{split-window} parameter of @var{window} is @code{t}, it splits
950 the window disregarding any other window parameters. If the
951 @code{split-window} parameter specifies a function, that function is
952 called with the arguments @var{window}, @var{size}, and @var{side} to
953 split @var{window}. If that function is @code{ignore}, nothing is done.
956 The following example starts with one window on a screen that is 50
957 lines high by 80 columns wide; then it splits the window.
961 (setq W1 (selected-window))
962 @result{} #<window 8 on windows.texi>
963 (setq W2 (split-window W1 15))
964 @result{} #<window 28 on windows.texi>
969 (window-total-size W1)
976 The screen looks like this:
992 Next, split the top window into two side-by-side windows:
996 (setq W3 (split-window W1 35 t))
997 @result{} #<window 32 on windows.texi>
1000 (window-left-column W1)
1002 (window-total-size W1 t)
1004 (window-left-column W3)
1010 Now the screen looks like this:
1027 Normally, Emacs indicates the border between two side-by-side windows
1028 with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The
1029 display table can specify alternative border characters; see @ref{Display
1032 Below we describe how @code{split-window} can be used to create the
1033 window configuration from our earlier example (@pxref{Windows and
1034 Frames}) and how internal windows are created for this purpose. We
1035 start with a frame containing one live window @code{W2} (in the
1036 following scenarios window names are assigned in an arbitrary manner in
1037 order to match the names of the example). Evaluating the form
1038 @code{(split-window W2 8 t)} creates a new internal window @code{W1}
1039 with two children---@code{W2} (the window we've split) and a new leaf
1043 ______________________________________
1044 | ______ ____________________________ |
1055 ||__W2__||_____________W6_____________ |
1056 |__________________W1__________________|
1061 Evaluating now @code{(split-window W6 -3)} creates another internal
1062 window @code{W3} with two children---@code{W6} and a new live window
1063 @code{W5}. This leaves us with a vertically combined window @code{W3}
1064 embedded in the horizontally combined window @code{W1}:
1067 ______________________________________
1068 | ______ ____________________________ |
1069 || || __________________________ ||
1075 || |||____________W6____________|||
1076 || || __________________________ ||
1078 || |||____________W5____________|||
1079 ||__W2__||_____________W3_____________ |
1080 |__________________W1__________________|
1085 Finally, evaluating @code{(split-window W6 nil t)} should get us the
1086 desired configuration as depicted below.
1089 ______________________________________
1090 | ______ ____________________________ |
1091 || || __________________________ ||
1092 || ||| ___________ ___________ |||
1095 || ||||_____W6____||_____W7____||||
1096 || |||____________W4____________|||
1097 || || __________________________ ||
1099 || |||____________W5____________|||
1100 ||__W2__||_____________W3_____________ |
1101 |__________________W1__________________|
1106 The scenario sketched above is the standard way to obtain the desired
1107 configuration. In Emacs 23 it was also the only way to do that since
1108 Emacs 23 did't allow splitting internal windows.
1110 With Emacs 24 you can also proceed as follows: Split an initial window
1111 @code{W6} by evaluating @code{(split-window W6 -3)} to produce the
1112 following vertical combination:
1115 ______________________________________
1116 | ____________________________________ |
1124 ||_________________W6_________________||
1125 | ____________________________________ |
1127 ||_________________W5_________________||
1128 |__________________W3__________________|
1133 Evaluating now @code{(split-window (window-parent W6) -8 'left)} or,
1134 equivalently, @code{(split-window W3 -8 'left)} should now produce the
1135 penultimate configuration from the previous scenario from where we can
1136 continue as described before.
1138 Another strategy starts with splitting an initial window @code{W6} by
1139 evaluating @code{(split-window W6 nil nil t)} with the following result:
1142 ______________________________________
1143 | _________________ _________________ |
1154 ||________W6_______||________W7_______||
1155 |__________________W4__________________|
1160 Evaluating now @code{(split-window W4 -3)} or @code{(split-window
1161 (window-parent W6) -3)} should get us a configuration as shown next.
1164 ______________________________________
1165 | ____________________________________ |
1166 || ________________ ________________ ||
1172 |||_______W6_______||________W7______|||
1173 ||_________________W4_________________||
1174 | ____________________________________ |
1176 ||_________________W5_________________||
1177 |__________________W3__________________|
1182 The desired configuration can be now obtained by evaluating
1183 @code{(split-window W3 -8 'left)} or, equivalently, @code{(split-window
1184 (window-parent W5) -8 'left)}.
1186 For a final approach let's start with the configuration of two live
1187 windows @code{W6} and @code{W7} shown above. If we now evaluate
1188 @code{(split-window W4 -8 'left)} or @code{(split-window (window-parent
1189 W6) -8 'left)} we get the following configuration.
1192 ______________________________________
1193 | ______ ____________________________ |
1194 || || ____________ ____________ ||
1202 || |||______W6____||______W7____|||
1203 ||__W2__||_____________W4_____________||
1204 |__________________W1__________________|
1209 Evaluating now @code{(split-window W4 -3)} or, for example,
1210 @code{(split-window (window-parent W6) -3)} should produce the desired
1213 The two options described next can be used to tune the operation of
1214 @code{split-window}.
1216 @defopt window-splits
1217 If this variable is nil, the function @code{split-window} can split a
1218 window if and only if that window's screen estate is sufficiently large
1219 to accommodate both--itself and the new window.
1221 If this variable is non-@code{nil}, @code{split-window} tries to resize
1222 all windows that are part of the same combination as the old window to
1223 accommodate the new window. Hence, the new window can be also created if
1224 the old window is of fixed size or too small to split (@pxref{Window
1227 In any case, the value of this variable is assigned to the splits status
1228 of the new window and, provided old and new window form a new
1229 combination, of the old window as well. The splits status of a window
1230 can be retrieved by invoking the function @code{window-splits} and
1231 altered by the function @code{set-window-splits} described next.
1233 If @code{window-nest} (see below) is non-@code{nil}, the space for the
1234 new window is exclusively taken from the old window, but the splits
1235 status of the involved windows is nevertheless set as described here.
1238 @defun window-splits &optional window
1239 This function returns the splits status of @var{window}. The argument
1240 @var{window} can be any window and defaults to the selected one.
1242 @cindex splits status
1243 The @dfn{splits status} of a window specifies how resizing and deleting
1244 that window may affect the size of other windows in the same window
1245 combination. More precisely, if @var{window}'s splits status is
1246 @code{nil} and @var{window} is resized, the corresponding space is
1247 preferably taken from (or given to) @var{window}'s right sibling. When
1248 @var{window} is deleted, its space is given to its left sibling. If
1249 @var{window}'s splits status is non-@code{nil}, resizing and deleting
1250 @var{window} may resize @emph{all} windows in @var{window}'s
1253 The splits status is initially set by @code{split-window}
1254 from the current value of the variable @code{window-splits} (see above)
1255 and can be reset by the function @code{set-window-splits} (see below).
1258 @defun set-window-splits window &optional status
1259 This function sets the splits status (see above) of @var{window} to
1260 @var{status}. The argument @var{window} can be any window and defaults
1261 to the selected one. The return value is @var{status}.
1264 To illustrate the use of @code{window-splits} consider the following
1265 window configuration:
1268 ______________________________________
1269 | ____________________________________ |
1274 ||_________________W2_________________||
1275 | ____________________________________ |
1280 ||_________________W3_________________||
1281 |__________________W1__________________|
1286 Splitting window @code{W3} with @code{window-splits} @code{nil}
1287 produces a configuration where the size of @code{W2} remains unchanged:
1290 ______________________________________
1291 | ____________________________________ |
1296 ||_________________W2_________________||
1297 | ____________________________________ |
1299 ||_________________W3_________________||
1300 | ____________________________________ |
1302 ||_________________W4_________________||
1303 |__________________W1__________________|
1308 Splitting @code{W3} with @code{window-splits} non-@code{nil} instead
1309 produces a configuration where all windows have approximately the same
1314 ______________________________________
1315 | ____________________________________ |
1318 ||_________________W2_________________||
1319 | ____________________________________ |
1322 ||_________________W3_________________||
1323 | ____________________________________ |
1326 ||_________________W4_________________||
1327 |__________________W1__________________|
1333 If this variable is @code{nil}, @code{split-window} creates a new parent
1334 window if and only if the old window has no parent window or shall be
1335 split orthogonally to the combination it is part of. If this variable
1336 is non-@code{nil}, @code{split-window} always creates a new parent
1337 window. If this variable is always non-@code{nil}, a frame's window
1338 tree is a binary tree so every window but the frame's root window has
1339 exactly one sibling.
1341 The value of this variable is also assigned to the nest status of the
1342 new parent window. The nest status of any window can be retrieved via
1343 the function @code{window-nest} and altered by the function
1344 @code{set-window-nest}, see below.
1347 @defun window-nest &optional window
1348 This function returns the nest status of @var{window}. The argument
1349 @var{window} can be any window and defaults to the selected one. Note,
1350 however, that the nest status is currently meaningful for internal
1354 The @dfn{nest status} of a window specifies whether that window may be
1355 removed and its subwindows recombined with that window's siblings when
1356 such a sibling's subwindow is deleted. The nest status is initially
1357 assigned by @code{split-window} from the current value of the variable
1358 @code{window-nest} (see above) and can be reset by the function
1359 @code{set-window-nest} (see below).
1361 If the return value is @code{nil}, subwindows of @var{window} may be
1362 recombined with @var{window}'s siblings when a window gets deleted. A
1363 return value of @code{nil} means that subwindows of @var{window} are
1364 never (re-)combined with @var{window}'s siblings in such a case.
1367 @defun set-window-nest window &optional status
1368 This functions sets the nest status (see above) of @var{window} to
1369 @var{status}. The argument @var{window} can be any window and defaults
1370 to the selected one. Note that setting the nest status is meaningful
1371 for internal windows only. The return value is @var{status}.
1374 To illustrate the use of @code{window-nest} consider the following
1375 configuration (throughout the following examples we shall assume that
1376 @code{window-splits} invariantly is @code{nil}).
1379 ______________________________________
1380 | ____________________________________ |
1387 ||_________________W2_________________||
1388 | ____________________________________ |
1391 ||_________________W3_________________||
1392 |__________________W1__________________|
1397 Splitting @code{W2} into two windows above each other with
1398 @code{window-nest} equal @code{nil} will get you a configuration like:
1401 ______________________________________
1402 | ____________________________________ |
1405 ||_________________W2_________________||
1406 | ____________________________________ |
1409 ||_________________W4_________________||
1410 | ____________________________________ |
1413 ||_________________W3_________________||
1414 |__________________W1__________________|
1419 If you now enlarge window @code{W4}, Emacs steals the necessary space
1420 from window @code{W3} resulting in a configuration like:
1423 ______________________________________
1424 | ____________________________________ |
1427 ||_________________W2_________________||
1428 | ____________________________________ |
1432 ||_________________W4_________________||
1433 | ____________________________________ |
1435 ||_________________W3_________________||
1436 |__________________W1__________________|
1441 Deleting window @code{W4}, will return its space to @code{W2} as
1445 ______________________________________
1446 | ____________________________________ |
1454 ||_________________W2_________________||
1455 | ____________________________________ |
1457 ||_________________W3_________________||
1458 |__________________W1__________________|
1463 Hence, with respect to the initial configuration, window @code{W2} has
1464 grown at the expense of window @code{W3}. If, however, in the initial
1465 configuration you had split @code{W2} with @code{window-nest} bound to
1466 @code{t}, a new internal window @code{W5} would have been created as
1470 ______________________________________
1471 | ____________________________________ |
1472 || __________________________________ ||
1474 |||________________W2________________|||
1475 || __________________________________ ||
1477 |||________________W4________________|||
1478 ||_________________W5_________________||
1479 | ____________________________________ |
1482 ||_________________W3_________________||
1483 |__________________W1__________________|
1488 Enlarging @code{W4} would now have stolen the necessary space from
1489 @code{W2} instead of @code{W3} as
1492 ______________________________________
1493 | ____________________________________ |
1494 || __________________________________ ||
1495 |||________________W2________________|||
1496 || __________________________________ ||
1499 |||________________W4________________|||
1500 ||_________________W5_________________||
1501 | ____________________________________ |
1504 ||_________________W3_________________||
1505 |__________________W1__________________|
1510 and the subsequent deletion of @code{W4} would have restored the initial
1513 For interactive use, Emacs provides two commands which always split the
1516 @deffn Command split-window-below &optional size
1517 This function splits the selected window into two windows, one above the
1518 other, leaving the upper of the two windows selected, with @var{size}
1519 lines. (If @var{size} is negative, then the lower of the two windows
1520 gets @minus{}@var{size} lines and the upper window gets the rest, but
1521 the upper window is still the one selected.) However, if
1522 @code{split-window-keep-point} (see below) is @code{nil}, then either
1523 window can be selected.
1525 In other respects, this function is similar to @code{split-window}.
1526 In particular, the upper window is the original one and the return value
1527 is the new, lower window.
1530 @defopt split-window-keep-point
1531 If this variable is non-@code{nil} (the default), then
1532 @code{split-window-below} behaves as described above.
1534 If it is @code{nil}, then @code{split-window-below} adjusts point
1535 in each of the two windows to avoid scrolling. (This is useful on
1536 slow terminals.) It selects whichever window contains the screen line
1537 that point was previously on. Other functions are not affected by
1541 @deffn Command split-window-right &optional size
1542 This function splits the selected window into two windows
1543 side-by-side, leaving the selected window on the left with @var{size}
1544 columns. If @var{size} is negative, the rightmost window gets
1545 @minus{}@var{size} columns, but the leftmost window still remains
1550 @node Deleting Windows
1551 @section Deleting Windows
1552 @cindex deleting windows
1554 A window remains visible on its frame unless you @dfn{delete} it by
1555 calling certain functions that delete windows. A deleted window cannot
1556 appear on the screen, but continues to exist as a Lisp object until
1557 there are no references to it. There is no way to cancel the deletion
1558 of a window aside from restoring a saved window configuration
1559 (@pxref{Window Configurations}). Restoring a window configuration also
1560 deletes any windows that aren't part of that configuration. Erroneous
1561 information may result from using a deleted window as if it were live.
1563 @deffn Command delete-window &optional window
1564 This function removes @var{window} from display and returns @code{nil}.
1565 The argument @var{window} can denote any window and defaults to the
1566 selected one. An error is signaled if @var{window} is the only window
1567 on its frame. Hence @var{window} must have at least one sibling window
1568 (@pxref{Windows and Frames}) in order to get deleted. If @var{window}
1569 is the selected window on its frame, this function selects the most
1570 recently selected live window on that frame instead.
1572 If the variable @code{ignore-window-parameters} (@pxref{Window
1573 Parameters}) is non-@code{nil}, this function ignores all parameters of
1574 @var{window}. Otherwise, if the @code{delete-window} parameter of
1575 @var{window} is @code{t}, it deletes the window disregarding other
1576 window parameters. If the @code{delete-window} parameter specifies a
1577 function, that function is called with @var{window} as its sole
1580 If the splits status of @var{window} (@pxref{Splitting Windows}) is
1581 @code{nil}, the space @var{window} took up is given to its left sibling
1582 if such a window exists and to its right sibling otherwise. If the
1583 splits status of @var{window} is non-@code{nil}, its space is
1584 proportionally distributed among the remaining windows in the same
1588 @deffn Command delete-other-windows &optional window
1589 This function makes @var{window} fill its frame and returns @code{nil}.
1590 The argument @var{window} can denote an arbitrary window and defaults to
1591 the selected one. Upon exit, @var{window} will be the selected window
1594 If the variable @code{ignore-window-parameters} (@pxref{Window
1595 Parameters}) is non-@code{nil}, this function ignores all parameters of
1596 @var{window}. Otherwise, if the @code{delete-other-windows} parameter
1597 of @var{window} equals @code{t}, it deletes all other windows
1598 disregarding any remaining window parameters. If the
1599 @code{delete-other-windows} parameter of @var{window} specifies a
1600 function, it calls that function with @var{window} as its sole argument.
1603 @deffn Command delete-windows-on &optional buffer-or-name frame
1604 This function deletes all windows showing @var{buffer-or-name} and
1605 returns nil. If there are no windows showing @var{buffer-or-name}, it
1606 does nothing. The optional argument @var{buffer-or-name} may be a
1607 buffer or the name of an existing buffer and defaults to the current
1608 buffer. Invoking this command on a minibuffer signals an error.
1610 The function @code{delete-windows-on} operates by calling
1611 @code{delete-window} for each window showing @var{buffer-or-name}. If a
1612 frame has several windows showing different buffers, then those showing
1613 @var{buffer-or-name} are removed, and the other windows expand to fill
1616 If all windows in some frame are showing @var{buffer-or-name} (including
1617 the case where there is only one window), then that frame is deleted
1618 provided there are other frames left.
1620 The optional argument @var{frame} specifies which frames to operate on.
1621 This function does not use it in quite the same way as the other
1622 functions which scan all live windows (@pxref{Cyclic Window Ordering});
1623 specifically, the values @code{t} and @code{nil} have the opposite of
1624 their meanings in the other functions. Here are the full details:
1628 means operate on all frames.
1630 means operate on the selected frame.
1631 @item @code{visible}
1632 means operate on all visible frames.
1634 means operate on all visible or iconified frames.
1636 means operate on that frame.
1641 @node Selecting Windows
1642 @section Selecting Windows
1643 @cindex selecting a window
1645 @defun select-window window &optional norecord
1646 This function makes @var{window} the selected window, see @ref{Basic
1647 Windows}. Unless @var{window} already is the selected window, this also
1648 makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current
1649 buffer. Moreover, the cursor for selected windows will be displayed in
1650 @var{window} after the next redisplay. This function returns
1653 Normally, @var{window}'s selected buffer is moved to the front of the
1654 buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
1655 recently selected window. But if the optional argument @var{norecord}
1656 is non-@code{nil}, the buffer list remains unchanged and @var{window}
1657 does not become the most recently selected one.
1660 @cindex most recently selected windows
1661 The sequence of calls to @code{select-window} with a non-@code{nil}
1662 @var{norecord} argument determines an ordering of windows by their
1663 selection time. The function @code{get-lru-window} can be used to
1664 retrieve the least recently selected live window in this ordering, see
1665 @ref{Cyclic Window Ordering}.
1667 @defmac save-selected-window forms@dots{}
1668 This macro records the selected frame, as well as the selected window
1669 of each frame, executes @var{forms} in sequence, then restores the
1670 earlier selected frame and windows. It also saves and restores the
1671 current buffer. It returns the value of the last form in @var{forms}.
1673 This macro does not save or restore anything about the sizes,
1674 arrangement or contents of windows; therefore, if @var{forms} change
1675 them, the change persists. If the previously selected window of some
1676 frame is no longer live at the time of exit from @var{forms}, that
1677 frame's selected window is left alone. If the previously selected
1678 window is no longer live, then whatever window is selected at the end of
1679 @var{forms} remains selected. The current buffer is restored if and
1680 only if it is still live when exiting @var{forms}.
1682 This macro changes neither the ordering of recently selected windows nor
1686 @defmac with-selected-window window forms@dots{}
1687 This macro selects @var{window}, executes @var{forms} in sequence, then
1688 restores the previously selected window and current buffer. The ordering
1689 of recently selected windows and the buffer list remain unchanged unless
1690 you deliberately change them within @var{forms}, for example, by calling
1691 @code{select-window} with argument @var{norecord} @code{nil}.
1693 The order of recently selected windows and the buffer list are not
1694 changed by this macro.
1697 @cindex frame selected window
1698 @cindex window selected within frame
1699 Earlier (@pxref{Basic Windows}) we mentioned that at any time, exactly
1700 one window on any frame is selected within the frame. The significance
1701 of this designation is that selecting the frame also selects this
1702 window. Conversely, selecting a window for Emacs with
1703 @code{select-window} also makes that window selected within its frame.
1705 @defun frame-selected-window &optional frame
1706 This function returns the window on @var{frame} that is selected within
1707 @var{frame}. The optional argument @var{frame} must denote a live frame
1708 and defaults to the selected one.
1711 @defun set-frame-selected-window frame window &optional norecord
1712 This function sets the selected window of frame @var{frame} to
1713 @var{window}. The argument @var{frame} must denote a live frame and
1714 defaults to the selected one. If @var{frame} is the selected frame,
1715 this also makes @var{window} the selected window. The argument
1716 @var{window} must denote a live window. This function returns
1719 Optional argument @var{norecord} non-@code{nil} means to neither change
1720 the list of most recently selected windows (@pxref{Selecting Windows})
1721 nor the buffer list (@pxref{The Buffer List}).
1725 @node Cyclic Window Ordering
1726 @section Cyclic Ordering of Windows
1727 @cindex cyclic ordering of windows
1728 @cindex ordering of windows, cyclic
1729 @cindex window ordering, cyclic
1731 When you use the command @kbd{C-x o} (@code{other-window}) to select
1732 some other window, it moves through live windows in a specific order.
1733 For any given configuration of windows, this order never varies. It is
1734 called the @dfn{cyclic ordering of windows}.
1736 For a particular frame, this ordering is determined by the window
1737 tree of that frame, see @ref{Windows and Frames}. More precisely, the
1738 ordering is obtained by a depth-first traversal of the frame's window
1739 tree supplemented, if requested, by the frame's minibuffer window.
1741 If there's just one live frame, the cyclic ordering is the ordering
1742 for that frame. Otherwise, the cyclic ordering is obtained by appending
1743 the orderings for individual frames in order of the list of all live
1744 frames, @ref{Finding All Frames}. In any case, the ordering is made
1745 ``cyclic'' by having the last window precede the first window in the
1748 @defun next-window &optional window minibuf all-frames
1749 @cindex minibuffer window, and @code{next-window}
1750 This function returns the window following @var{window} in the cyclic
1751 ordering of windows. The argument @var{window} must specify a live
1752 window and defaults to the selected one.
1754 The optional argument @var{minibuf} specifies whether minibuffer windows
1755 shall be included in the cyclic ordering. Normally, when @var{minibuf}
1756 is @code{nil}, a minibuffer window is included only if it is currently
1757 ``active''; this matches the behavior of @kbd{C-x o}. (Note that a
1758 minibuffer window is active as long as its minibuffer is in use; see
1761 If @var{minibuf} is @code{t}, the cyclic ordering includes all
1762 minibuffer windows. If @var{minibuf} is neither @code{t} nor
1763 @code{nil}, minibuffer windows are not included even if they are active.
1765 The optional argument @var{all-frames} specifies which frames to
1766 consider. Here are the possible values and their meanings:
1770 means consider all windows on @var{window}'s frame, plus the minibuffer
1771 window used by that frame even if it lies in some other frame. If the
1772 minibuffer counts (as determined by @var{minibuf}), then all windows on
1773 all frames that share that minibuffer count too.
1776 means consider all windows on all existing frames.
1778 @item @code{visible}
1779 means consider all windows on all visible frames. (To get useful
1780 results, ensure that @var{window} is on a visible frame.)
1783 means consider all windows on all visible or iconified frames.
1786 means consider all windows on that frame.
1789 means consider the windows on @var{window}'s frame, and no others.
1792 This example assumes there are two windows, both displaying the
1793 buffer @samp{windows.texi}:
1798 @result{} #<window 56 on windows.texi>
1801 (next-window (selected-window))
1802 @result{} #<window 52 on windows.texi>
1805 (next-window (next-window (selected-window)))
1806 @result{} #<window 56 on windows.texi>
1811 @defun previous-window &optional window minibuf all-frames
1812 This function returns the window preceding @var{window} in the cyclic
1813 ordering of windows. The other arguments specify which windows to
1814 consider as in @code{next-window}.
1817 @deffn Command other-window count &optional all-frames
1818 This function selects another window in the cyclic ordering of windows.
1819 @var{count} specifies the number of windows to skip in the ordering,
1820 starting with the selected window, before making the selection. If
1821 @var{count} is a positive number, it skips @var{count} windows forwards.
1822 @var{count} negative means skip @minus{}@var{count} windows backwards.
1823 If @var{count} is zero, it does not skip any window, thus re-selecting
1824 the selected window. In an interactive call, @var{count} is the numeric
1827 The optional argument @var{all-frames} has the same meaning as in
1828 @code{next-window}, but the @var{minibuf} argument of @code{next-window}
1829 is always effectively @code{nil}. This function returns @code{nil}.
1831 This function does not select a window that has a non-@code{nil}
1832 @code{no-other-window} window parameter (@pxref{Window Parameters}).
1835 The following function returns a copy of the list of windows in the
1838 @defun window-list-1 &optional window &optional minibuf &optional all_frames
1839 This function returns a list of live windows. The optional arguments
1840 @var{minibuf} and @var{all-frames} specify the set of windows to include
1841 in the list. See the description of @code{next-window} for details.
1843 The optional argument @var{window} specifies the first window to list
1844 and defaults to the selected window. If @var{window} is not on the list
1845 of windows returned, some other window will be listed first but no error
1849 The functions described below use @code{window-list-1} for generating a
1850 copy of the list of all relevant windows. Hence, any change of the
1851 window configuration that occurs while one of these functions is
1852 executed is @emph{not} reflected in the list of windows investigated.
1854 @defun walk-windows proc &optional minibuf all-frames
1855 This function cycles through live windows. It calls the function
1856 @var{proc} once for each window, with the window as its sole argument.
1858 The optional arguments @var{minibuf} and @var{all-frames} specify the
1859 set of windows to include in the walk, see @code{next-window} above. If
1860 @var{all-frames} specifies a frame, the first window walked is the first
1861 window on that frame as returned by @code{frame-first-window} and not
1862 necessarily the selected window.
1864 If @var{proc} changes the window configuration by splitting or deleting
1865 windows, that change is not reflected in the set of windows walked.
1866 That set is determined entirely by the set of live windows at the time
1867 this function was invoked.
1870 The following function allows to determine whether a specific window is
1871 the only live window.
1873 @defun one-window-p &optional no-mini all-frames
1874 This function returns non-@code{nil} if the selected window is the only
1877 The optional argument @var{no-mini}, if non-@code{nil}, means don't
1878 count the minibuffer even if it is active; otherwise, the minibuffer
1879 window is counted when it is active. The optional argument
1880 @var{all-frames} has the same meaning as for @code{next-window}, see
1884 @cindex finding windows
1885 The following functions choose (but do not select) one of the windows
1886 on the screen, offering various criteria for the choice.
1888 @cindex least recently used window
1889 @defun get-lru-window &optional all-frames dedicated
1890 This function returns the window least recently ``used'' (that is,
1891 selected). If any full-width windows are present, it only considers
1892 these. The optional argument @var{all-frames} has the same meaning as
1893 in @code{next-window}.
1895 The selected window is returned if it is the only candidate. A
1896 minibuffer window is never a candidate. A dedicated window
1897 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1898 argument @var{dedicated} is non-@code{nil}.
1901 @cindex largest window
1902 @defun get-largest-window &optional all-frames dedicated
1903 This function returns the window with the largest area (height times
1904 width). A minibuffer window is never a candidate. A dedicated window
1905 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1906 argument @var{dedicated} is non-@code{nil}.
1908 If there are two candidate windows of the same size, this function
1909 prefers the one that comes first in the cyclic ordering of windows,
1910 starting from the selected window.
1912 The optional argument @var{all-frames} specifies which set of windows to
1913 consider as with @code{next-window}, see above.
1916 @cindex window that satisfies a predicate
1917 @cindex conditional selection of windows
1918 @defun get-window-with-predicate predicate &optional minibuf all-frames default
1919 This function returns a window satisfying @var{predicate}. It cycles
1920 through all visible windows calling @var{predicate} on each one of them
1921 with that window as its argument. The function returns the first window
1922 for which @var{predicate} returns a non-@code{nil} value; if that never
1923 happens, it returns @var{default} (which defaults to @code{nil}).
1925 The optional arguments @var{minibuf} and @var{all-frames} specify the
1926 set of windows to investigate. See the description of
1927 @code{next-window} for details.
1930 @node Buffers and Windows
1931 @section Buffers and Windows
1932 @cindex examining windows
1933 @cindex windows, controlling precisely
1934 @cindex buffers, controlled in windows
1936 To find out which buffer is displayed in a given window the following
1939 @defun window-buffer &optional window
1940 This function returns the buffer that @var{window} is displaying. The
1941 argument @var{window} can be any window and defaults to the selected
1942 one. If @var{window} is an internal window, this function returns
1946 The basic, low-level function to associate a window with a buffer is
1947 @code{set-window-buffer}. Higher-level functions like
1948 @code{switch-to-buffer} and @code{display-buffer} try to obey a number
1949 of user customizations regulating which windows are supposed to
1950 display which buffers. @xref{Switching Buffers}. When writing an
1951 application, you should avoid using @code{set-window-buffer} unless
1952 you are sure you need it.
1954 @defun set-window-buffer window buffer-or-name &optional keep-margins
1955 This function makes @var{window} display @var{buffer-or-name} and
1956 returns @code{nil}. The argument @var{window} has to denote a live
1957 window and defaults to the selected one. The argument
1958 @var{buffer-or-name} must specify a buffer or the name of an existing
1959 buffer. An error is signalled when @var{window} is @dfn{strongly}
1960 dedicated to its buffer (@pxref{Dedicated Windows}) and does not already
1961 display @var{buffer-or-name}.
1963 Normally, displaying @var{buffer-or-name} in @var{window} resets the
1964 window's position, display margins, fringe widths, and scroll bar
1965 settings based on the local variables of the specified buffer. However,
1966 if the optional argument @var{keep-margins} is non-@code{nil}, display
1967 margins and fringe widths of @var{window} remain unchanged.
1970 This function is the fundamental primitive for changing which buffer is
1971 displayed in a window, and all ways of doing that call this function.
1972 Neither the selected window nor the current buffer are changed by this
1975 This function runs @code{window-scroll-functions} before running
1976 @code{window-configuration-change-hook}, see @ref{Window Hooks}.
1979 @defvar buffer-display-count
1980 This buffer-local variable records the number of times a buffer has been
1981 displayed in a window. It is incremented each time
1982 @code{set-window-buffer} is called for the buffer.
1985 @defvar buffer-display-time
1986 This variable records the time at which a buffer was last made visible
1987 in a window. It is always local in each buffer; each time
1988 @code{set-window-buffer} is called, it sets this variable to
1989 @code{(current-time)} in the specified buffer (@pxref{Time of Day}).
1990 When a buffer is first created, @code{buffer-display-time} starts out
1991 with the value @code{nil}.
1994 @defun get-buffer-window &optional buffer-or-name all-frames
1995 This function returns a window displaying @var{buffer-or-name}, or
1996 @code{nil} if there is none. If there are several such windows, then
1997 the function returns the first one in the cyclic ordering of windows,
1998 starting from the selected window, @xref{Cyclic Window Ordering}.
2000 The argument @var{buffer-or-name} may be a buffer or a buffer name and
2001 defaults to the current buffer. The optional argument @var{all-frames}
2002 specifies which windows to consider:
2006 @code{nil} means consider windows on the selected frame.
2008 @code{t} means consider windows on all existing frames.
2010 @code{visible} means consider windows on all visible frames.
2012 0 means consider windows on all visible or iconified frames.
2014 A frame means consider windows on that frame only.
2017 Observe that the behavior of @code{get-buffer-window} may differ from
2018 that of @code{next-window} (@pxref{Cyclic Window Ordering}) when
2019 @var{all-frames} equals @code{nil} or any value not listed here.
2020 Perhaps we will change @code{get-buffer-window} in the future to make it
2021 compatible with the other functions.
2024 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
2025 This function returns a list of all windows currently displaying
2026 @var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer
2027 or the name of an existing buffer and defaults to the current buffer.
2029 The two remaining arguments work like the same-named arguments of
2030 @code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
2031 like the optional arguments of @code{get-buffer-window}.
2034 @deffn Command replace-buffer-in-windows &optional buffer-or-name
2035 This command replaces @var{buffer-or-name} with some other buffer, in
2036 all windows displaying it. For each such window, it choose another
2037 buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
2039 The argument @var{buffer-or-name} may be a buffer, or the name of an
2040 existing buffer; it defaults to the current buffer.
2042 If a window displaying @var{buffer-or-name} is dedicated
2043 (@pxref{Dedicated Windows}) and is not the only window on its frame,
2044 that window is deleted. If that window is the only window on its frame
2045 and there are other frames on the frame's terminal, that frame is dealt
2046 with by the function spcecified by @code{frame-auto-hide-function}
2047 (@pxref{Quitting Windows}). Otherwise, the buffer provided by the
2048 function @code{switch-to-prev-buffer} (@pxref{Window History}) is
2049 displayed in the window instead.
2053 @node Switching Buffers
2054 @section Switching to a Buffer in a Window
2055 @cindex switching to a buffer
2056 @cindex displaying a buffer
2058 This section describes high-level functions for switching to a
2059 specified buffer in some window.
2061 Do @emph{not} use these functions to make a buffer temporarily
2062 current just so a Lisp program can access or modify it. They have
2063 side-effects, such as changing window histories (@pxref{Window
2064 History}), which will surprise the user if used that way. If you want
2065 to make a buffer current to modify it in Lisp, use
2066 @code{with-current-buffer}, @code{save-current-buffer}, or
2067 @code{set-buffer}. @xref{Current Buffer}.
2069 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
2070 This function displays @var{buffer-or-name} in the selected window,
2071 and makes it the current buffer. (In contrast, @code{set-buffer}
2072 makes the buffer current but does not display it; @pxref{Current
2073 Buffer}). It is often used interactively (as the binding of @kbd{C-x
2074 b}), as well as in Lisp programs. The return value is the buffer
2077 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2078 returned by @code{other-buffer} (@pxref{The Buffer List}). If
2079 @var{buffer-or-name} is a string that is not the name of any existing
2080 buffer, this function creates a new buffer with that name; the new
2081 buffer's major mode is determined by the variable @code{major-mode}
2082 (@pxref{Major Modes}).
2084 Normally the specified buffer is put at the front of the buffer
2085 list---both the global buffer list and the selected frame's buffer
2086 list (@pxref{The Buffer List}). However, this is not done if the
2087 optional argument @var{norecord} is non-@code{nil}.
2089 If this function is unable to display the buffer in the selected
2090 window---usually because the selected window is a minibuffer window or
2091 is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then
2092 it normally tries to display the buffer in some other window, in the
2093 manner of @code{pop-to-buffer} (see below). However, if the optional
2094 argument @var{force-same-window} is non-@code{nil}, it signals an error
2098 The next two functions are similar to @code{switch-to-buffer}, except
2099 for the described features.
2101 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
2102 This function makes the buffer specified by @var{buffer-or-name}
2103 current and displays it in some window other than the selected window.
2104 It uses the function @code{pop-to-buffer} internally (see below).
2106 If the selected window already displays the specified buffer, it
2107 continues to do so, but another window is nonetheless found to display
2110 The @var{buffer-or-name} and @var{norecord} arguments have the same
2111 meanings as in @code{switch-to-buffer}.
2114 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
2115 This function makes the buffer specified by @var{buffer-or-name}
2116 current and displays it, usually in a new frame. It uses the function
2117 @code{pop-to-buffer} (see below).
2119 If the specified buffer is already displayed in another window, in any
2120 frame on the current terminal, this switches to that window instead of
2121 creating a new frame. However, the selected window is never used for
2124 The @var{buffer-or-name} and @var{norecord} arguments have the same
2125 meanings as in @code{switch-to-buffer}.
2128 The above commands use @code{pop-to-buffer}, which is the function
2129 used by Lisp programs to flexibly display a buffer in some window and
2130 select that window for editing:
2132 @defun pop-to-buffer buffer-or-name &optional action norecord
2133 This function makes @var{buffer-or-name} the current buffer and
2134 displays it in some window, preferably not the window previously
2135 selected. It then selects the displaying window. If that window is
2136 on a different graphical frame, that frame is given input focus if
2137 possible (@pxref{Input Focus}). The return value is the buffer that
2140 This function uses @code{display-buffer} to display the buffer, so all
2141 the variables affecting @code{display-buffer} will affect it as well.
2142 @xref{Choosing Window}.
2144 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2145 returned by @code{other-buffer} (@pxref{The Buffer List}). If
2146 @var{buffer-or-name} is a string that is not the name of any existing
2147 buffer, this function creates a new buffer with that name; the new
2148 buffer's major mode is determined by the variable @code{major-mode}
2149 (@pxref{Major Modes}).
2151 If @var{action} is non-@code{nil}, it should be a display action to
2152 pass to @code{display-buffer} (@pxref{Choosing Window}).
2153 Alternatively, a non-@code{nil}, non-list value means to pop to a
2154 window other than the selected one---even if the buffer is already
2155 displayed in the selected window.
2157 Like @code{switch-to-buffer}, this function updates the buffer list
2158 unless @var{norecord} is non-@code{nil}.
2161 @node Choosing Window
2162 @section Choosing a Window for Display
2164 The command @code{display-buffer} flexibly chooses a window for
2165 display, and displays a specified buffer in that window. It can be
2166 called interactively, via the key binding @kbd{C-x 4 o}. It is also
2167 used as a subroutine by many functions and commands, including
2168 @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
2171 @cindex display action
2172 @cindex action function, for display-buffer
2173 @cindex action alist, for display-buffer
2174 This command performs several complex steps to find a window to
2175 display in. These steps are described by means of @dfn{display
2176 actions}, which have the form @code{(@var{function} . @var{alist})}.
2177 Here, @var{function} is either a function or a list of functions,
2178 which we refer to as @dfn{action functions}; @var{alist} is an
2179 association list, which we refer to as @dfn{action alists}.
2181 An action function accepts two arguments: the buffer to display and
2182 an action alist. It attempts to display the buffer in some window,
2183 picking or creating a window according to its own criteria. If
2184 successful, it returns the window; otherwise, it returns @code{nil}.
2185 @xref{Display Action Functions}, for a list of predefined action
2188 @code{display-buffer} works by combining display actions from
2189 several sources, and calling the action functions in turn, until one
2190 of them manages to display the buffer and returns a non-@code{nil}
2193 @deffn Command display-buffer buffer-or-name &optional action frame
2194 This command makes @var{buffer-or-name} appear in some window, without
2195 selecting the window or making the buffer current. The argument
2196 @var{buffer-or-name} must be a buffer or the name of an existing
2197 buffer. The return value is the window chosen to display the buffer.
2199 The optional argument @var{action}, if non-@code{nil}, should normally
2200 be a display action (described above). @code{display-buffer} builds a
2201 list of action functions and an action alist, by consolidating display
2202 actions from the following sources (in order):
2206 The variable @code{display-buffer-overriding-action}.
2209 The user option @code{display-buffer-alist}.
2212 The @var{action} argument.
2215 The user option @code{display-buffer-base-action}.
2218 The constant @code{display-buffer-fallback-action}.
2222 Each action function is called in turn, passing the buffer as the
2223 first argument and the combined action alist as the second argument,
2224 until one of the functions returns non-nil.
2226 The argument @var{action} can also have a non-@code{nil}, non-list
2227 value. This has the special meaning that the buffer should be
2228 displayed in a window other than the selected one, even if the
2229 selected window is already displaying it. If called interactively
2230 with a prefix argument, @var{action} is @code{t}.
2232 The optional argument @var{frame}, if non-@code{nil}, specifies which
2233 frames to check when deciding whether the buffer is already displayed.
2234 It is equivalent to adding an element @code{(reusable-frames
2235 . @var{frame})} to the action alist of @var{action}. @xref{Display
2239 @defvar display-buffer-overriding-action
2240 The value of this variable should be a display action, which is
2241 treated with the highest priority by @code{display-buffer}. The
2242 default value is empty, i.e. @code{(nil . nil)}.
2245 @defopt display-buffer-alist
2246 The value of this option is an alist mapping regular expressions to
2247 display actions. If the name of the buffer passed to
2248 @code{display-buffer} matches a regular expression in this alist, then
2249 @code{display-buffer} uses the corresponding display action.
2252 @defopt display-buffer-base-action
2253 The value of this option should be a display action. This option can
2254 be used to define a ``standard'' display action for calls to
2255 @code{display-buffer}.
2258 @defvr Constant display-buffer-fallback-action
2259 This display action specifies the fallback behavior for
2260 @code{display-buffer} if no other display actions are given.
2263 @node Display Action Functions
2264 @section Action Functions for @code{display-buffer}
2266 The following basic action functions are defined in Emacs. Each of
2267 these functions takes two arguments: @var{buffer}, the buffer to
2268 display, and @var{alist}, an action alist. Each action function
2269 returns the window if it succeeds, and @code{nil} if it fails.
2271 @defun display-buffer-same-window buffer alist
2272 This function tries to display @var{buffer} in the selected window.
2273 It fails if the selected window is a minibuffer window or is dedicated
2274 to another buffer (@pxref{Dedicated Windows}). It also fails if
2275 @var{alist} has a non-nil @code{inhibit-same-window} entry.
2278 @defun display-buffer-reuse-window buffer alist
2279 This function tries to ``display'' @var{buffer} by finding a window
2280 that is already displaying it.
2282 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2283 the selected window is not eligible for reuse.
2285 If @var{alist} contains a @code{reusable-frames} entry, its value
2286 determines which frames to search for a reusable window:
2290 @code{nil} means consider windows on the selected frame.
2291 (Actually, the last non-minibuffer frame.)
2293 @code{t} means consider windows on all frames.
2295 @code{visible} means consider windows on all visible frames.
2297 0 means consider windows on all visible or iconified frames.
2299 A frame means consider windows on that frame only.
2302 If @var{alist} contains no @code{reusable-frames} entry, this function
2303 normally searches just the selected frame; however, if either the
2304 variable @code{display-buffer-reuse-frames} or the variable
2305 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
2306 current terminal. @xref{Choosing Window Options}.
2309 @defun display-buffer-pop-up-frame buffer alist
2310 This function creates a new frame, and displays the buffer in that
2314 @defun display-buffer-pop-up-window buffer alist
2315 This function tries to display @var{buffer} by splitting the largest
2316 or least recently-used window. It uses @code{split-window-sensibly}
2317 as a subroutine (@pxref{Choosing Window Options}).
2320 @defun display-buffer-use-some-window buffer alist
2321 This function tries to display @var{buffer} by choosing an existing
2322 window and displaying the buffer in that window. It can fail if all
2323 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
2326 @node Choosing Window Options
2327 @section Additional Options for Displaying Buffers
2329 The behavior of the standard display actions of @code{display-buffer}
2330 (@pxref{Choosing Window}) can be modified by a variety of user
2333 @defopt display-buffer-reuse-frames
2334 If this variable is non-@code{nil}, @code{display-buffer} searches
2335 visible and iconified frames for a window displaying
2336 @var{buffer-or-name}. If there is such a window, @code{display-buffer}
2337 makes that window's frame visible and raises it if necessary, and
2338 returns the window. If there is no such window or
2339 @code{display-buffer-reuse-frames} is @code{nil}, the behavior of
2340 @code{display-buffer} is determined by the variables described next.
2343 @defopt pop-up-windows
2344 This variable specifies whether @code{display-buffer} is allowed to
2345 split (@pxref{Splitting Windows}) an existing window. If this variable
2346 is non-@code{nil}, @code{display-buffer} tries to split the largest or
2347 least recently used window on the selected frame. (If the selected
2348 frame is a minibuffer-only frame, @code{display-buffer} tries to split a
2349 window on another frame instead.) If this variable is @code{nil} or the
2350 variable @code{pop-up-frames} (see below) is non-@code{nil},
2351 @code{display-buffer} does not split any window.
2354 @defopt split-window-preferred-function
2355 This variable must specify a function with one argument, which is a
2356 window. The @code{display-buffer} routines will call this function with
2357 one or more candidate windows when they look for a window to split. The
2358 function is expected to split that window and return the new window. If
2359 the function returns @code{nil}, this means that the argument window
2360 cannot (or shall not) be split.
2362 The default value of @code{split-window-preferred-function} is the
2363 function @code{split-window-sensibly} described below. If you
2364 customize this option, bear in mind that the @code{display-buffer}
2365 routines may call your function up to two times when trying to split a
2366 window. The argument of the first call is the largest window on the
2367 chosen frame (as returned by @code{get-largest-window}). If that call
2368 fails to return a live window, your function is called a second time
2369 with the least recently used window on that frame (as returned by
2370 @code{get-lru-window}).
2372 The function specified by this option may try to split any other window
2373 instead of the argument window. Note that the window selected at the
2374 time @code{display-buffer} was invoked is still selected when your
2375 function is called. Hence, you can split the selected window (instead
2376 of the largest or least recently used one) by simply ignoring the window
2377 argument in the body of your function. You can even choose to not split
2378 any window as long as the return value of your function specifies a live
2379 window or @code{nil}, but you are not encouraged to do so
2380 unconditionally. If you want @code{display-buffer} to never split any
2381 windows, set @code{pop-up-windows} to @code{nil}.
2384 @defun split-window-sensibly window
2385 This function takes a window as argument and tries to split that window
2386 in a suitable way. The two variables described next are useful for
2387 tuning the behavior of this function.
2390 @defopt split-height-threshold
2391 This variable specifies whether @code{split-window-sensibly} may split
2392 windows vertically. If it is an integer, @code{split-window-sensibly}
2393 tries to vertically split a window only if it has at least this many
2394 lines. If the window has less lines, splitting fails, or the value of
2395 this variable is @code{nil}, @code{split-window-sensibly} will try to
2396 split the window horizontally, subject to restrictions of
2397 @code{split-width-threshold} (see below). If splitting horizontally
2398 fails too and the window is the only window on its frame,
2399 @code{split-window-sensibly} will try to split the window vertically
2400 disregarding the value of @code{split-height-threshold}. If this fails
2401 as well, @code{split-window-sensibly} returns @code{nil}.
2403 @code{split-window-sensibly} does not split vertically a window whose
2404 height is fixed (@pxref{Resizing Windows}). Also, it vertically splits
2405 a window only if the space taken up by that window can accommodate two
2406 windows one above the other that are both at least
2407 @code{window-min-height} lines tall. Moreover, if the window that shall
2408 be split has a mode line, @code{split-window-sensibly} does not split
2409 the window unless the new window can accommodate a mode line too.
2412 @defopt split-width-threshold
2413 This variable specifies whether @code{split-window-sensibly} may split
2414 windows horizontally. If it is an integer, @code{split-window-sensibly}
2415 tries to horizontally split a window only if it has at least this many
2416 columns. If it is @code{nil}, @code{split-window-sensibly} will not
2417 split the window horizontally. (It still might split the window
2418 vertically, though, see above.)
2420 @code{split-window-sensibly} does not split horizontally a window if
2421 that window's width is fixed (@pxref{Resizing Windows}). Also, it
2422 horizontally splits a window only if the space that window takes up can
2423 accommodate two windows side by side that are both at least
2424 @code{window-min-width} columns wide.
2427 @defopt even-window-heights
2428 This variable specifies whether @code{display-buffer} should even out
2429 window heights if the buffer gets displayed in an existing window, above
2430 or beneath another window. If @code{even-window-heights} is
2431 non-@code{nil}, the default, window heights will be evened out. If
2432 either of the involved window has fixed height (@pxref{Resizing
2433 Windows}) or @code{even-window-heights} is @code{nil}, the original
2434 window heights will be left alone.
2438 @defopt pop-up-frames
2439 This variable specifies whether @code{display-buffer} should make new
2440 frames. If it is non-@code{nil}, @code{display-buffer} looks for a
2441 window already displaying @var{buffer-or-name} on any visible or
2442 iconified frame. If it finds such a window, it makes that window's
2443 frame visible and raises it if necessary, and returns the window.
2444 Otherwise it makes a new frame, unless the variable's value is
2445 @code{graphic-only} and the selected frame is not on a graphic display.
2446 @xref{Frames}, for more information.
2448 Note that the value of @code{pop-up-windows} does not matter if
2449 @code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is
2450 @code{nil}, then @code{display-buffer} either splits a window or reuses
2455 @defopt pop-up-frame-function
2456 This variable specifies how to make a new frame if @code{pop-up-frames}
2459 The value of this variable must be a function of no arguments. When
2460 @code{display-buffer} makes a new frame, it does so by calling that
2461 function, which should return a frame. The default value of this
2462 variable is a function that creates a frame using the parameters
2463 specified by @code{pop-up-frame-alist} described next.
2466 @defopt pop-up-frame-alist
2467 This variable holds an alist specifying frame parameters used by the
2468 default value of @code{pop-up-frame-function} for making new frames.
2469 @xref{Frame Parameters}, for more information about frame parameters.
2472 @defopt special-display-buffer-names
2473 A list of buffer names identifying buffers that should be displayed
2474 specially. If the name of @var{buffer-or-name} is in this list,
2475 @code{display-buffer} handles the buffer specially. By default, special
2476 display means to give the buffer a dedicated frame.
2478 If an element is a list, instead of a string, then the @sc{car} of that
2479 list is the buffer name, and the rest of that list says how to create
2480 the frame. There are two possibilities for the rest of that list (its
2481 @sc{cdr}): It can be an alist, specifying frame parameters, or it can
2482 contain a function and arguments to give to it. (The function's first
2483 argument is always the buffer to be displayed; the arguments from the
2484 list come after that.)
2489 (("myfile" (minibuffer) (menu-bar-lines . 0)))
2493 specifies to display a buffer named @samp{myfile} in a dedicated frame
2494 with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
2496 The list of frame parameters can also use the phony frame parameters
2497 @code{same-frame} and @code{same-window}. If the specified frame
2498 parameters include @code{(same-window . @var{value})} and @var{value}
2499 is non-@code{nil}, that means to display the buffer in the current
2500 selected window. Otherwise, if they include @code{(same-frame .
2501 @var{value})} and @var{value} is non-@code{nil}, that means to display
2502 the buffer in a new window in the currently selected frame.
2505 @defopt special-display-regexps
2506 A list of regular expressions specifying buffers that should be
2507 displayed specially. If the buffer's name matches any of the regular
2508 expressions in this list, @code{display-buffer} handles the buffer
2509 specially. By default, special display means to give the buffer a
2512 If an element is a list, instead of a string, then the @sc{car} of the
2513 list is the regular expression, and the rest of the list says how to
2514 create the frame. See @code{special-display-buffer-names} above.
2517 @defun special-display-p buffer-name
2518 This function returns non-@code{nil} if displaying a buffer
2519 named @var{buffer-name} with @code{display-buffer} would
2520 create a special frame. The value is @code{t} if it would
2521 use the default frame parameters, or else the specified list
2522 of frame parameters.
2525 @defopt special-display-function
2526 This variable holds the function to call to display a buffer specially.
2527 It receives the buffer as an argument, and should return the window in
2528 which it is displayed. The default value of this variable is
2529 @code{special-display-popup-frame}, see below.
2532 @defun special-display-popup-frame buffer &optional args
2533 This function tries to make @var{buffer} visible in a frame of its own.
2534 If @var{buffer} is already displayed in some window, it makes that
2535 window's frame visible and raises it. Otherwise, it creates a frame
2536 that is dedicated to @var{buffer}. The return value is the window used
2537 to display @var{buffer}.
2539 If @var{args} is an alist, it specifies frame parameters for the new
2540 frame. If @var{args} is a list whose @sc{car} is a symbol, then
2541 @code{(car @var{args})} is called as a function to actually create and
2542 set up the frame; it is called with @var{buffer} as first argument, and
2543 @code{(cdr @var{args})} as additional arguments.
2545 This function always uses an existing window displaying @var{buffer},
2546 whether or not it is in a frame of its own; but if you set up the above
2547 variables in your init file, before @var{buffer} was created, then
2548 presumably the window was previously made by this function.
2551 @defopt special-display-frame-alist
2552 @anchor{Definition of special-display-frame-alist}
2553 This variable holds frame parameters for
2554 @code{special-display-popup-frame} to use when it creates a frame.
2557 @defopt same-window-buffer-names
2558 A list of buffer names for buffers that should be displayed in the
2559 selected window. If the buffer's name is in this list,
2560 @code{display-buffer} handles the buffer by switching to it in the
2564 @defopt same-window-regexps
2565 A list of regular expressions that specify buffers that should be
2566 displayed in the selected window. If the buffer's name matches any of
2567 the regular expressions in this list, @code{display-buffer} handles the
2568 buffer by switching to it in the selected window.
2571 @defun same-window-p buffer-name
2572 This function returns @code{t} if displaying a buffer
2573 named @var{buffer-name} with @code{display-buffer} would
2574 put it in the selected window.
2578 @defopt display-buffer-function
2579 This variable is the most flexible way to customize the behavior of
2580 @code{display-buffer}. If it is non-@code{nil}, it should be a function
2581 that @code{display-buffer} calls to do the work. The function should
2582 accept two arguments, the first two arguments that @code{display-buffer}
2583 received. It should choose or create a window, display the specified
2584 buffer in it, and then return the window.
2586 This variable takes precedence over all the other options described
2590 If all options described above fail to produce a suitable window,
2591 @code{display-buffer} tries to reuse an existing window. As a last
2592 resort, it will try to display @var{buffer-or-name} on a separate frame.
2593 In that case, the value of @code{pop-up-frames} is disregarded.
2596 @node Window History
2597 @section Window History
2598 @cindex window history
2600 Each window remembers the buffers it has displayed earlier and the order
2601 in which these buffers have been removed from it. This history is used,
2602 for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and
2603 Windows}). This list is automatically maintained by Emacs, but you can
2604 use the following functions to explicitly inspect or alter it:
2606 @defun window-prev-buffers &optional window
2607 This function returns a list specifying the previous contents of
2608 @var{window}, which should be a live window and defaults to the
2611 Each list element has the form @code{(@var{buffer} @var{window-start}
2612 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
2613 the window, @var{window-start} is the window start position when that
2614 buffer was last shown, and @var{window-pos} is the point position when
2615 that buffer was last shown.
2617 The list is ordered so that earlier elements correspond to more
2618 recently-shown buffers, and the first element usually corresponds to the
2619 buffer most recently removed from the window.
2622 @defun set-window-prev-buffers window prev-buffers
2623 This function sets @var{window}'s previous buffers to the value of
2624 @var{prev-buffers}. The argument @var{window} must be a live window
2625 and defaults to the selected one. The argument @var{prev-buffers}
2626 should be a list of the same form as that returned by
2627 @code{window-prev-buffers}.
2630 In addition, each buffer maintains a list of @dfn{next buffers}, which
2631 is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
2632 below). This list is mainly used by @code{switch-to-prev-buffer} and
2633 @code{switch-to-next-buffer} for choosing buffers to switch to.
2635 @defun window-next-buffers &optional window
2636 This function returns the list of buffers recently re-shown in
2637 @var{window} via @code{switch-to-prev-buffer}. The @var{window}
2638 argument must denote a live window or @code{nil} (meaning the selected
2642 @defun set-window-next-buffers window next-buffers
2643 This function sets the next buffer list of @var{window} to
2644 @var{next-buffers}. The @var{window} argument should be a live window
2645 or @code{nil} (meaning the selected window). The argument
2646 @var{next-buffers} should be a list of buffers.
2649 The following commands can be used to cycle through the global buffer
2650 list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
2651 they cycle according to the specified window's history list, rather
2652 than the global buffer list. In addition, they restore
2653 window-specific window start and point positions, and may show a
2654 buffer even if it is already shown in another window. The
2655 @code{switch-to-prev-buffer} command, in particular, is used by
2656 @code{replace-buffer-in-windows}, @code{bury-buffer} and
2657 @code{quit-window} to find a replacement buffer for a window.
2659 @deffn Command switch-to-prev-buffer &optional window bury-or-kill
2660 This command displays the previous buffer in @var{window}. The
2661 argument @var{window} should be a live window or @code{nil} (meaning
2662 the selected window). If the optional argument @var{bury-or-kill} is
2663 non-@code{nil}, this means that the buffer currently shown in
2664 @var{window} is about to be buried or killed and consequently shall
2665 not be switched to in future invocations of this command.
2667 The previous buffer is usually the buffer shown before the buffer
2668 currently shown in @var{window}. However, a buffer that has been buried
2669 or killed or has been already shown by a recent invocation of
2670 @code{switch-to-prev-buffer} does not qualify as previous buffer.
2672 If repeated invocations of this command have already shown all buffers
2673 previously shown in @var{window}, further invocations will show buffers
2674 from the buffer list of the frame @var{window} appears on (@pxref{The
2678 @deffn Command switch-to-next-buffer &optional window
2679 This command switches to the next buffer in @var{window} thus undoing
2680 the effect of the last @code{switch-to-prev-buffer} command in
2681 @var{window}. The argument @var{window} must be a live window and
2682 defaults to the selected one.
2684 If there is no recent invocation of a @code{switch-to-prev-buffer} that
2685 can be undone, this function tries to show a buffer from the buffer list
2686 of the frame @var{window} appears on (@pxref{The Buffer List}).
2690 @node Dedicated Windows
2691 @section Dedicated Windows
2692 @cindex dedicated window
2694 Functions for displaying a buffer can be told to not use specific
2695 windows by marking these windows as @dfn{dedicated} to their buffers.
2696 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
2697 window for displaying another buffer in it. @code{get-lru-window} and
2698 @code{get-largest-window} (@pxref{Selecting Windows}) do not consider
2699 dedicated windows as candidates when their @var{dedicated} argument is
2700 non-@code{nil}. The behavior of @code{set-window-buffer}
2701 (@pxref{Buffers and Windows}) with respect to dedicated windows is
2702 slightly different, see below.
2704 When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
2705 delete a dedicated window and that window is the only window on its
2706 frame, it deletes the window's frame too, provided there are other
2707 frames left. @code{replace-buffer-in-windows} (@pxref{Switching
2708 Buffers}) tries to delete all dedicated windows showing its buffer
2709 argument. When such a window is the only window on its frame, that
2710 frame is deleted, provided there are other frames left. If there are
2711 no more frames left, some other buffer is displayed in the window, and
2712 the window is marked as non-dedicated.
2714 When you kill a buffer (@pxref{Killing Buffers}) displayed in a
2715 dedicated window, any such window usually gets deleted too, since
2716 @code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
2717 up windows. Burying a buffer (@pxref{The Buffer List}) deletes the
2718 selected window if it is dedicated to that buffer. If, however, that
2719 window is the only window on its frame, @code{bury-buffer} displays
2720 another buffer in it and iconifies the frame.
2722 @defun window-dedicated-p &optional window
2723 This function returns non-@code{nil} if @var{window} is dedicated to its
2724 buffer and @code{nil} otherwise. More precisely, the return value is
2725 the value assigned by the last call of @code{set-window-dedicated-p} for
2726 @var{window} or @code{nil} if that function was never called with
2727 @var{window} as its argument. The default for @var{window} is the
2731 @defun set-window-dedicated-p window flag
2732 This function marks @var{window} as dedicated to its buffer if
2733 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
2735 As a special case, if @var{flag} is @code{t}, @var{window} becomes
2736 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
2737 signals an error when the window it acts upon is strongly dedicated to
2738 its buffer and does not already display the buffer it is asked to
2739 display. Other functions do not treat @code{t} differently from any
2740 non-@code{nil} value.
2744 @node Quitting Windows
2745 @section Quitting Windows
2747 When you want to get rid of a window used for displaying a buffer you
2748 can call @code{delete-window} or @code{delete-windows-on}
2749 (@pxref{Deleting Windows}) to remove that window from its frame. If the
2750 buffer is shown on a separate frame, you might want to call
2751 @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
2752 hand, a window has been reused for displaying the buffer, you might
2753 prefer showing the buffer previously shown in that window by calling the
2754 function @code{switch-to-prev-buffer} (@pxref{Window History}).
2755 Finally, you might want to either bury (@pxref{The Buffer List}) or kill
2756 (@pxref{Killing Buffers}) the window's buffer.
2758 The following function uses information on how the window for
2759 displaying the buffer was obtained in the first place thus attempting to
2760 automatize the above decisions for you.
2762 @deffn Command quit-window &optional kill window
2763 This command quits @var{window} and buries its buffer. The argument
2764 @var{window} must be a live window and defaults to the selected one.
2765 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
2766 instead of burying it.
2768 Quitting @var{window} means to proceed as follows: If @var{window} was
2769 created specially for displaying its current buffer, delete @var{window}
2770 provided its frame contains at least one other live window. If
2771 @var{window} is the only window on its frame and there are other frames
2772 on the frame's terminal, the value of @var{kill} determines how to
2773 proceed with the window. If @var{kill} is @code{nil}, the fate of the
2774 frame is determined by calling @code{frame-auto-hide-function} (see
2775 below) with that frame as sole argument. If @var{kill} is
2776 non-@code{nil}, the frame is deleted unconditionally.
2778 If @var{window} was reused for displaying its buffer, this command tries
2779 to display the buffer previously shown in it. It also tries to restore
2780 the window start (@pxref{Window Start and End}) and point (@pxref{Window
2781 Point}) positions of the previously shown buffer. If, in addition, the
2782 current buffer was temporarily resized, this command will also try to
2783 restore the original height of @var{window}.
2785 The three cases described so far require that the buffer shown in
2786 @var{window} is still the buffer displayed by the last buffer display
2787 function for this window. If another buffer has been shown in the
2788 meantime or the buffer previously shown no longer exists, this command
2789 calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some
2790 other buffer instead.
2793 The function @code{quit-window} bases its decisions on information
2794 stored in @var{window}'s @code{quit-restore} window parameter
2795 (@pxref{Window Parameters}) and resets that parameter to @code{nil}
2798 The following option specifies how to deal with a frame containing just
2799 one window that shall be either quit or whose buffer shall be buried.
2801 @defopt frame-auto-hide-function
2802 The function specified by this option is called to automatically hide
2803 frames. This function is called with one argument - a frame.
2805 The function specified here is called by @code{bury-buffer} (@pxref{The
2806 Buffer List}) when the selected window is dedicated and shows the buffer
2807 that shall be buried. It is also called by @code{quit-window} (see
2808 above) when the frame of the window that shall be quit has been
2809 specially created for displaying that window's buffer and the buffer
2812 The default is to call @code{iconify-frame} (@pxref{Visibility of
2813 Frames}). Alternatively, you may either specify @code{delete-frame}
2814 (@pxref{Deleting Frames}) to remove the frame from its display,
2815 @code{ignore} to leave the frame unchanged, or any other function that
2816 can take a frame as its sole argument.
2818 Note that the function specified by this option is called if and only if
2819 there's at least one other frame on the terminal of the frame it's
2820 supposed to handle and that frame contains only one live window.
2825 @section Windows and Point
2826 @cindex window position
2827 @cindex window point
2828 @cindex position in window
2829 @cindex point in window
2831 Each window has its own value of point (@pxref{Point}), independent of
2832 the value of point in other windows displaying the same buffer. This
2833 makes it useful to have multiple windows showing one buffer.
2837 The window point is established when a window is first created; it is
2838 initialized from the buffer's point, or from the window point of another
2839 window opened on the buffer if such a window exists.
2842 Selecting a window sets the value of point in its buffer from the
2843 window's value of point. Conversely, deselecting a window sets the
2844 window's value of point from that of the buffer. Thus, when you switch
2845 between windows that display a given buffer, the point value for the
2846 selected window is in effect in the buffer, while the point values for
2847 the other windows are stored in those windows.
2850 As long as the selected window displays the current buffer, the window's
2851 point and the buffer's point always move together; they remain equal.
2855 As far as the user is concerned, point is where the cursor is, and
2856 when the user switches to another buffer, the cursor jumps to the
2857 position of point in that buffer.
2859 @defun window-point &optional window
2860 This function returns the current position of point in @var{window}.
2861 For a nonselected window, this is the value point would have (in that
2862 window's buffer) if that window were selected. The default for
2863 @var{window} is the selected window.
2865 When @var{window} is the selected window and its buffer is also the
2866 current buffer, the value returned is the same as point in that buffer.
2867 Strictly speaking, it would be more correct to return the ``top-level''
2868 value of point, outside of any @code{save-excursion} forms. But that
2869 value is hard to find.
2872 @defun set-window-point window position
2873 This function positions point in @var{window} at position
2874 @var{position} in @var{window}'s buffer. It returns @var{position}.
2876 If @var{window} is selected, and its buffer is current,
2877 this simply does @code{goto-char}.
2880 @defvar window-point-insertion-type
2881 This variable specifies the marker insertion type (@pxref{Marker
2882 Insertion Types}) of @code{window-point}. The default is @code{nil},
2883 so @code{window-point} will stay behind text inserted there.
2886 @node Window Start and End
2887 @section The Window Start and End Positions
2888 @cindex window start position
2890 Each window maintains a marker used to keep track of a buffer position
2891 that specifies where in the buffer display should start. This position
2892 is called the @dfn{display-start} position of the window (or just the
2893 @dfn{start}). The character after this position is the one that appears
2894 at the upper left corner of the window. It is usually, but not
2895 inevitably, at the beginning of a text line.
2897 After switching windows or buffers, and in some other cases, if the
2898 window start is in the middle of a line, Emacs adjusts the window
2899 start to the start of a line. This prevents certain operations from
2900 leaving the window start at a meaningless point within a line. This
2901 feature may interfere with testing some Lisp code by executing it
2902 using the commands of Lisp mode, because they trigger this
2903 readjustment. To test such code, put it into a command and bind the
2906 @defun window-start &optional window
2907 @cindex window top line
2908 This function returns the display-start position of window
2909 @var{window}. If @var{window} is @code{nil}, the selected window is
2919 When you create a window, or display a different buffer in it, the
2920 display-start position is set to a display-start position recently used
2921 for the same buffer, or to @code{point-min} if the buffer doesn't have
2924 Redisplay updates the window-start position (if you have not specified
2925 it explicitly since the previous redisplay)---to make sure point appears
2926 on the screen. Nothing except redisplay automatically changes the
2927 window-start position; if you move point, do not expect the window-start
2928 position to change in response until after the next redisplay.
2930 For a realistic example of using @code{window-start}, see the
2931 description of @code{count-lines}. @xref{Definition of count-lines}.
2934 @cindex window end position
2935 @defun window-end &optional window update
2936 This function returns the position where display of its buffer ends in
2937 @var{window}. The default for @var{window} is the selected window.
2939 Simply changing the buffer text or moving point does not update the
2940 value that @code{window-end} returns. The value is updated only when
2941 Emacs redisplays and redisplay completes without being preempted.
2943 If the last redisplay of @var{window} was preempted, and did not finish,
2944 Emacs does not know the position of the end of display in that window.
2945 In that case, this function returns @code{nil}.
2947 If @var{update} is non-@code{nil}, @code{window-end} always returns an
2948 up-to-date value for where display ends, based on the current
2949 @code{window-start} value. If a previously saved value of that position
2950 is still valid, @code{window-end} returns that value; otherwise it
2951 computes the correct value by scanning the buffer text.
2953 Even if @var{update} is non-@code{nil}, @code{window-end} does not
2954 attempt to scroll the display if point has moved off the screen, the
2955 way real redisplay would do. It does not alter the
2956 @code{window-start} value. In effect, it reports where the displayed
2957 text will end if scrolling is not required.
2960 @defun set-window-start window position &optional noforce
2961 This function sets the display-start position of @var{window} to
2962 @var{position} in @var{window}'s buffer. It returns @var{position}.
2964 The display routines insist that the position of point be visible when a
2965 buffer is displayed. Normally, they change the display-start position
2966 (that is, scroll the window) whenever necessary to make point visible.
2967 However, if you specify the start position with this function using
2968 @code{nil} for @var{noforce}, it means you want display to start at
2969 @var{position} even if that would put the location of point off the
2970 screen. If this does place point off screen, the display routines move
2971 point to the left margin on the middle line in the window.
2973 For example, if point @w{is 1} and you set the start of the window
2974 @w{to 37}, the start of the next line, point will be ``above'' the top
2975 of the window. The display routines will automatically move point if
2976 it is still 1 when redisplay occurs. Here is an example:
2980 ;; @r{Here is what @samp{foo} looks like before executing}
2981 ;; @r{the @code{set-window-start} expression.}
2985 ---------- Buffer: foo ----------
2986 @point{}This is the contents of buffer foo.
2992 ---------- Buffer: foo ----------
3006 ;; @r{Here is what @samp{foo} looks like after executing}
3007 ;; @r{the @code{set-window-start} expression.}
3008 ---------- Buffer: foo ----------
3014 ---------- Buffer: foo ----------
3018 If @var{noforce} is non-@code{nil}, and @var{position} would place point
3019 off screen at the next redisplay, then redisplay computes a new window-start
3020 position that works well with point, and thus @var{position} is not used.
3023 @defun pos-visible-in-window-p &optional position window partially
3024 This function returns non-@code{nil} if @var{position} is within the
3025 range of text currently visible on the screen in @var{window}. It
3026 returns @code{nil} if @var{position} is scrolled vertically out of view.
3027 Locations that are partially obscured are not considered visible unless
3028 @var{partially} is non-@code{nil}. The argument @var{position} defaults
3029 to the current position of point in @var{window}; @var{window}, to the
3030 selected window. If @var{position} is @code{t}, that means to check the
3031 last visible position in @var{window}.
3033 This function considers only vertical scrolling. If @var{position} is
3034 out of view only because @var{window} has been scrolled horizontally,
3035 @code{pos-visible-in-window-p} returns non-@code{nil} anyway.
3036 @xref{Horizontal Scrolling}.
3038 If @var{position} is visible, @code{pos-visible-in-window-p} returns
3039 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
3040 non-@code{nil}, and the character following @var{position} is fully
3041 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
3042 @var{x} and @var{y} are the pixel coordinates relative to the top left
3043 corner of the window; otherwise it returns an extended list of the form
3044 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
3045 where @var{rtop} and @var{rbot} specify the number of off-window pixels
3046 at the top and bottom of the row at @var{position}, @var{rowh} specifies
3047 the visible height of that row, and @var{vpos} specifies the vertical
3048 position (zero-based row number) of that row.
3054 ;; @r{If point is off the screen now, recenter it now.}
3055 (or (pos-visible-in-window-p
3056 (point) (selected-window))
3062 @defun window-line-height &optional line window
3063 This function returns the height of text line @var{line} in
3064 @var{window}. If @var{line} is one of @code{header-line} or
3065 @code{mode-line}, @code{window-line-height} returns information about
3066 the corresponding line of the window. Otherwise, @var{line} is a text
3067 line number starting from 0. A negative number counts from the end of
3068 the window. The default for @var{line} is the current line in
3069 @var{window}; the default for @var{window} is the selected window.
3071 If the display is not up to date, @code{window-line-height} returns
3072 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
3073 to obtain related information.
3075 If there is no line corresponding to the specified @var{line},
3076 @code{window-line-height} returns @code{nil}. Otherwise, it returns
3077 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
3078 where @var{height} is the height in pixels of the visible part of the
3079 line, @var{vpos} and @var{ypos} are the vertical position in lines and
3080 pixels of the line relative to the top of the first text line, and
3081 @var{offbot} is the number of off-window pixels at the bottom of the
3082 text line. If there are off-window pixels at the top of the (first)
3083 text line, @var{ypos} is negative.
3086 @node Textual Scrolling
3087 @section Textual Scrolling
3088 @cindex textual scrolling
3089 @cindex scrolling textually
3091 @dfn{Textual scrolling} means moving the text up or down through a
3092 window. It works by changing the window's display-start location. It
3093 may also change the value of @code{window-point} to keep point on the
3094 screen (@pxref{Window Point}).
3096 The basic textual scrolling functions are @code{scroll-up} (which
3097 scrolls forward) and @code{scroll-down} (which scrolls backward). In
3098 these function names, ``up'' and ``down'' refer to the direction of
3099 motion of the buffer text relative to the window. Imagine that the
3100 text is written on a long roll of paper and that the scrolling
3101 commands move the paper up and down. Thus, if you are looking at the
3102 middle of a buffer and repeatedly call @code{scroll-down}, you will
3103 eventually see the beginning of the buffer.
3105 Some people have urged that the opposite convention be used: they
3106 imagine the window moving over text that remains in place, so that
3107 ``down'' commands take you to the end of the buffer. This convention
3108 is consistent with fact that such a command is bound to a key named
3109 @key{PageDown} on modern keyboards. We have not switched to this
3110 convention as that is likely to break existing Emacs Lisp code.
3112 Textual scrolling functions (aside from @code{scroll-other-window})
3113 have unpredictable results if the current buffer is not the one
3114 displayed in the selected window. @xref{Current Buffer}.
3116 If the window contains a row taller than the height of the window
3117 (for example in the presence of a large image), the scroll functions
3118 will adjust the window's vertical scroll position to scroll the
3119 partially visible row. Lisp callers can disable this feature by
3120 binding the variable @code{auto-window-vscroll} to @code{nil}
3121 (@pxref{Vertical Scrolling}).
3123 @deffn Command scroll-up &optional count
3124 This function scrolls forward by @var{count} lines in the selected
3127 If @var{count} is negative, it scrolls backward instead. If
3128 @var{count} is @code{nil} (or omitted), the distance scrolled is
3129 @code{next-screen-context-lines} lines less than the height of the
3132 If the selected window cannot be scrolled any further, this function
3133 signals an error. Otherwise, it returns @code{nil}.
3136 @deffn Command scroll-down &optional count
3137 This function scrolls backward by @var{count} lines in the selected
3140 If @var{count} is negative, it scrolls forward instead. If
3141 @var{count} is omitted or @code{nil}, the distance scrolled is
3142 @code{next-screen-context-lines} lines less than the height of the
3145 If the selected window cannot be scrolled any further, this function
3146 signals an error. Otherwise, it returns @code{nil}.
3149 @deffn Command scroll-up-command &optional count
3150 This behaves like @code{scroll-up}, except that if the selected window
3151 cannot be scrolled any further and the value of the variable
3152 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3153 end of the buffer instead. If point is already there, it signals an
3157 @deffn Command scroll-down-command &optional count
3158 This behaves like @code{scroll-down}, except that if the selected
3159 window cannot be scrolled any further and the value of the variable
3160 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3161 beginning of the buffer instead. If point is already there, it
3165 @deffn Command scroll-other-window &optional count
3166 This function scrolls the text in another window upward @var{count}
3167 lines. Negative values of @var{count}, or @code{nil}, are handled
3168 as in @code{scroll-up}.
3170 You can specify which buffer to scroll by setting the variable
3171 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
3172 already displayed, @code{scroll-other-window} displays it in some
3175 When the selected window is the minibuffer, the next window is normally
3176 the one at the top left corner. You can specify a different window to
3177 scroll, when the minibuffer is selected, by setting the variable
3178 @code{minibuffer-scroll-window}. This variable has no effect when any
3179 other window is selected. When it is non-@code{nil} and the
3180 minibuffer is selected, it takes precedence over
3181 @code{other-window-scroll-buffer}. @xref{Definition of
3182 minibuffer-scroll-window}.
3184 When the minibuffer is active, it is the next window if the selected
3185 window is the one at the bottom right corner. In this case,
3186 @code{scroll-other-window} attempts to scroll the minibuffer. If the
3187 minibuffer contains just one line, it has nowhere to scroll to, so the
3188 line reappears after the echo area momentarily displays the message
3189 @samp{Beginning of buffer}.
3192 @defvar other-window-scroll-buffer
3193 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
3194 which buffer's window to scroll.
3197 @defopt scroll-margin
3198 This option specifies the size of the scroll margin---a minimum number
3199 of lines between point and the top or bottom of a window. Whenever
3200 point gets within this many lines of the top or bottom of the window,
3201 redisplay scrolls the text automatically (if possible) to move point
3202 out of the margin, closer to the center of the window.
3205 @defopt scroll-conservatively
3206 This variable controls how scrolling is done automatically when point
3207 moves off the screen (or into the scroll margin). If the value is a
3208 positive integer @var{n}, then redisplay scrolls the text up to
3209 @var{n} lines in either direction, if that will bring point back into
3210 proper view. This behavior is called @dfn{conservative scrolling}.
3211 Otherwise, scrolling happens in the usual way, under the control of
3212 other variables such as @code{scroll-up-aggressively} and
3213 @code{scroll-down-aggressively}.
3215 The default value is zero, which means that conservative scrolling
3219 @defopt scroll-down-aggressively
3220 The value of this variable should be either @code{nil} or a fraction
3221 @var{f} between 0 and 1. If it is a fraction, that specifies where on
3222 the screen to put point when scrolling down. More precisely, when a
3223 window scrolls down because point is above the window start, the new
3224 start position is chosen to put point @var{f} part of the window
3225 height from the top. The larger @var{f}, the more aggressive the
3228 A value of @code{nil} is equivalent to .5, since its effect is to center
3229 point. This variable automatically becomes buffer-local when set in any
3233 @defopt scroll-up-aggressively
3234 Likewise, for scrolling up. The value, @var{f}, specifies how far
3235 point should be placed from the bottom of the window; thus, as with
3236 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
3240 This variable is an older variant of @code{scroll-conservatively}.
3241 The difference is that if its value is @var{n}, that permits scrolling
3242 only by precisely @var{n} lines, not a smaller number. This feature
3243 does not work with @code{scroll-margin}. The default value is zero.
3246 @cindex @code{scroll-command} property
3247 @defopt scroll-preserve-screen-position
3248 If this option is @code{t}, whenever a scrolling command moves point
3249 off-window, Emacs tries to adjust point to keep the cursor at its old
3250 vertical position in the window, rather than the window edge.
3252 If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
3253 to keep the cursor at the same vertical position, even if the
3254 scrolling command didn't move point off-window.
3256 This option affects all scroll commands that have a non-@code{nil}
3257 @code{scroll-command} symbol property.
3260 @defopt next-screen-context-lines
3261 The value of this variable is the number of lines of continuity to
3262 retain when scrolling by full screens. For example, @code{scroll-up}
3263 with an argument of @code{nil} scrolls so that this many lines at the
3264 bottom of the window appear instead at the top. The default value is
3268 @defopt scroll-error-top-bottom
3269 If this option is @code{nil} (the default), @code{scroll-up-command}
3270 and @code{scroll-down-command} simply signal an error when no more
3271 scrolling is possible.
3273 If the value is @code{t}, these commands instead move point to the
3274 beginning or end of the buffer (depending on scrolling direction);
3275 only if point is already on that position do they signal an error.
3278 @deffn Command recenter &optional count
3279 @cindex centering point
3280 This function scrolls the text in the selected window so that point is
3281 displayed at a specified vertical position within the window. It does
3282 not ``move point'' with respect to the text.
3284 If @var{count} is a nonnegative number, that puts the line containing
3285 point @var{count} lines down from the top of the window. If
3286 @var{count} is a negative number, then it counts upward from the
3287 bottom of the window, so that @minus{}1 stands for the last usable
3288 line in the window. If @var{count} is a non-@code{nil} list, then it
3289 stands for the line in the middle of the window.
3291 If @var{count} is @code{nil}, @code{recenter} puts the line containing
3292 point in the middle of the window, then clears and redisplays the entire
3295 When @code{recenter} is called interactively, @var{count} is the raw
3296 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
3297 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
3298 @var{count} to 4, which positions the current line four lines from the
3301 With an argument of zero, @code{recenter} positions the current line at
3302 the top of the window. This action is so handy that some people make a
3303 separate key binding to do this. For example,
3307 (defun line-to-top-of-window ()
3308 "Scroll current line to top of window.
3309 Replaces three keystroke sequence C-u 0 C-l."
3313 (global-set-key [kp-multiply] 'line-to-top-of-window)
3318 @node Vertical Scrolling
3319 @section Vertical Fractional Scrolling
3320 @cindex vertical fractional scrolling
3321 @cindex vertical scroll position
3323 @dfn{Vertical fractional scrolling} means shifting text in a window
3324 up or down by a specified multiple or fraction of a line. Each window
3325 has a @dfn{vertical scroll position}, which is a number, never less than
3326 zero. It specifies how far to raise the contents of the window.
3327 Raising the window contents generally makes all or part of some lines
3328 disappear off the top, and all or part of some other lines appear at the
3329 bottom. The usual value is zero.
3331 The vertical scroll position is measured in units of the normal line
3332 height, which is the height of the default font. Thus, if the value is
3333 .5, that means the window contents are scrolled up half the normal line
3334 height. If it is 3.3, that means the window contents are scrolled up
3335 somewhat over three times the normal line height.
3337 What fraction of a line the vertical scrolling covers, or how many
3338 lines, depends on what the lines contain. A value of .5 could scroll a
3339 line whose height is very short off the screen, while a value of 3.3
3340 could scroll just part of the way through a tall line or an image.
3342 @defun window-vscroll &optional window pixels-p
3343 This function returns the current vertical scroll position of
3344 @var{window}. The default for @var{window} is the selected window.
3345 If @var{pixels-p} is non-@code{nil}, the return value is measured in
3346 pixels, rather than in units of the normal line height.
3356 @defun set-window-vscroll window lines &optional pixels-p
3357 This function sets @var{window}'s vertical scroll position to
3358 @var{lines}. If @var{window} is @code{nil}, the selected window is
3359 used. The argument @var{lines} should be zero or positive; if not, it
3363 The actual vertical scroll position must always correspond
3364 to an integral number of pixels, so the value you specify
3365 is rounded accordingly.
3367 The return value is the result of this rounding.
3371 (set-window-vscroll (selected-window) 1.2)
3376 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
3377 pixels. In this case, the return value is @var{lines}.
3380 @defvar auto-window-vscroll
3381 If this variable is non-@code{nil}, the line-move, scroll-up, and
3382 scroll-down functions will automatically modify the vertical scroll
3383 position to scroll through display rows that are taller than the height
3384 of the window, for example in the presence of large images.
3387 @node Horizontal Scrolling
3388 @section Horizontal Scrolling
3389 @cindex horizontal scrolling
3391 @dfn{Horizontal scrolling} means shifting the image in the window left
3392 or right by a specified multiple of the normal character width. Each
3393 window has a @dfn{horizontal scroll position}, which is a number, never
3394 less than zero. It specifies how far to shift the contents left.
3395 Shifting the window contents left generally makes all or part of some
3396 characters disappear off the left, and all or part of some other
3397 characters appear at the right. The usual value is zero.
3399 The horizontal scroll position is measured in units of the normal
3400 character width, which is the width of space in the default font. Thus,
3401 if the value is 5, that means the window contents are scrolled left by 5
3402 times the normal character width. How many characters actually
3403 disappear off to the left depends on their width, and could vary from
3406 Because we read from side to side in the ``inner loop,'' and from top
3407 to bottom in the ``outer loop,'' the effect of horizontal scrolling is
3408 not like that of textual or vertical scrolling. Textual scrolling
3409 involves selection of a portion of text to display, and vertical
3410 scrolling moves the window contents contiguously; but horizontal
3411 scrolling causes part of @emph{each line} to go off screen.
3413 Usually, no horizontal scrolling is in effect; then the leftmost
3414 column is at the left edge of the window. In this state, scrolling to
3415 the right is meaningless, since there is no data to the left of the edge
3416 to be revealed by it; so this is not allowed. Scrolling to the left is
3417 allowed; it scrolls the first columns of text off the edge of the window
3418 and can reveal additional columns on the right that were truncated
3419 before. Once a window has a nonzero amount of leftward horizontal
3420 scrolling, you can scroll it back to the right, but only so far as to
3421 reduce the net horizontal scroll to zero. There is no limit to how far
3422 left you can scroll, but eventually all the text will disappear off the
3425 @vindex auto-hscroll-mode
3426 If @code{auto-hscroll-mode} is set, redisplay automatically alters
3427 the horizontal scrolling of a window as necessary to ensure that point
3428 is always visible. However, you can still set the horizontal
3429 scrolling value explicitly. The value you specify serves as a lower
3430 bound for automatic scrolling, i.e. automatic scrolling will not
3431 scroll a window to a column less than the specified one.
3433 @deffn Command scroll-left &optional count set-minimum
3434 This function scrolls the selected window @var{count} columns to the
3435 left (or to the right if @var{count} is negative). The default
3436 for @var{count} is the window width, minus 2.
3438 The return value is the total amount of leftward horizontal scrolling in
3439 effect after the change---just like the value returned by
3440 @code{window-hscroll} (below).
3442 Once you scroll a window as far right as it can go, back to its normal
3443 position where the total leftward scrolling is zero, attempts to scroll
3444 any farther right have no effect.
3446 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
3447 the lower bound for automatic scrolling; that is, automatic scrolling
3448 will not scroll a window to a column less than the value returned by
3449 this function. Interactive calls pass non-@code{nil} for
3453 @deffn Command scroll-right &optional count set-minimum
3454 This function scrolls the selected window @var{count} columns to the
3455 right (or to the left if @var{count} is negative). The default
3456 for @var{count} is the window width, minus 2. Aside from the direction
3457 of scrolling, this works just like @code{scroll-left}.
3460 @defun window-hscroll &optional window
3461 This function returns the total leftward horizontal scrolling of
3462 @var{window}---the number of columns by which the text in @var{window}
3463 is scrolled left past the left margin. The default for
3464 @var{window} is the selected window.
3466 The return value is never negative. It is zero when no horizontal
3467 scrolling has been done in @var{window} (which is usually the case).
3486 @defun set-window-hscroll window columns
3487 This function sets horizontal scrolling of @var{window}. The value of
3488 @var{columns} specifies the amount of scrolling, in terms of columns
3489 from the left margin. The argument @var{columns} should be zero or
3490 positive; if not, it is taken as zero. Fractional values of
3491 @var{columns} are not supported at present.
3493 Note that @code{set-window-hscroll} may appear not to work if you test
3494 it by evaluating a call with @kbd{M-:} in a simple way. What happens
3495 is that the function sets the horizontal scroll value and returns, but
3496 then redisplay adjusts the horizontal scrolling to make point visible,
3497 and this overrides what the function did. You can observe the
3498 function's effect if you call it while point is sufficiently far from
3499 the left margin that it will remain visible.
3501 The value returned is @var{columns}.
3505 (set-window-hscroll (selected-window) 10)
3511 Here is how you can determine whether a given position @var{position}
3512 is off the screen due to horizontal scrolling:
3516 (defun hscroll-on-screen (window position)
3518 (goto-char position)
3520 (>= (- (current-column) (window-hscroll window)) 0)
3521 (< (- (current-column) (window-hscroll window))
3522 (window-width window)))))
3527 @node Coordinates and Windows
3528 @section Coordinates and Windows
3530 This section describes how to relate screen coordinates to windows.
3532 @defun window-at x y &optional frame
3533 This function returns the window containing the specified cursor
3534 position in the frame @var{frame}. The coordinates @var{x} and @var{y}
3535 are measured in characters and count from the top left corner of the
3536 frame. If they are out of range, @code{window-at} returns @code{nil}.
3538 If you omit @var{frame}, the selected frame is used.
3541 @defun coordinates-in-window-p coordinates window
3542 This function checks whether a particular frame position falls within
3543 the window @var{window}.
3545 The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
3546 . @var{y})}. The coordinates @var{x} and @var{y} are measured in
3547 characters, and count from the top left corner of the screen or frame.
3549 The value returned by @code{coordinates-in-window-p} is non-@code{nil}
3550 if the coordinates are inside @var{window}. The value also indicates
3551 what part of the window the position is in, as follows:
3554 @item (@var{relx} . @var{rely})
3555 The coordinates are inside @var{window}. The numbers @var{relx} and
3556 @var{rely} are the equivalent window-relative coordinates for the
3557 specified position, counting from 0 at the top left corner of the
3561 The coordinates are in the mode line of @var{window}.
3564 The coordinates are in the header line of @var{window}.
3567 The coordinates are in the vertical line between @var{window} and its
3568 neighbor to the right. This value occurs only if the window doesn't
3569 have a scroll bar; positions in a scroll bar are considered outside the
3570 window for these purposes.
3574 The coordinates are in the left or right fringe of the window.
3578 The coordinates are in the left or right margin of the window.
3581 The coordinates are not in any part of @var{window}.
3584 The function @code{coordinates-in-window-p} does not require a frame as
3585 argument because it always uses the frame that @var{window} is on.
3589 @node Window Configurations
3590 @section Window Configurations
3591 @cindex window configurations
3592 @cindex saving window information
3594 A @dfn{window configuration} records the entire layout of one
3595 frame---all windows, their sizes, which buffers they contain, how those
3596 buffers are scrolled, and their values of point and the mark; also their
3597 fringes, margins, and scroll bar settings. It also includes the value
3598 of @code{minibuffer-scroll-window}. As a special exception, the window
3599 configuration does not record the value of point in the selected window
3600 for the current buffer.
3602 You can bring back an entire frame layout by restoring a previously
3603 saved window configuration. If you want to record the layout of all
3604 frames instead of just one, use a frame configuration instead of a
3605 window configuration; see @ref{Frame Configurations}.
3607 @defun current-window-configuration &optional frame
3608 This function returns a new object representing @var{frame}'s current
3609 window configuration. The default for @var{frame} is the selected
3613 @defun set-window-configuration configuration
3614 This function restores the configuration of windows and buffers as
3615 specified by @var{configuration}, for the frame that @var{configuration}
3618 The argument @var{configuration} must be a value that was previously
3619 returned by @code{current-window-configuration}. The configuration is
3620 restored in the frame from which @var{configuration} was made, whether
3621 that frame is selected or not. This always counts as a window size
3622 change and triggers execution of the @code{window-size-change-functions}
3623 (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
3624 know how to tell whether the new configuration actually differs from the
3627 If the frame which @var{configuration} was saved from is dead, all this
3628 function does is restore the three variables @code{window-min-height},
3629 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
3630 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
3632 Here is a way of using this function to get the same effect
3633 as @code{save-window-excursion}:
3637 (let ((config (current-window-configuration)))
3639 (progn (split-window-below nil)
3641 (set-window-configuration config)))
3646 @defspec save-window-excursion forms@dots{}
3647 This special form records the window configuration, executes @var{forms}
3648 in sequence, then restores the earlier window configuration. The window
3649 configuration includes, for each window, the value of point and the
3650 portion of the buffer that is visible. It also includes the choice of
3651 selected window. However, it does not include the value of point in
3652 the current buffer; use @code{save-excursion} also, if you wish to
3655 Don't use this construct when @code{save-selected-window} is sufficient.
3657 Exit from @code{save-window-excursion} always triggers execution of
3658 @code{window-size-change-functions}. (It doesn't know how to tell
3659 whether the restored configuration actually differs from the one in
3660 effect at the end of the @var{forms}.)
3662 The return value is the value of the final form in @var{forms}.
3668 @result{} #<window 25 on control.texi>
3671 (setq w (selected-window))
3672 @result{} #<window 19 on control.texi>
3675 (save-window-excursion
3676 (delete-other-windows w)
3677 (switch-to-buffer "foo")
3679 @result{} do-something
3680 ;; @r{The screen is now split again.}
3685 @defun window-configuration-p object
3686 This function returns @code{t} if @var{object} is a window configuration.
3689 @defun compare-window-configurations config1 config2
3690 This function compares two window configurations as regards the
3691 structure of windows, but ignores the values of point and mark and the
3692 saved scrolling positions---it can return @code{t} even if those
3695 The function @code{equal} can also compare two window configurations; it
3696 regards configurations as unequal if they differ in any respect, even a
3697 saved point or mark.
3700 @defun window-configuration-frame config
3701 This function returns the frame for which the window configuration
3702 @var{config} was made.
3705 Other primitives to look inside of window configurations would make
3706 sense, but are not implemented because we did not need them. See the
3707 file @file{winner.el} for some more operations on windows
3710 The objects returned by @code{current-window-configuration} die
3711 together with the Emacs process. In order to store a window
3712 configuration on disk and read it back in another Emacs session the
3713 following two functions can be used.
3715 @defun window-state-get &optional window markers
3716 This function returns the state of @var{window} as a Lisp object. The
3717 argument @var{window} can be any window and defaults to the root window
3718 of the selected frame.
3720 The optional argument @var{markers} non-@code{nil} means to use markers
3721 for sampling positions like @code{window-point} or @code{window-start}.
3722 This argument should be non-@code{nil} only if the value is used for
3723 putting the state back in the same session since markers slow down
3727 The value returned by @code{window-state-get} can be converted by using
3728 one of the functions defined by Desktop Save Mode (@pxref{Desktop Save
3729 Mode}) to an object that can be written to a file. Such objects can be
3730 read back and converted to a Lisp object representing the state of the
3731 window. That Lisp object can be used as argument for the following
3732 function in order to restore the state window in another window.
3734 @defun window-state-put state &optional window ignore
3735 This function puts the window state @var{state} into @var{window}. The
3736 argument @var{state} should be the state of a window returned by an
3737 earlier invocation of @code{window-state-get}, see above. The optional
3738 argument @var{window} must specify a live window and defaults to the
3741 The optional argument @var{ignore} non-@code{nil} means to ignore
3742 minimum window sizes and fixed size restrictions. If @var{ignore}
3743 equals @code{safe}, this means subwindows can get as small as one line
3748 @node Window Parameters
3749 @section Window Parameters
3750 @cindex window parameters
3752 This section describes how window parameters can be used to associate
3753 additional information with windows.
3755 @defun window-parameter window parameter
3756 This function returns @var{window}'s value for @var{parameter}. The
3757 default for @var{window} is the selected window. If @var{window} has no
3758 setting for @var{parameter}, this function returns @code{nil}.
3761 @defun window-parameters &optional window
3762 This function returns all parameters of @var{window} and their values.
3763 The default for @var{window} is the selected window. The return value,
3764 if non-@code{nil} is an association list whose elements have the form
3765 @code{(@var{parameter} . @var{value})}.
3768 @defun set-window-parameter window parameter value
3769 This function sets @var{window}'s value of @var{parameter} to
3770 @var{value} and returns @var{value}. The default for @var{window}
3771 is the selected window.
3774 Some functions, notably @code{delete-window},
3775 @code{delete-other-windows} and @code{split-window} may behave specially
3776 when their @var{window} argument has a parameter set. You can override
3777 such special behavior by binding the following variable to a
3778 non-@code{nil} value:
3780 @defvar ignore-window-parameters
3781 If this variable is non-@code{nil}, some standard functions do not
3782 process window parameters. The functions currently affected by this are
3783 @code{split-window}, @code{delete-window}, @code{delete-other-windows}
3784 and @code{other-window}.
3786 An application can bind this variable to a non-@code{nil} value around
3787 calls to these functions. If it does so, the application is fully
3788 responsible for correctly assigning the parameters of all involved
3789 windows when exiting that function.
3792 The following parameters are currently used by the window management
3796 @item @code{delete-window}
3797 This parameter affects the execution of @code{delete-window}
3798 (@pxref{Deleting Windows}).
3800 @item @code{delete-other-windows}
3801 This parameter affects the execution of @code{delete-other-windows}
3802 (@pxref{Deleting Windows}).
3804 @item @code{split-window}
3805 This parameter affects the execution of @code{split-window}
3806 (@pxref{Splitting Windows}).
3808 @item @code{other-window}
3809 This parameter affects the execution of @code{other-window}
3810 (@pxref{Cyclic Window Ordering}).
3812 @item @code{no-other-window}
3813 This parameter marks the window as not selectable by @code{other-window}
3814 (@pxref{Cyclic Window Ordering}).
3817 In addition, the parameters @code{window-atom} and @code{window-side}
3818 are reserved and should not be used by applications. The
3819 @code{quit-restore} parameter tells how to proceed with a window when
3820 the buffer it shows is no more needed. This parameter is installed by
3821 the buffer display functions (@pxref{Choosing Window}) and consulted by
3822 the function @code{quit-window} (@pxref{Quitting Windows}).
3826 @section Hooks for Window Scrolling and Changes
3827 @cindex hooks for window operations
3829 This section describes how a Lisp program can take action whenever a
3830 window displays a different part of its buffer or a different buffer.
3831 There are three actions that can change this: scrolling the window,
3832 switching buffers in the window, and changing the size of the window.
3833 The first two actions run @code{window-scroll-functions}; the last runs
3834 @code{window-size-change-functions}.
3836 @defvar window-scroll-functions
3837 This variable holds a list of functions that Emacs should call before
3838 redisplaying a window with scrolling. Displaying a different buffer in
3839 the window also runs these functions.
3841 This variable is not a normal hook, because each function is called with
3842 two arguments: the window, and its new display-start position.
3844 These functions must be careful in using @code{window-end}
3845 (@pxref{Window Start and End}); if you need an up-to-date value, you
3846 must use the @var{update} argument to ensure you get it.
3848 @strong{Warning:} don't use this feature to alter the way the window
3849 is scrolled. It's not designed for that, and such use probably won't
3853 @defvar window-size-change-functions
3854 This variable holds a list of functions to be called if the size of any
3855 window changes for any reason. The functions are called just once per
3856 redisplay, and just once for each frame on which size changes have
3859 Each function receives the frame as its sole argument. There is no
3860 direct way to find out which windows on that frame have changed size, or
3861 precisely how. However, if a size-change function records, at each
3862 call, the existing windows and their sizes, it can also compare the
3863 present sizes and the previous sizes.
3865 Creating or deleting windows counts as a size change, and therefore
3866 causes these functions to be called. Changing the frame size also
3867 counts, because it changes the sizes of the existing windows.
3869 It is not a good idea to use @code{save-window-excursion} (@pxref{Window
3870 Configurations}) in these functions, because that always counts as a
3871 size change, and it would cause these functions to be called over and
3872 over. In most cases, @code{save-selected-window} (@pxref{Selecting
3873 Windows}) is what you need here.
3876 @defvar window-configuration-change-hook
3877 A normal hook that is run every time you change the window configuration
3878 of an existing frame. This includes splitting or deleting windows,
3879 changing the sizes of windows, or displaying a different buffer in a
3882 The buffer-local part of this hook is run once per each window on the
3883 affected frame, with the relevant window selected and its buffer
3884 current. The global part is run once for the modified frame, with that
3888 In addition, you can use @code{jit-lock-register} to register a Font
3889 Lock fontification function, which will be called whenever parts of a
3890 buffer are (re)fontified because a window was scrolled or its size
3891 changed. @xref{Other Font Lock Variables}.