]> code.delx.au - gnu-emacs/blob - doc/lispref/windows.texi
Merge from origin/emacs-25
[gnu-emacs] / doc / lispref / windows.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2016 Free Software
4 @c Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @node Windows
7 @chapter Windows
8
9 This chapter describes the functions and variables related to Emacs
10 windows. @xref{Frames}, for how windows are assigned an area of screen
11 available for Emacs to use. @xref{Display}, for information on how text
12 is displayed in windows.
13
14 @menu
15 * Basic Windows:: Basic information on using windows.
16 * Windows and Frames:: Relating windows to the frame they appear on.
17 * Window Sizes:: Accessing a window's size.
18 * Resizing Windows:: Changing the sizes of windows.
19 * Preserving Window Sizes:: Preserving the size of windows.
20 * Splitting Windows:: Creating a new window.
21 * Deleting Windows:: Removing a window from its frame.
22 * Recombining Windows:: Preserving the frame layout when splitting and
23 deleting windows.
24 * Selecting Windows:: The selected window is the one that you edit in.
25 * Cyclic Window Ordering:: Moving around the existing windows.
26 * Buffers and Windows:: Each window displays the contents of a buffer.
27 * Switching Buffers:: Higher-level functions for switching to a buffer.
28 * Choosing Window:: How to choose a window for displaying a buffer.
29 * Display Action Functions:: Subroutines for @code{display-buffer}.
30 * Choosing Window Options:: Extra options affecting how buffers are displayed.
31 * Window History:: Each window remembers the buffers displayed in it.
32 * Dedicated Windows:: How to avoid displaying another buffer in
33 a specific window.
34 * Quitting Windows:: How to restore the state prior to displaying a
35 buffer.
36 * Window Point:: Each window has its own location of point.
37 * Window Start and End:: Buffer positions indicating which text is
38 on-screen in a window.
39 * Textual Scrolling:: Moving text up and down through the window.
40 * Vertical Scrolling:: Moving the contents up and down on the window.
41 * Horizontal Scrolling:: Moving the contents sideways on the window.
42 * Coordinates and Windows:: Converting coordinates to windows.
43 * Window Configurations:: Saving and restoring the state of the screen.
44 * Window Parameters:: Associating additional information with windows.
45 * Window Hooks:: Hooks for scrolling, window size changes,
46 redisplay going past a certain point,
47 or window configuration changes.
48 @end menu
49
50
51 @node Basic Windows
52 @section Basic Concepts of Emacs Windows
53 @cindex window
54
55 A @dfn{window} is an area of the screen that is used to display a buffer
56 (@pxref{Buffers}). In Emacs Lisp, windows are represented by a special
57 Lisp object type.
58
59 @cindex multiple windows
60 Windows are grouped into frames (@pxref{Frames}). Each frame
61 contains at least one window; the user can subdivide it into multiple,
62 non-overlapping windows to view several buffers at once. Lisp
63 programs can use multiple windows for a variety of purposes. In
64 Rmail, for example, you can view a summary of message titles in one
65 window, and the contents of the selected message in another window.
66
67 @cindex terminal screen
68 @cindex screen of terminal
69 Emacs uses the word ``window'' with a different meaning than in
70 graphical desktop environments and window systems, such as the X
71 Window System. When Emacs is run on X, each of its graphical X
72 windows is an Emacs frame (containing one or more Emacs windows).
73 When Emacs is run on a text terminal, the frame fills the entire
74 terminal screen.
75
76 @cindex tiled windows
77 Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
78 within the area of the frame. When a window is created, resized, or
79 deleted, the change in window space is taken from or given to the
80 adjacent windows, so that the total area of the frame is unchanged.
81
82 @defun windowp object
83 This function returns @code{t} if @var{object} is a window (whether or
84 not it displays a buffer). Otherwise, it returns @code{nil}.
85 @end defun
86
87 @cindex live windows
88 A @dfn{live window} is one that is actually displaying a buffer in a
89 frame.
90
91 @defun window-live-p object
92 This function returns @code{t} if @var{object} is a live window and
93 @code{nil} otherwise. A live window is one that displays a buffer.
94 @end defun
95
96 @cindex internal windows
97 The windows in each frame are organized into a @dfn{window tree}.
98 @xref{Windows and Frames}. The leaf nodes of each window tree are live
99 windows---the ones actually displaying buffers. The internal nodes of
100 the window tree are @dfn{internal windows}, which are not live.
101
102 @cindex valid windows
103 A @dfn{valid window} is one that is either live or internal. A valid
104 window can be @dfn{deleted}, i.e., removed from its frame
105 (@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
106 object representing it might be still referenced from other Lisp
107 objects. A deleted window may be made valid again by restoring a saved
108 window configuration (@pxref{Window Configurations}).
109
110 You can distinguish valid windows from deleted windows with
111 @code{window-valid-p}.
112
113 @defun window-valid-p object
114 This function returns @code{t} if @var{object} is a live window, or an
115 internal window in a window tree. Otherwise, it returns @code{nil},
116 including for the case where @var{object} is a deleted window.
117 @end defun
118
119 @cindex selected window
120 @cindex window selected within a frame
121 In each frame, at any time, exactly one Emacs window is designated
122 as @dfn{selected within the frame}. For the selected frame, that
123 window is called the @dfn{selected window}---the one in which most
124 editing takes place, and in which the cursor for selected windows
125 appears (@pxref{Cursor Parameters}). The selected window's buffer is
126 usually also the current buffer, except when @code{set-buffer} has
127 been used (@pxref{Current Buffer}). As for non-selected frames, the
128 window selected within the frame becomes the selected window if the
129 frame is ever selected. @xref{Selecting Windows}.
130
131 @defun selected-window
132 This function returns the selected window (which is always a live
133 window).
134 @end defun
135
136 @anchor{Window Group}Sometimes several windows collectively and
137 cooperatively display a buffer, for example, under the management of
138 Follow Mode (@pxref{Follow Mode,,, emacs}), where the windows together
139 display a bigger portion of the buffer than one window could alone.
140 It is often useful to consider such a @dfn{window group} as a single
141 entity. Several functions such as @code{window-group-start}
142 (@pxref{Window Start and End}) allow you to do this by supplying, as
143 an argument, one of the windows as a stand in for the whole group.
144
145 @defun selected-window-group
146 @vindex selected-window-group-function
147 When the selected window is a member of a group of windows, this
148 function returns a list of the windows in the group, ordered such that
149 the first window in the list is displaying the earliest part of the
150 buffer, and so on. Otherwise the function returns a list containing
151 just the selected window.
152
153 The selected window is considered part of a group when the buffer
154 local variable @code{selected-window-group-function} is set to a
155 function. In this case, @code{selected-window-group} calls it with no
156 arguments and returns its result (which should be the list of windows
157 in the group).
158 @end defun
159
160 @node Windows and Frames
161 @section Windows and Frames
162
163 Each window belongs to exactly one frame (@pxref{Frames}).
164
165 @defun window-frame &optional window
166 This function returns the frame that the window @var{window} belongs
167 to. If @var{window} is @code{nil}, it defaults to the selected
168 window.
169 @end defun
170
171 @defun window-list &optional frame minibuffer window
172 This function returns a list of live windows belonging to the frame
173 @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
174 the selected frame.
175
176 The optional argument @var{minibuffer} specifies whether to include
177 the minibuffer window in the returned list. If @var{minibuffer} is
178 @code{t}, the minibuffer window is included. If @var{minibuffer} is
179 @code{nil} or omitted, the minibuffer window is included only if it is
180 active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the
181 minibuffer window is never included.
182
183 The optional argument @var{window}, if non-@code{nil}, should be a live
184 window on the specified frame; then @var{window} will be the first
185 element in the returned list. If @var{window} is omitted or @code{nil},
186 the window selected within the frame is the first element.
187 @end defun
188
189 @cindex window tree
190 @cindex root window
191 Windows in the same frame are organized into a @dfn{window tree},
192 whose leaf nodes are the live windows. The internal nodes of a window
193 tree are not live; they exist for the purpose of organizing the
194 relationships between live windows. The root node of a window tree is
195 called the @dfn{root window}. It can be either a live window (if the
196 frame has just one window), or an internal window.
197
198 A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
199 frame's window tree unless the frame is a minibuffer-only frame.
200 Nonetheless, most of the functions in this section accept the
201 minibuffer window as an argument. Also, the function
202 @code{window-tree} described at the end of this section lists the
203 minibuffer window alongside the actual window tree.
204
205 @defun frame-root-window &optional frame-or-window
206 This function returns the root window for @var{frame-or-window}. The
207 argument @var{frame-or-window} should be either a window or a frame;
208 if omitted or @code{nil}, it defaults to the selected frame. If
209 @var{frame-or-window} is a window, the return value is the root window
210 of that window's frame.
211 @end defun
212
213 @cindex parent window
214 @cindex child window
215 @cindex sibling window
216 When a window is split, there are two live windows where previously
217 there was one. One of these is represented by the same Lisp window
218 object as the original window, and the other is represented by a
219 newly-created Lisp window object. Both of these live windows become
220 leaf nodes of the window tree, as @dfn{child windows} of a single
221 internal window. If necessary, Emacs automatically creates this
222 internal window, which is also called the @dfn{parent window}, and
223 assigns it to the appropriate position in the window tree. A set of
224 windows that share the same parent are called @dfn{siblings}.
225
226 @cindex parent window
227 @defun window-parent &optional window
228 This function returns the parent window of @var{window}. If
229 @var{window} is omitted or @code{nil}, it defaults to the selected
230 window. The return value is @code{nil} if @var{window} has no parent
231 (i.e., it is a minibuffer window or the root window of its frame).
232 @end defun
233
234 Each internal window always has at least two child windows. If this
235 number falls to one as a result of window deletion, Emacs
236 automatically deletes the internal window, and its sole remaining
237 child window takes its place in the window tree.
238
239 Each child window can be either a live window, or an internal window
240 (which in turn would have its own child windows). Therefore, each
241 internal window can be thought of as occupying a certain rectangular
242 @dfn{screen area}---the union of the areas occupied by the live
243 windows that are ultimately descended from it.
244
245 @cindex window combination
246 @cindex vertical combination
247 @cindex horizontal combination
248 For each internal window, the screen areas of the immediate children
249 are arranged either vertically or horizontally (never both). If the
250 child windows are arranged one above the other, they are said to form
251 a @dfn{vertical combination}; if they are arranged side by side, they
252 are said to form a @dfn{horizontal combination}. Consider the
253 following example:
254
255 @smallexample
256 @group
257 ______________________________________
258 | ______ ____________________________ |
259 || || __________________________ ||
260 || ||| |||
261 || ||| |||
262 || ||| |||
263 || |||____________W4____________|||
264 || || __________________________ ||
265 || ||| |||
266 || ||| |||
267 || |||____________W5____________|||
268 ||__W2__||_____________W3_____________ |
269 |__________________W1__________________|
270
271 @end group
272 @end smallexample
273
274 @noindent
275 The root window of this frame is an internal window, @var{W1}. Its
276 child windows form a horizontal combination, consisting of the live
277 window @var{W2} and the internal window @var{W3}. The child windows
278 of @var{W3} form a vertical combination, consisting of the live
279 windows @var{W4} and @var{W5}. Hence, the live windows in this
280 window tree are @var{W2}, @var{W4}, and @var{W5}.
281
282 The following functions can be used to retrieve a child window of an
283 internal window, and the siblings of a child window.
284
285 @defun window-top-child &optional window
286 This function returns the topmost child window of @var{window}, if
287 @var{window} is an internal window whose children form a vertical
288 combination. For any other type of window, the return value is
289 @code{nil}.
290 @end defun
291
292 @defun window-left-child &optional window
293 This function returns the leftmost child window of @var{window}, if
294 @var{window} is an internal window whose children form a horizontal
295 combination. For any other type of window, the return value is
296 @code{nil}.
297 @end defun
298
299 @defun window-child window
300 This function returns the first child window of the internal window
301 @var{window}---the topmost child window for a vertical combination, or
302 the leftmost child window for a horizontal combination. If
303 @var{window} is a live window, the return value is @code{nil}.
304 @end defun
305
306 @defun window-combined-p &optional window horizontal
307 This function returns a non-@code{nil} value if and only if
308 @var{window} is part of a vertical combination. If @var{window} is
309 omitted or @code{nil}, it defaults to the selected one.
310
311 If the optional argument @var{horizontal} is non-@code{nil}, this
312 means to return non-@code{nil} if and only if @var{window} is part of
313 a horizontal combination.
314 @end defun
315
316 @defun window-next-sibling &optional window
317 This function returns the next sibling of the window @var{window}. If
318 omitted or @code{nil}, @var{window} defaults to the selected window.
319 The return value is @code{nil} if @var{window} is the last child of
320 its parent.
321 @end defun
322
323 @defun window-prev-sibling &optional window
324 This function returns the previous sibling of the window @var{window}.
325 If omitted or @code{nil}, @var{window} defaults to the selected
326 window. The return value is @code{nil} if @var{window} is the first
327 child of its parent.
328 @end defun
329
330 The functions @code{window-next-sibling} and
331 @code{window-prev-sibling} should not be confused with the functions
332 @code{next-window} and @code{previous-window}, which return the next
333 and previous window, respectively, in the cyclic ordering of windows
334 (@pxref{Cyclic Window Ordering}).
335
336 You can use the following functions to find the first live window on a
337 frame and the window nearest to a given window.
338
339 @defun frame-first-window &optional frame-or-window
340 This function returns the live window at the upper left corner of the
341 frame specified by @var{frame-or-window}. The argument
342 @var{frame-or-window} must denote a window or a live frame and defaults
343 to the selected frame. If @var{frame-or-window} specifies a window,
344 this function returns the first window on that window's frame. Under
345 the assumption that the frame from our canonical example is selected
346 @code{(frame-first-window)} returns @var{W2}.
347 @end defun
348
349 @cindex window in direction
350 @defun window-in-direction direction &optional window ignore sign wrap mini
351 This function returns the nearest live window in direction
352 @var{direction} as seen from the position of @code{window-point} in
353 window @var{window}. The argument @var{direction} must be one of
354 @code{above}, @code{below}, @code{left} or @code{right}. The optional
355 argument @var{window} must denote a live window and defaults to the
356 selected one.
357
358 This function does not return a window whose @code{no-other-window}
359 parameter is non-@code{nil} (@pxref{Window Parameters}). If the nearest
360 window's @code{no-other-window} parameter is non-@code{nil}, this
361 function tries to find another window in the indicated direction whose
362 @code{no-other-window} parameter is @code{nil}. If the optional
363 argument @var{ignore} is non-@code{nil}, a window may be returned even
364 if its @code{no-other-window} parameter is non-@code{nil}.
365
366 If the optional argument @var{sign} is a negative number, it means to
367 use the right or bottom edge of @var{window} as reference position
368 instead of @code{window-point}. If @var{sign} is a positive number, it
369 means to use the left or top edge of @var{window} as reference position.
370
371 If the optional argument @var{wrap} is non-@code{nil}, this means to
372 wrap @var{direction} around frame borders. For example, if @var{window}
373 is at the top of the frame and @var{direction} is @code{above}, then
374 this function usually returns the frame's minibuffer window if it's
375 active and a window at the bottom of the frame otherwise.
376
377 If the optional argument @var{mini} is @code{nil}, this means to return
378 the minibuffer window if and only if it is currently active. If
379 @var{mini} is non-@code{nil}, this function may return the minibuffer
380 window even when it's not active. However, if @var{wrap} is
381 non-@code{nil}, it always acts as if @var{mini} were @code{nil}.
382
383 If it doesn't find a suitable window, this function returns @code{nil}.
384 @end defun
385
386 The following function allows the entire window tree of a frame to be
387 retrieved:
388
389 @defun window-tree &optional frame
390 This function returns a list representing the window tree for frame
391 @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
392 the selected frame.
393
394 The return value is a list of the form @code{(@var{root} @var{mini})},
395 where @var{root} represents the window tree of the frame's root
396 window, and @var{mini} is the frame's minibuffer window.
397
398 If the root window is live, @var{root} is that window itself.
399 Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
400 @var{w2} ...)} where @var{dir} is @code{nil} for a horizontal
401 combination and @code{t} for a vertical combination, @var{edges} gives
402 the size and position of the combination, and the remaining elements
403 are the child windows. Each child window may again be a window object
404 (for a live window) or a list with the same format as above (for an
405 internal window). The @var{edges} element is a list @code{(@var{left}
406 @var{top} @var{right} @var{bottom})}, similar to the value returned by
407 @code{window-edges} (@pxref{Coordinates and Windows}).
408 @end defun
409
410
411 @node Window Sizes
412 @section Window Sizes
413 @cindex window size
414 @cindex size of window
415
416 The following schematic shows the structure of a live window:
417
418 @smallexample
419 @group
420 ____________________________________________
421 |______________ Header Line ______________|RD| ^
422 ^ |LS|LM|LF| |RF|RM|RS| | |
423 | | | | | | | | | | |
424 Window | | | | Text Area | | | | | Window
425 Body | | | | | (Window Body) | | | | | Total
426 Height | | | | | | | | | Height
427 | | | | |<- Window Body Width ->| | | | | |
428 v |__|__|__|_______________________|__|__|__| | |
429 |_________ Horizontal Scroll Bar _________| | |
430 |_______________ Mode Line _______________|__| |
431 |_____________ Bottom Divider _______________| v
432 <---------- Window Total Width ------------>
433
434 @end group
435 @end smallexample
436
437 @cindex window body
438 @cindex text area of a window
439 @cindex body of a window
440 At the center of the window is the @dfn{text area}, or @dfn{body},
441 where the buffer text is displayed. The text area can be surrounded by
442 a series of optional areas. On the left and right, from innermost to
443 outermost, these are the left and right fringes, denoted by LF and RF
444 (@pxref{Fringes}); the left and right margins, denoted by LM and RM in
445 the schematic (@pxref{Display Margins}); the left or right vertical
446 scroll bar, only one of which is present at any time, denoted by LS and
447 RS (@pxref{Scroll Bars}); and the right divider, denoted by RD
448 (@pxref{Window Dividers}). At the top of the window is the header line
449 (@pxref{Header Lines}). At the bottom of the window are the horizontal
450 scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
451 Format}); and the bottom divider (@pxref{Window Dividers}).
452
453 Emacs provides miscellaneous functions for finding the height and
454 width of a window. The return value of many of these functions can be
455 specified either in units of pixels or in units of lines and columns.
456 On a graphical display, the latter actually correspond to the height and
457 width of a default character specified by the frame's default font
458 as returned by @code{frame-char-height} and @code{frame-char-width}
459 (@pxref{Frame Font}). Thus, if a window is displaying text with a
460 different font or size, the reported line height and column width for
461 that window may differ from the actual number of text lines or columns
462 displayed within it.
463
464 @cindex window height
465 @cindex height of a window
466 @cindex total height of a window
467 The @dfn{total height} of a window is the number of lines comprising
468 the window's body, the header line, the horizontal scroll bar, the mode
469 line and the bottom divider (if any).
470
471 @defun window-total-height &optional window round
472 This function returns the total height, in lines, of the window
473 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
474 the selected window. If @var{window} is an internal window, the return
475 value is the total height occupied by its descendant windows.
476
477 If a window's pixel height is not an integral multiple of its frame's
478 default character height, the number of lines occupied by the window is
479 rounded internally. This is done in a way such that, if the window is a
480 parent window, the sum of the total heights of all its child windows
481 internally equals the total height of their parent. This means that
482 although two windows have the same pixel height, their internal total
483 heights may differ by one line. This means also, that if window is
484 vertically combined and has a next sibling, the topmost row of that
485 sibling can be calculated as the sum of this window's topmost row and
486 total height (@pxref{Coordinates and Windows})
487
488 If the optional argument @var{round} is @code{ceiling}, this
489 function returns the smallest integer larger than @var{window}'s pixel
490 height divided by the character height of its frame; if it is
491 @code{floor}, it returns the largest integer smaller than said value;
492 with any other @var{round} it returns the internal value of
493 @var{windows}'s total height.
494 @end defun
495
496 @cindex window width
497 @cindex width of a window
498 @cindex total width of a window
499 The @dfn{total width} of a window is the number of lines comprising the
500 window's body, its margins, fringes, scroll bars and a right divider (if
501 any).
502
503 @defun window-total-width &optional window round
504 This function returns the total width, in columns, of the window
505 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
506 the selected window. If @var{window} is internal, the return value is
507 the total width occupied by its descendant windows.
508
509 If a window's pixel width is not an integral multiple of its frame's
510 character width, the number of lines occupied by the window is rounded
511 internally. This is done in a way such that, if the window is a parent
512 window, the sum of the total widths of all its children internally
513 equals the total width of their parent. This means that although two
514 windows have the same pixel width, their internal total widths may
515 differ by one column. This means also, that if this window is
516 horizontally combined and has a next sibling, the leftmost column of
517 that sibling can be calculated as the sum of this window's leftmost
518 column and total width (@pxref{Coordinates and Windows}). The optional
519 argument @var{round} behaves as it does for @code{window-total-height}.
520 @end defun
521
522 @defun window-total-size &optional window horizontal round
523 This function returns either the total height in lines or the total
524 width in columns of the window @var{window}. If @var{horizontal} is
525 omitted or @code{nil}, this is equivalent to calling
526 @code{window-total-height} for @var{window}; otherwise it is equivalent
527 to calling @code{window-total-width} for @var{window}. The optional
528 argument @var{round} behaves as it does for @code{window-total-height}.
529 @end defun
530
531 The following two functions can be used to return the total size of a
532 window in units of pixels.
533
534 @cindex window pixel height
535 @cindex pixel height of a window
536 @cindex total pixel height of a window
537
538 @defun window-pixel-height &optional window
539 This function returns the total height of window @var{window} in pixels.
540 @var{window} must be a valid window and defaults to the selected one.
541
542 The return value includes mode and header line, a horizontal scroll bar
543 and a bottom divider, if any. If @var{window} is an internal window,
544 its pixel height is the pixel height of the screen areas spanned by its
545 children.
546 @end defun
547
548 @defun window-pixel-height-before-size-change &optional Lisp_Object &optional window
549 This function returns the height of window @var{window} in pixels at the
550 time @code{window-size-change-functions} was run for the last time on
551 @var{window}'s frame (@pxref{Window Hooks}).
552 @end defun
553
554 @cindex window pixel width
555 @cindex pixel width of a window
556 @cindex total pixel width of a window
557
558 @defun window-pixel-width &optional Lisp_Object &optional window
559 This function returns the width of window @var{window} in pixels.
560 @var{window} must be a valid window and defaults to the selected one.
561
562 The return value includes the fringes and margins of @var{window} as
563 well as any vertical dividers or scroll bars belonging to @var{window}.
564 If @var{window} is an internal window, its pixel width is the width of
565 the screen areas spanned by its children.
566 @end defun
567
568 @defun window-pixel-width-before-size-change &optional Lisp_Object &optional window
569 This function returns the width of window @var{window} in pixels at the
570 time @code{window-size-change-functions} was run for the last time on
571 @var{window}'s frame (@pxref{Window Hooks}).
572 @end defun
573
574 @cindex full-width window
575 @cindex full-height window
576 The following functions can be used to determine whether a given
577 window has any adjacent windows.
578
579 @defun window-full-height-p &optional window
580 This function returns non-@code{nil} if @var{window} has no other window
581 above or below it in its frame. More precisely, this means that the
582 total height of @var{window} equals the total height of the root window
583 on that frame. The minibuffer window does not count in this regard. If
584 @var{window} is omitted or @code{nil}, it defaults to the selected
585 window.
586 @end defun
587
588 @defun window-full-width-p &optional window
589 This function returns non-@code{nil} if @var{window} has no other
590 window to the left or right in its frame, i.e., its total width equals
591 that of the root window on that frame. If @var{window} is omitted or
592 @code{nil}, it defaults to the selected window.
593 @end defun
594
595 @cindex window body height
596 @cindex body height of a window
597 The @dfn{body height} of a window is the height of its text area, which
598 does not include a mode or header line, a horizontal scroll bar, or a
599 bottom divider.
600
601 @defun window-body-height &optional window pixelwise
602 This function returns the height, in lines, of the body of window
603 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
604 the selected window; otherwise it must be a live window.
605
606 If the optional argument @var{pixelwise} is non-@code{nil}, this
607 function returns the body height of @var{window} counted in pixels.
608
609 If @var{pixelwise} is @code{nil}, the return value is rounded down to
610 the nearest integer, if necessary. This means that if a line at the
611 bottom of the text area is only partially visible, that line is not
612 counted. It also means that the height of a window's body can never
613 exceed its total height as returned by @code{window-total-height}.
614 @end defun
615
616 @cindex window body width
617 @cindex body width of a window
618 The @dfn{body width} of a window is the width of its text area, which
619 does not include the scroll bar, fringes, margins or a right divider.
620 Note that when one or both fringes are removed (by setting their width
621 to zero), the display engine reserves two character cells, one on each
622 side of the window, for displaying the continuation and truncation
623 glyphs, which leaves 2 columns less for text display. (The function
624 @code{window-max-chars-per-line}, described below, takes this
625 peculiarity into account.)
626
627 @defun window-body-width &optional window pixelwise
628 This function returns the width, in columns, of the body of window
629 @var{window}. If @var{window} is omitted or @code{nil}, it defaults to
630 the selected window; otherwise it must be a live window.
631
632 If the optional argument @var{pixelwise} is non-@code{nil}, this
633 function returns the body width of @var{window} in units of pixels.
634
635 If @var{pixelwise} is @code{nil}, the return value is rounded down to
636 the nearest integer, if necessary. This means that if a column on the
637 right of the text area is only partially visible, that column is not
638 counted. It also means that the width of a window's body can never
639 exceed its total width as returned by @code{window-total-width}.
640 @end defun
641
642 @cindex window body size
643 @cindex body size of a window
644 @defun window-body-size &optional window horizontal pixelwise
645 This function returns the body height or body width of @var{window}. If
646 @var{horizontal} is omitted or @code{nil}, it is equivalent to calling
647 @code{window-body-height} for @var{window}; otherwise it is equivalent
648 to calling @code{window-body-width}. In either case, the optional
649 argument @var{pixelwise} is passed to the function called.
650 @end defun
651
652 For compatibility with previous versions of Emacs,
653 @code{window-height} is an alias for @code{window-total-height}, and
654 @code{window-width} is an alias for @code{window-body-width}. These
655 aliases are considered obsolete and will be removed in the future.
656
657 The pixel heights of a window's mode and header line can be retrieved
658 with the functions given below. Their return value is usually accurate
659 unless the window has not been displayed before: In that case, the
660 return value is based on an estimate of the font used for the window's
661 frame.
662
663 @defun window-mode-line-height &optional window
664 This function returns the height in pixels of @var{window}'s mode line.
665 @var{window} must be a live window and defaults to the selected one. If
666 @var{window} has no mode line, the return value is zero.
667 @end defun
668
669 @defun window-header-line-height &optional window
670 This function returns the height in pixels of @var{window}'s header
671 line. @var{window} must be a live window and defaults to the selected
672 one. If @var{window} has no header line, the return value is zero.
673 @end defun
674
675 Functions for retrieving the height and/or width of window dividers
676 (@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
677 (@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
678 described in the corresponding sections.
679
680 If your Lisp program needs to make layout decisions, you will find the
681 following function useful:
682
683 @defun window-max-chars-per-line &optional window face
684 This function returns the number of characters displayed in the
685 specified face @var{face} in the specified window @var{window} (which
686 must be a live window). If @var{face} was remapped (@pxref{Face
687 Remapping}), the information is returned for the remapped face. If
688 omitted or @code{nil}, @var{face} defaults to the default face, and
689 @var{window} defaults to the selected window.
690
691 Unlike @code{window-body-width}, this function accounts for the actual
692 size of @var{face}'s font, instead of working in units of the canonical
693 character width of @var{window}'s frame (@pxref{Frame Font}). It also
694 accounts for space used by the continuation glyph, if @var{window} lacks
695 one or both of its fringes.
696 @end defun
697
698 @cindex fixed-size window
699 @vindex window-min-height
700 @vindex window-min-width
701 Commands that change the size of windows (@pxref{Resizing Windows}),
702 or split them (@pxref{Splitting Windows}), obey the variables
703 @code{window-min-height} and @code{window-min-width}, which specify the
704 smallest allowable window height and width. They also obey the variable
705 @code{window-size-fixed}, with which a window can be @dfn{fixed} in
706 size (@pxref{Preserving Window Sizes}).
707
708 @defopt window-min-height
709 This option specifies the minimum total height, in lines, of any window.
710 Its value has to accommodate at least one text line as well as a mode
711 and header line, a horizontal scroll bar and a bottom divider, if
712 present.
713 @end defopt
714
715 @defopt window-min-width
716 This option specifies the minimum total width, in columns, of any
717 window. Its value has to accommodate two text columns as well as
718 margins, fringes, a scroll bar and a right divider, if present.
719 @end defopt
720
721 The following function tells how small a specific window can get taking
722 into account the sizes of its areas and the values of
723 @code{window-min-height}, @code{window-min-width} and
724 @code{window-size-fixed} (@pxref{Preserving Window Sizes}).
725
726 @defun window-min-size &optional window horizontal ignore pixelwise
727 This function returns the minimum size of @var{window}. @var{window}
728 must be a valid window and defaults to the selected one. The optional
729 argument @var{horizontal} non-@code{nil} means to return the minimum
730 number of columns of @var{window}; otherwise return the minimum number
731 of @var{window}'s lines.
732
733 The return value makes sure that all components of @var{window} remain
734 fully visible if @var{window}'s size were actually set to it. With
735 @var{horizontal} @code{nil} it includes the mode and header line, the
736 horizontal scroll bar and the bottom divider, if present. With
737 @var{horizontal} non-@code{nil} it includes the margins and fringes, the
738 vertical scroll bar and the right divider, if present.
739
740 The optional argument @var{ignore}, if non-@code{nil}, means ignore
741 restrictions imposed by fixed size windows, @code{window-min-height} or
742 @code{window-min-width} settings. If @var{ignore} equals @code{safe},
743 live windows may get as small as @code{window-safe-min-height} lines and
744 @code{window-safe-min-width} columns. If @var{ignore} is a window,
745 ignore restrictions for that window only. Any other non-@code{nil}
746 value means ignore all of the above restrictions for all windows.
747
748 The optional argument @var{pixelwise} non-@code{nil} means to return the
749 minimum size of @var{window} counted in pixels.
750 @end defun
751
752 @node Resizing Windows
753 @section Resizing Windows
754 @cindex window resizing
755 @cindex resize window
756 @cindex changing window size
757 @cindex window size, changing
758
759 This section describes functions for resizing a window without
760 changing the size of its frame. Because live windows do not overlap,
761 these functions are meaningful only on frames that contain two or more
762 windows: resizing a window also changes the size of a neighboring
763 window. If there is just one window on a frame, its size cannot be
764 changed except by resizing the frame (@pxref{Size and Position}).
765
766 Except where noted, these functions also accept internal windows as
767 arguments. Resizing an internal window causes its child windows to be
768 resized to fit the same space.
769
770 @defun window-resizable window delta &optional horizontal ignore pixelwise
771 This function returns @var{delta} if the size of @var{window} can be
772 changed vertically by @var{delta} lines. If the optional argument
773 @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
774 @var{window} can be resized horizontally by @var{delta} columns. It
775 does not actually change the window size.
776
777 If @var{window} is @code{nil}, it defaults to the selected window.
778
779 A positive value of @var{delta} means to check whether the window can be
780 enlarged by that number of lines or columns; a negative value of
781 @var{delta} means to check whether the window can be shrunk by that many
782 lines or columns. If @var{delta} is non-zero, a return value of 0 means
783 that the window cannot be resized.
784
785 Normally, the variables @code{window-min-height} and
786 @code{window-min-width} specify the smallest allowable window size
787 (@pxref{Window Sizes}). However, if the optional argument @var{ignore}
788 is non-@code{nil}, this function ignores @code{window-min-height} and
789 @code{window-min-width}, as well as @code{window-size-fixed}. Instead,
790 it considers the minimum-height window to be one consisting of a header
791 and a mode line, a horizontal scrollbar and a bottom divider (if any),
792 plus a text area one line tall; and a minimum-width window as one
793 consisting of fringes, margins, a scroll bar and a right divider (if
794 any), plus a text area two columns wide.
795
796 If the optional argument @var{pixelwise} is non-@code{nil},
797 @var{delta} is interpreted as pixels.
798 @end defun
799
800 @defun window-resize window delta &optional horizontal ignore pixelwise
801 This function resizes @var{window} by @var{delta} increments. If
802 @var{horizontal} is @code{nil}, it changes the height by @var{delta}
803 lines; otherwise, it changes the width by @var{delta} columns. A
804 positive @var{delta} means to enlarge the window, and a negative
805 @var{delta} means to shrink it.
806
807 If @var{window} is @code{nil}, it defaults to the selected window. If
808 the window cannot be resized as demanded, an error is signaled.
809
810 The optional argument @var{ignore} has the same meaning as for the
811 function @code{window-resizable} above.
812
813 If the optional argument @var{pixelwise} is non-@code{nil},
814 @var{delta} will be interpreted as pixels.
815
816 The choice of which window edges this function alters depends on the
817 values of the option @code{window-combination-resize} and the
818 combination limits of the involved windows; in some cases, it may alter
819 both edges. @xref{Recombining Windows}. To resize by moving only the
820 bottom or right edge of a window, use the function
821 @code{adjust-window-trailing-edge}.
822 @end defun
823
824 @c The commands enlarge-window, enlarge-window-horizontally,
825 @c shrink-window, and shrink-window-horizontally are documented in the
826 @c Emacs manual. They are not preferred for calling from Lisp.
827
828 @defun adjust-window-trailing-edge window delta &optional horizontal pixelwise
829 This function moves @var{window}'s bottom edge by @var{delta} lines.
830 If optional argument @var{horizontal} is non-@code{nil}, it instead
831 moves the right edge by @var{delta} columns. If @var{window} is
832 @code{nil}, it defaults to the selected window.
833
834 If the optional argument @var{pixelwise} is non-@code{nil},
835 @var{delta} is interpreted as pixels.
836
837 A positive @var{delta} moves the edge downwards or to the right; a
838 negative @var{delta} moves it upwards or to the left. If the edge
839 cannot be moved as far as specified by @var{delta}, this function
840 moves it as far as possible but does not signal a error.
841
842 This function tries to resize windows adjacent to the edge that is
843 moved. If this is not possible for some reason (e.g., if that adjacent
844 window is fixed-size), it may resize other windows.
845 @end defun
846
847 @cindex pixelwise, resizing windows
848 @defopt window-resize-pixelwise
849 If the value of this option is non-@code{nil}, Emacs resizes windows in
850 units of pixels. This currently affects functions like
851 @code{split-window} (@pxref{Splitting Windows}), @code{maximize-window},
852 @code{minimize-window}, @code{fit-window-to-buffer},
853 @code{fit-frame-to-buffer} and
854 @code{shrink-window-if-larger-than-buffer} (all listed below).
855
856 Note that when a frame's pixel size is not a multiple of its character
857 size, at least one window may get resized pixelwise even if this
858 option is @code{nil}. The default value is @code{nil}.
859 @end defopt
860
861 The following commands resize windows in more specific ways. When
862 called interactively, they act on the selected window.
863
864 @deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size
865 This command adjusts the height or width of @var{window} to fit the text
866 in it. It returns non-@code{nil} if it was able to resize @var{window},
867 and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
868 defaults to the selected window. Otherwise, it should be a live window.
869
870 If @var{window} is part of a vertical combination, this function adjusts
871 @var{window}'s height. The new height is calculated from the actual
872 height of the accessible portion of its buffer. The optional argument
873 @var{max-height}, if non-@code{nil}, specifies the maximum total height
874 that this function can give @var{window}. The optional argument
875 @var{min-height}, if non-@code{nil}, specifies the minimum total height
876 that it can give, which overrides the variable @code{window-min-height}.
877 Both @var{max-height} and @var{min-height} are specified in lines and
878 include mode and header line and a bottom divider, if any.
879
880 If @var{window} is part of a horizontal combination and the value of the
881 option @code{fit-window-to-buffer-horizontally} (see below) is
882 non-@code{nil}, this function adjusts @var{window}'s height. The new
883 width of @var{window} is calculated from the maximum length of its
884 buffer's lines that follow the current start position of @var{window}.
885 The optional argument @var{max-width} specifies a maximum width and
886 defaults to the width of @var{window}'s frame. The optional argument
887 @var{min-width} specifies a minimum width and defaults to
888 @code{window-min-width}. Both @var{max-width} and @var{min-width} are
889 specified in columns and include fringes, margins and scrollbars, if
890 any.
891
892 The optional argument @var{preserve-size}, if non-@code{nil}, will
893 install a parameter to preserve the size of @var{window} during future
894 resize operations (@pxref{Preserving Window Sizes}).
895
896 If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil},
897 this function will try to resize the frame of @var{window} to fit its
898 contents by calling @code{fit-frame-to-buffer} (see below).
899 @end deffn
900
901 @defopt fit-window-to-buffer-horizontally
902 If this is non-@code{nil}, @code{fit-window-to-buffer} can resize
903 windows horizontally. If this is @code{nil} (the default)
904 @code{fit-window-to-buffer} never resizes windows horizontally. If this
905 is @code{only}, it can resize windows horizontally only. Any other
906 value means @code{fit-window-to-buffer} can resize windows in both
907 dimensions.
908 @end defopt
909
910 @defopt fit-frame-to-buffer
911 If this option is non-@code{nil}, @code{fit-window-to-buffer} can fit a
912 frame to its buffer. A frame is fit if and only if its root window is a
913 live window and this option is non-@code{nil}. If this is
914 @code{horizontally}, frames are fit horizontally only. If this is
915 @code{vertically}, frames are fit vertically only. Any other
916 non-@code{nil} value means frames can be resized in both dimensions.
917 @end defopt
918
919 If you have a frame that displays only one window, you can fit that
920 frame to its buffer using the command @code{fit-frame-to-buffer}.
921
922 @deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only
923 This command adjusts the size of @var{frame} to display the contents of
924 its buffer exactly. @var{frame} can be any live frame and defaults to
925 the selected one. Fitting is done only if @var{frame}'s root window is
926 live. The arguments @var{max-height}, @var{min-height}, @var{max-width}
927 and @var{min-width} specify bounds on the new total size of
928 @var{frame}'s root window. @var{min-height} and @var{min-width} default
929 to the values of @code{window-min-height} and @code{window-min-width}
930 respectively.
931
932 If the optional argument @var{only} is @code{vertically}, this function
933 may resize the frame vertically only. If @var{only} is
934 @code{horizontally}, it may resize the frame horizontally only.
935 @end deffn
936
937 The behavior of @code{fit-frame-to-buffer} can be controlled with the
938 help of the two options listed next.
939
940 @defopt fit-frame-to-buffer-margins
941 This option can be used to specify margins around frames to be fit by
942 @code{fit-frame-to-buffer}. Such margins can be useful to avoid, for
943 example, that such frames overlap the taskbar.
944
945 It specifies the numbers of pixels to be left free on the left, above,
946 the right, and below a frame that shall be fit. The default specifies
947 @code{nil} for each which means to use no margins. The value specified
948 here can be overridden for a specific frame by that frame's
949 @code{fit-frame-to-buffer-margins} parameter, if present.
950 @end defopt
951
952 @defopt fit-frame-to-buffer-sizes
953 This option specifies size boundaries for @code{fit-frame-to-buffer}.
954 It specifies the total maximum and minimum lines and maximum and minimum
955 columns of the root window of any frame that shall be fit to its buffer.
956 If any of these values is non-@code{nil}, it overrides the corresponding
957 argument of @code{fit-frame-to-buffer}.
958 @end defopt
959
960 @deffn Command shrink-window-if-larger-than-buffer &optional window
961 This command attempts to reduce @var{window}'s height as much as
962 possible while still showing its full buffer, but no less than
963 @code{window-min-height} lines. The return value is non-@code{nil} if
964 the window was resized, and @code{nil} otherwise. If @var{window} is
965 omitted or @code{nil}, it defaults to the selected window. Otherwise,
966 it should be a live window.
967
968 This command does nothing if the window is already too short to
969 display all of its buffer, or if any of the buffer is scrolled
970 off-screen, or if the window is the only live window in its frame.
971
972 This command calls @code{fit-window-to-buffer} (see above) to do its
973 work.
974 @end deffn
975
976
977 @cindex balancing window sizes
978 @deffn Command balance-windows &optional window-or-frame
979 This function balances windows in a way that gives more space to
980 full-width and/or full-height windows. If @var{window-or-frame}
981 specifies a frame, it balances all windows on that frame. If
982 @var{window-or-frame} specifies a window, it balances only that window
983 and its siblings (@pxref{Windows and Frames}).
984 @end deffn
985
986 @deffn Command balance-windows-area
987 This function attempts to give all windows on the selected frame
988 approximately the same share of the screen area. Full-width or
989 full-height windows are not given more space than other windows.
990 @end deffn
991
992 @cindex maximizing windows
993 @deffn Command maximize-window &optional window
994 This function attempts to make @var{window} as large as possible, in
995 both dimensions, without resizing its frame or deleting other windows.
996 If @var{window} is omitted or @code{nil}, it defaults to the selected
997 window.
998 @end deffn
999
1000 @cindex minimizing windows
1001 @deffn Command minimize-window &optional window
1002 This function attempts to make @var{window} as small as possible, in
1003 both dimensions, without deleting it or resizing its frame. If
1004 @var{window} is omitted or @code{nil}, it defaults to the selected
1005 window.
1006 @end deffn
1007
1008
1009 @node Preserving Window Sizes
1010 @section Preserving Window Sizes
1011 @cindex preserving window sizes
1012
1013 A window can get resized explicitly by using one of the functions from
1014 the preceding section or implicitly, for example, when resizing an
1015 adjacent window, when splitting or deleting a window (@pxref{Splitting
1016 Windows}, @pxref{Deleting Windows}) or when resizing the window's frame
1017 (@pxref{Size and Position}).
1018
1019 It is possible to avoid implicit resizing of a specific window when
1020 there are one or more other resizable windows on the same frame. For
1021 this purpose, Emacs must be advised to @dfn{preserve} the size of that
1022 window. There are two basic ways to do that.
1023
1024 @defvar window-size-fixed
1025 If this buffer-local variable is non-@code{nil}, the size of any window
1026 displaying the buffer cannot normally be changed. Deleting a window or
1027 changing the frame's size may still change the window's size, if there
1028 is no choice.
1029
1030 If the value is @code{height}, then only the window's height is fixed;
1031 if the value is @code{width}, then only the window's width is fixed.
1032 Any other non-@code{nil} value fixes both the width and the height.
1033
1034 If this variable is @code{nil}, this does not necessarily mean that any
1035 window showing the buffer can be resized in the desired direction. To
1036 determine that, use the function @code{window-resizable}.
1037 @xref{Resizing Windows}.
1038 @end defvar
1039
1040 Often @code{window-size-fixed} is overly aggressive because it inhibits
1041 any attempt to explicitly resize or split an affected window as well.
1042 This may even happen after the window has been resized implicitly, for
1043 example, when deleting an adjacent window or resizing the window's
1044 frame. The following function tries hard to never disallow resizing
1045 such a window explicitly:
1046
1047 @defun window-preserve-size &optional window horizontal preserve
1048 This function (un-)marks the height of window @var{window} as preserved
1049 for future resize operations. @var{window} must be a live window and
1050 defaults to the selected one. If the optional argument @var{horizontal}
1051 is non-@code{nil}, it (un-)marks the width of @var{window} as preserved.
1052
1053 If the optional argument @var{preserve} is @code{t}, this means to
1054 preserve the current height/width of @var{window}'s body. The
1055 height/width of @var{window} will change only if Emacs has no better
1056 choice. Resizing a window whose height/width is preserved by this
1057 function never throws an error.
1058
1059 If @var{preserve} is @code{nil}, this means to stop preserving the
1060 height/width of @var{window}, lifting any respective restraint induced
1061 by a previous call of this function for @var{window}. Calling
1062 @code{enlarge-window}, @code{shrink-window} or
1063 @code{fit-window-to-buffer} with @var{window} as argument may also
1064 remove the respective restraint.
1065 @end defun
1066
1067 @code{window-preserve-size} is currently invoked by the following
1068 functions:
1069
1070 @table @code
1071 @item fit-window-to-buffer
1072 If the optional argument @var{preserve-size} of that function
1073 (@pxref{Resizing Windows}) is non-@code{nil}, the size established by
1074 that function is preserved.
1075
1076 @item display-buffer
1077 If the @var{alist} argument of that function (@pxref{Choosing Window})
1078 contains a @code{preserve-size} entry, the size of the window produced
1079 by that function is preserved.
1080 @end table
1081
1082 @code{window-preserve-size} installs a window parameter (@pxref{Window
1083 Parameters}) called @code{preserved-size} which is consulted by the
1084 window resizing functions. This parameter will not prevent resizing the
1085 window when the window shows another buffer than the one when
1086 @code{window-preserve-size} was invoked or if its size has changed since
1087 then.
1088
1089 The following function can be used to check whether the height of a
1090 particular window is preserved:
1091
1092 @defun window-preserved-size &optional window horizontal
1093 This function returns the preserved height of window @var{window} in
1094 pixels. @var{window} must be a live window and defaults to the selected
1095 one. If the optional argument @var{horizontal} is non-@code{nil}, it
1096 returns the preserved width of @var{window}. It returns @code{nil} if
1097 the size of @var{window} is not preserved.
1098 @end defun
1099
1100
1101 @node Splitting Windows
1102 @section Splitting Windows
1103 @cindex splitting windows
1104 @cindex window splitting
1105
1106 This section describes functions for creating a new window by
1107 @dfn{splitting} an existing one.
1108
1109 @defun split-window &optional window size side pixelwise
1110 This function creates a new live window next to the window
1111 @var{window}. If @var{window} is omitted or @code{nil}, it defaults
1112 to the selected window. That window is split, and reduced in
1113 size. The space is taken up by the new window, which is returned.
1114
1115 The optional second argument @var{size} determines the sizes of
1116 @var{window} and/or the new window. If it is omitted or @code{nil},
1117 both windows are given equal sizes; if there is an odd line, it is
1118 allocated to the new window. If @var{size} is a positive number,
1119 @var{window} is given @var{size} lines (or columns, depending on the
1120 value of @var{side}). If @var{size} is a negative number, the new
1121 window is given @minus{}@var{size} lines (or columns).
1122
1123 If @var{size} is @code{nil}, this function obeys the variables
1124 @code{window-min-height} and @code{window-min-width} (@pxref{Window
1125 Sizes}). Thus, it signals an error if splitting would result in making
1126 a window smaller than those variables specify. However, a
1127 non-@code{nil} value for @var{size} causes those variables to be
1128 ignored; in that case, the smallest allowable window is considered to be
1129 one that has space for a text area one line tall and/or two columns
1130 wide.
1131
1132 Hence, if @var{size} is specified, it's the caller's responsibility to
1133 check whether the emanating windows are large enough to encompass all
1134 areas like a mode line or a scroll bar. The function
1135 @code{window-min-size} (@pxref{Window Sizes}) can be used to determine
1136 the minimum requirements of @var{window} in this regard. Since the new
1137 window usually inherits areas like the mode line or the scroll bar
1138 from @var{window}, that function is also a good guess for the minimum
1139 size of the new window. The caller should specify a smaller size only
1140 if it correspondingly removes an inherited area before the next
1141 redisplay.
1142
1143 The optional third argument @var{side} determines the position of the
1144 new window relative to @var{window}. If it is @code{nil} or
1145 @code{below}, the new window is placed below @var{window}. If it is
1146 @code{above}, the new window is placed above @var{window}. In both
1147 these cases, @var{size} specifies a total window height, in lines.
1148
1149 If @var{side} is @code{t} or @code{right}, the new window is placed on
1150 the right of @var{window}. If @var{side} is @code{left}, the new
1151 window is placed on the left of @var{window}. In both these cases,
1152 @var{size} specifies a total window width, in columns.
1153
1154 The optional fourth argument @var{pixelwise}, if non-@code{nil}, means
1155 to interpret @var{size} in units of pixels, instead of lines and
1156 columns.
1157
1158 If @var{window} is a live window, the new window inherits various
1159 properties from it, including margins and scroll bars. If
1160 @var{window} is an internal window, the new window inherits the
1161 properties of the window selected within @var{window}'s frame.
1162
1163 The behavior of this function may be altered by the window parameters
1164 of @var{window}, so long as the variable
1165 @code{ignore-window-parameters} is @code{nil}. If the value of
1166 the @code{split-window} window parameter is @code{t}, this function
1167 ignores all other window parameters. Otherwise, if the value of the
1168 @code{split-window} window parameter is a function, that function is
1169 called with the arguments @var{window}, @var{size}, and @var{side}, in
1170 lieu of the usual action of @code{split-window}. Otherwise, this
1171 function obeys the @code{window-atom} or @code{window-side} window
1172 parameter, if any. @xref{Window Parameters}.
1173 @end defun
1174
1175 As an example, here is a sequence of @code{split-window} calls that
1176 yields the window configuration discussed in @ref{Windows and Frames}.
1177 This example demonstrates splitting a live window as well as splitting
1178 an internal window. We begin with a frame containing a single window
1179 (a live root window), which we denote by @var{W4}. Calling
1180 @code{(split-window W4)} yields this window configuration:
1181
1182 @smallexample
1183 @group
1184 ______________________________________
1185 | ____________________________________ |
1186 || ||
1187 || ||
1188 || ||
1189 ||_________________W4_________________||
1190 | ____________________________________ |
1191 || ||
1192 || ||
1193 || ||
1194 ||_________________W5_________________||
1195 |__________________W3__________________|
1196
1197 @end group
1198 @end smallexample
1199
1200 @noindent
1201 The @code{split-window} call has created a new live window, denoted by
1202 @var{W5}. It has also created a new internal window, denoted by
1203 @var{W3}, which becomes the root window and the parent of both
1204 @var{W4} and @var{W5}.
1205
1206 Next, we call @code{(split-window W3 nil 'left)}, passing the
1207 internal window @var{W3} as the argument. The result:
1208
1209 @smallexample
1210 @group
1211 ______________________________________
1212 | ______ ____________________________ |
1213 || || __________________________ ||
1214 || ||| |||
1215 || ||| |||
1216 || ||| |||
1217 || |||____________W4____________|||
1218 || || __________________________ ||
1219 || ||| |||
1220 || ||| |||
1221 || |||____________W5____________|||
1222 ||__W2__||_____________W3_____________ |
1223 |__________________W1__________________|
1224 @end group
1225 @end smallexample
1226
1227 @noindent
1228 A new live window @var{W2} is created, to the left of the internal
1229 window @var{W3}. A new internal window @var{W1} is created, becoming
1230 the new root window.
1231
1232 For interactive use, Emacs provides two commands which always split
1233 the selected window. These call @code{split-window} internally.
1234
1235 @deffn Command split-window-right &optional size
1236 This function splits the selected window into two side-by-side
1237 windows, putting the selected window on the left. If @var{size} is
1238 positive, the left window gets @var{size} columns; if @var{size} is
1239 negative, the right window gets @minus{}@var{size} columns.
1240 @end deffn
1241
1242 @deffn Command split-window-below &optional size
1243 This function splits the selected window into two windows, one above
1244 the other, leaving the upper window selected. If @var{size} is
1245 positive, the upper window gets @var{size} lines; if @var{size} is
1246 negative, the lower window gets @minus{}@var{size} lines.
1247 @end deffn
1248
1249 @defopt split-window-keep-point
1250 If the value of this variable is non-@code{nil} (the default),
1251 @code{split-window-below} behaves as described above.
1252
1253 If it is @code{nil}, @code{split-window-below} adjusts point in each
1254 of the two windows to minimize redisplay. (This is useful on slow
1255 terminals.) It selects whichever window contains the screen line that
1256 point was previously on. Note that this only affects
1257 @code{split-window-below}, not the lower-level @code{split-window}
1258 function.
1259 @end defopt
1260
1261
1262 @node Deleting Windows
1263 @section Deleting Windows
1264 @cindex deleting windows
1265
1266 @dfn{Deleting} a window removes it from the frame's window tree. If
1267 the window is a live window, it disappears from the screen. If the
1268 window is an internal window, its child windows are deleted too.
1269
1270 Even after a window is deleted, it continues to exist as a Lisp
1271 object, until there are no more references to it. Window deletion can
1272 be reversed, by restoring a saved window configuration (@pxref{Window
1273 Configurations}).
1274
1275 @deffn Command delete-window &optional window
1276 This function removes @var{window} from display and returns
1277 @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
1278 the selected window. If deleting the window would leave no more
1279 windows in the window tree (e.g., if it is the only live window in the
1280 frame), an error is signaled.
1281
1282 By default, the space taken up by @var{window} is given to one of its
1283 adjacent sibling windows, if any. However, if the variable
1284 @code{window-combination-resize} is non-@code{nil}, the space is
1285 proportionally distributed among any remaining windows in the same
1286 window combination. @xref{Recombining Windows}.
1287
1288 The behavior of this function may be altered by the window parameters
1289 of @var{window}, so long as the variable
1290 @code{ignore-window-parameters} is @code{nil}. If the value of
1291 the @code{delete-window} window parameter is @code{t}, this function
1292 ignores all other window parameters. Otherwise, if the value of the
1293 @code{delete-window} window parameter is a function, that function is
1294 called with the argument @var{window}, in lieu of the usual action of
1295 @code{delete-window}. Otherwise, this function obeys the
1296 @code{window-atom} or @code{window-side} window parameter, if any.
1297 @xref{Window Parameters}.
1298 @end deffn
1299
1300 @deffn Command delete-other-windows &optional window
1301 This function makes @var{window} fill its frame, by deleting other
1302 windows as necessary. If @var{window} is omitted or @code{nil}, it
1303 defaults to the selected window. The return value is @code{nil}.
1304
1305 The behavior of this function may be altered by the window parameters
1306 of @var{window}, so long as the variable
1307 @code{ignore-window-parameters} is @code{nil}. If the value of
1308 the @code{delete-other-windows} window parameter is @code{t}, this
1309 function ignores all other window parameters. Otherwise, if the value
1310 of the @code{delete-other-windows} window parameter is a function,
1311 that function is called with the argument @var{window}, in lieu of the
1312 usual action of @code{delete-other-windows}. Otherwise, this function
1313 obeys the @code{window-atom} or @code{window-side} window parameter,
1314 if any. @xref{Window Parameters}.
1315 @end deffn
1316
1317 @deffn Command delete-windows-on &optional buffer-or-name frame
1318 This function deletes all windows showing @var{buffer-or-name}, by
1319 calling @code{delete-window} on those windows. @var{buffer-or-name}
1320 should be a buffer, or the name of a buffer; if omitted or @code{nil},
1321 it defaults to the current buffer. If there are no windows showing
1322 the specified buffer, this function does nothing. If the specified
1323 buffer is a minibuffer, an error is signaled.
1324
1325 If there is a dedicated window showing the buffer, and that window is
1326 the only one on its frame, this function also deletes that frame if it
1327 is not the only frame on the terminal.
1328
1329 The optional argument @var{frame} specifies which frames to operate
1330 on:
1331
1332 @itemize @bullet
1333 @item @code{nil}
1334 means operate on all frames.
1335 @item @code{t}
1336 means operate on the selected frame.
1337 @item @code{visible}
1338 means operate on all visible frames.
1339 @item @code{0}
1340 means operate on all visible or iconified frames.
1341 @item A frame
1342 means operate on that frame.
1343 @end itemize
1344
1345 Note that this argument does not have the same meaning as in other
1346 functions which scan all live windows (@pxref{Cyclic Window
1347 Ordering}). Specifically, the meanings of @code{t} and @code{nil} here
1348 are the opposite of what they are in those other functions.
1349 @end deffn
1350
1351
1352 @node Recombining Windows
1353 @section Recombining Windows
1354 @cindex recombining windows
1355 @cindex windows, recombining
1356
1357 When deleting the last sibling of a window @var{W}, its parent window
1358 is deleted too, with @var{W} replacing it in the window tree. This
1359 means that @var{W} must be recombined with its parent's siblings to
1360 form a new window combination (@pxref{Windows and Frames}). In some
1361 occasions, deleting a live window may even entail the deletion of two
1362 internal windows.
1363
1364 @smallexample
1365 @group
1366 ______________________________________
1367 | ______ ____________________________ |
1368 || || __________________________ ||
1369 || ||| ___________ ___________ |||
1370 || |||| || ||||
1371 || ||||____W6_____||_____W7____||||
1372 || |||____________W4____________|||
1373 || || __________________________ ||
1374 || ||| |||
1375 || ||| |||
1376 || |||____________W5____________|||
1377 ||__W2__||_____________W3_____________ |
1378 |__________________W1__________________|
1379
1380 @end group
1381 @end smallexample
1382
1383 @noindent
1384 Deleting @var{W5} in this configuration normally causes the deletion of
1385 @var{W3} and @var{W4}. The remaining live windows @var{W2},
1386 @var{W6} and @var{W7} are recombined to form a new horizontal
1387 combination with parent @var{W1}.
1388
1389 Sometimes, however, it makes sense to not delete a parent window like
1390 @var{W4}. In particular, a parent window should not be removed when it
1391 was used to preserve a combination embedded in a combination of the same
1392 type. Such embeddings make sense to assure that when you split a window
1393 and subsequently delete the new window, Emacs reestablishes the layout
1394 of the associated frame as it existed before the splitting.
1395
1396 Consider a scenario starting with two live windows @var{W2} and
1397 @var{W3} and their parent @var{W1}.
1398
1399 @smallexample
1400 @group
1401 ______________________________________
1402 | ____________________________________ |
1403 || ||
1404 || ||
1405 || ||
1406 || ||
1407 || ||
1408 || ||
1409 ||_________________W2_________________||
1410 | ____________________________________ |
1411 || ||
1412 || ||
1413 ||_________________W3_________________||
1414 |__________________W1__________________|
1415
1416 @end group
1417 @end smallexample
1418
1419 @noindent
1420 Split @var{W2} to make a new window @var{W4} as follows.
1421
1422 @smallexample
1423 @group
1424 ______________________________________
1425 | ____________________________________ |
1426 || ||
1427 || ||
1428 ||_________________W2_________________||
1429 | ____________________________________ |
1430 || ||
1431 || ||
1432 ||_________________W4_________________||
1433 | ____________________________________ |
1434 || ||
1435 || ||
1436 ||_________________W3_________________||
1437 |__________________W1__________________|
1438
1439 @end group
1440 @end smallexample
1441
1442 @noindent
1443 Now, when enlarging a window vertically, Emacs tries to obtain the
1444 corresponding space from its lower sibling, provided such a window
1445 exists. In our scenario, enlarging @var{W4} will steal space from
1446 @var{W3}.
1447
1448 @smallexample
1449 @group
1450 ______________________________________
1451 | ____________________________________ |
1452 || ||
1453 || ||
1454 ||_________________W2_________________||
1455 | ____________________________________ |
1456 || ||
1457 || ||
1458 || ||
1459 || ||
1460 ||_________________W4_________________||
1461 | ____________________________________ |
1462 ||_________________W3_________________||
1463 |__________________W1__________________|
1464
1465 @end group
1466 @end smallexample
1467
1468 @noindent
1469 Deleting @var{W4} will now give its entire space to @var{W2},
1470 including the space earlier stolen from @var{W3}.
1471
1472 @smallexample
1473 @group
1474 ______________________________________
1475 | ____________________________________ |
1476 || ||
1477 || ||
1478 || ||
1479 || ||
1480 || ||
1481 || ||
1482 || ||
1483 || ||
1484 ||_________________W2_________________||
1485 | ____________________________________ |
1486 ||_________________W3_________________||
1487 |__________________W1__________________|
1488
1489 @end group
1490 @end smallexample
1491
1492 @noindent
1493 This can be counterintuitive, in particular if @var{W4} were used for
1494 displaying a buffer only temporarily (@pxref{Temporary Displays}), and
1495 you want to continue working with the initial layout.
1496
1497 The behavior can be fixed by making a new parent window when splitting
1498 @var{W2}. The variable described next allows that to be done.
1499
1500 @defopt window-combination-limit
1501 This variable controls whether splitting a window shall make a new
1502 parent window. The following values are recognized:
1503
1504 @table @code
1505 @item nil
1506 This means that the new live window is allowed to share the existing
1507 parent window, if one exists, provided the split occurs in the same
1508 direction as the existing window combination (otherwise, a new internal
1509 window is created anyway).
1510
1511 @item window-size
1512 In this case @code{display-buffer} makes a new parent window if it is
1513 passed a @code{window-height} or @code{window-width} entry in the
1514 @var{alist} argument (@pxref{Display Action Functions}).
1515
1516 @item temp-buffer
1517 This value causes the creation of a new parent window when a window is
1518 split for showing a temporary buffer (@pxref{Temporary Displays}) only.
1519
1520 @item display-buffer
1521 This means that when @code{display-buffer} (@pxref{Choosing Window})
1522 splits a window it always makes a new parent window.
1523
1524 @item t
1525 In this case a new parent window is always created when splitting a
1526 window. Thus, if the value of this variable is at all times @code{t},
1527 then at all times every window tree is a binary tree (a tree where each
1528 window except the root window has exactly one sibling).
1529 @end table
1530
1531 The default is @code{nil}. Other values are reserved for future use.
1532
1533 If, as a consequence of this variable's setting, @code{split-window}
1534 makes a new parent window, it also calls
1535 @code{set-window-combination-limit} (see below) on the newly-created
1536 internal window. This affects how the window tree is rearranged when
1537 the child windows are deleted (see below).
1538 @end defopt
1539
1540 If @code{window-combination-limit} is @code{t}, splitting @var{W2} in
1541 the initial configuration of our scenario would have produced this:
1542
1543 @smallexample
1544 @group
1545 ______________________________________
1546 | ____________________________________ |
1547 || __________________________________ ||
1548 ||| |||
1549 |||________________W2________________|||
1550 || __________________________________ ||
1551 ||| |||
1552 |||________________W4________________|||
1553 ||_________________W5_________________||
1554 | ____________________________________ |
1555 || ||
1556 || ||
1557 ||_________________W3_________________||
1558 |__________________W1__________________|
1559
1560 @end group
1561 @end smallexample
1562
1563 @noindent
1564 A new internal window @var{W5} has been created; its children are
1565 @var{W2} and the new live window @var{W4}. Now, @var{W2} is the only
1566 sibling of @var{W4}, so enlarging @var{W4} will try to shrink
1567 @var{W2}, leaving @var{W3} unaffected. Observe that @var{W5}
1568 represents a vertical combination of two windows embedded in the
1569 vertical combination @var{W1}.
1570
1571 @cindex window combination limit
1572 @defun set-window-combination-limit window limit
1573 This function sets the @dfn{combination limit} of the window
1574 @var{window} to @var{limit}. This value can be retrieved via the
1575 function @code{window-combination-limit}. See below for its effects;
1576 note that it is only meaningful for internal windows. The
1577 @code{split-window} function automatically calls this function, passing
1578 it @code{t} as @var{limit}, provided the value of the variable
1579 @code{window-combination-limit} is @code{t} when it is called.
1580 @end defun
1581
1582 @defun window-combination-limit window
1583 This function returns the combination limit for @var{window}.
1584
1585 The combination limit is meaningful only for an internal window. If it
1586 is @code{nil}, then Emacs is allowed to automatically delete
1587 @var{window}, in response to a window deletion, in order to group the
1588 child windows of @var{window} with its sibling windows to form a new
1589 window combination. If the combination limit is @code{t}, the child
1590 windows of @var{window} are never automatically recombined with its
1591 siblings.
1592
1593 If, in the configuration shown at the beginning of this section, the
1594 combination limit of @var{W4} (the parent window of @var{W6} and
1595 @var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete
1596 @var{W4} too.
1597 @end defun
1598
1599 Alternatively, the problems sketched above can be avoided by always
1600 resizing all windows in the same combination whenever one of its windows
1601 is split or deleted. This also permits splitting windows that would be
1602 otherwise too small for such an operation.
1603
1604 @defopt window-combination-resize
1605 If this variable is @code{nil}, @code{split-window} can only split a
1606 window (denoted by @var{window}) if @var{window}'s screen area is large
1607 enough to accommodate both itself and the new window.
1608
1609 If this variable is @code{t}, @code{split-window} tries to resize all
1610 windows that are part of the same combination as @var{window}, in order
1611 to accommodate the new window. In particular, this may allow
1612 @code{split-window} to succeed even if @var{window} is a fixed-size
1613 window or too small to ordinarily split. Furthermore, subsequently
1614 resizing or deleting @var{window} may resize all other windows in its
1615 combination.
1616
1617 The default is @code{nil}. Other values are reserved for future use.
1618 The value of this variable is ignored when
1619 @code{window-combination-limit} is non-@code{nil}.
1620 @end defopt
1621
1622 To illustrate the effect of @code{window-combination-resize}, consider
1623 the following frame layout.
1624
1625 @smallexample
1626 @group
1627 ______________________________________
1628 | ____________________________________ |
1629 || ||
1630 || ||
1631 || ||
1632 || ||
1633 ||_________________W2_________________||
1634 | ____________________________________ |
1635 || ||
1636 || ||
1637 || ||
1638 || ||
1639 ||_________________W3_________________||
1640 |__________________W1__________________|
1641
1642 @end group
1643 @end smallexample
1644
1645 @noindent
1646 If @code{window-combination-resize} is @code{nil}, splitting window
1647 @var{W3} leaves the size of @var{W2} unchanged:
1648
1649 @smallexample
1650 @group
1651 ______________________________________
1652 | ____________________________________ |
1653 || ||
1654 || ||
1655 || ||
1656 || ||
1657 ||_________________W2_________________||
1658 | ____________________________________ |
1659 || ||
1660 ||_________________W3_________________||
1661 | ____________________________________ |
1662 || ||
1663 ||_________________W4_________________||
1664 |__________________W1__________________|
1665
1666 @end group
1667 @end smallexample
1668
1669 @noindent
1670 If @code{window-combination-resize} is @code{t}, splitting @var{W3}
1671 instead leaves all three live windows with approximately the same
1672 height:
1673
1674 @smallexample
1675 @group
1676 ______________________________________
1677 | ____________________________________ |
1678 || ||
1679 || ||
1680 ||_________________W2_________________||
1681 | ____________________________________ |
1682 || ||
1683 || ||
1684 ||_________________W3_________________||
1685 | ____________________________________ |
1686 || ||
1687 || ||
1688 ||_________________W4_________________||
1689 |__________________W1__________________|
1690
1691 @end group
1692 @end smallexample
1693
1694 @noindent
1695 Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will
1696 distribute its space proportionally among the two remaining live
1697 windows.
1698
1699
1700 @node Selecting Windows
1701 @section Selecting Windows
1702 @cindex selecting a window
1703
1704 @defun select-window window &optional norecord
1705 This function makes @var{window} the selected window and the window
1706 selected within its frame (@pxref{Basic Windows}) and selects that
1707 frame. It also makes @var{window}'s buffer (@pxref{Buffers and
1708 Windows}) current and sets that buffer's value of @code{point} to the
1709 value of @code{window-point} (@pxref{Window Point}) in @var{window}.
1710 @var{window} must be a live window. The return value is @var{window}.
1711
1712 By default, this function also moves @var{window}'s buffer to the front
1713 of the buffer list (@pxref{Buffer List}), and makes @var{window} the
1714 most recently selected window. However, if the optional argument
1715 @var{norecord} is non-@code{nil}, these additional actions are omitted.
1716
1717 This function runs @code{buffer-list-update-hook} (@pxref{Buffer List})
1718 unless @var{norecord} is non-@code{nil}. Note that applications and
1719 internal routines often temporarily select a window in order to simplify
1720 coding. As a rule, such selections (including those made by the macros
1721 @code{save-selected-window} and @code{with-selected-window} below) are
1722 not recorded thus avoiding to pollute @code{buffer-list-update-hook}.
1723 Selections that really count are those causing a visible change in
1724 the next redisplay of @var{window}'s frame and should be always
1725 recorded. This also means that to run a function each time a window
1726 gets selected, putting it on @code{buffer-list-update-hook} should be
1727 the right choice.
1728 @end defun
1729
1730 @cindex most recently selected windows
1731 The sequence of calls to @code{select-window} with a non-@code{nil}
1732 @var{norecord} argument determines an ordering of windows by their
1733 selection time. The function @code{get-lru-window} can be used to
1734 retrieve the least recently selected live window (@pxref{Cyclic Window
1735 Ordering}).
1736
1737 @defmac save-selected-window forms@dots{}
1738 This macro records the selected frame, as well as the selected window
1739 of each frame, executes @var{forms} in sequence, then restores the
1740 earlier selected frame and windows. It also saves and restores the
1741 current buffer. It returns the value of the last form in @var{forms}.
1742
1743 This macro does not save or restore anything about the sizes,
1744 arrangement or contents of windows; therefore, if @var{forms} change
1745 them, the change persists. If the previously selected window of some
1746 frame is no longer live at the time of exit from @var{forms}, that
1747 frame's selected window is left alone. If the previously selected
1748 window is no longer live, then whatever window is selected at the end of
1749 @var{forms} remains selected. The current buffer is restored if and
1750 only if it is still live when exiting @var{forms}.
1751
1752 This macro changes neither the ordering of recently selected windows nor
1753 the buffer list.
1754 @end defmac
1755
1756 @defmac with-selected-window window forms@dots{}
1757 This macro selects @var{window}, executes @var{forms} in sequence, then
1758 restores the previously selected window and current buffer. The ordering
1759 of recently selected windows and the buffer list remain unchanged unless
1760 you deliberately change them within @var{forms}; for example, by calling
1761 @code{select-window} with argument @var{norecord} @code{nil}.
1762
1763 This macro does not change the order of recently selected windows or
1764 the buffer list.
1765 @end defmac
1766
1767 @defun frame-selected-window &optional frame
1768 This function returns the window on @var{frame} that is selected
1769 within that frame. @var{frame} should be a live frame; if omitted or
1770 @code{nil}, it defaults to the selected frame.
1771 @end defun
1772
1773 @defun set-frame-selected-window frame window &optional norecord
1774 This function makes @var{window} the window selected within the frame
1775 @var{frame}. @var{frame} should be a live frame; if @code{nil}, it
1776 defaults to the selected frame. @var{window} should be a live window;
1777 if @code{nil}, it defaults to the selected window.
1778
1779 If @var{frame} is the selected frame, this makes @var{window} the
1780 selected window.
1781
1782 If the optional argument @var{norecord} is non-@code{nil}, this
1783 function does not alter the list of most recently selected windows,
1784 nor the buffer list.
1785 @end defun
1786
1787 @cindex window use time
1788 @cindex use time of window
1789 @cindex window order by time of last use
1790 @defun window-use-time &optional window
1791 This functions returns the use time of window @var{window}.
1792 @var{window} must be a live window and defaults to the selected one.
1793
1794 The @dfn{use time} of a window is not really a time value, but an
1795 integer that does increase monotonically with each call of
1796 @code{select-window} with a @code{nil} @var{norecord} argument. The
1797 window with the lowest use time is usually called the least recently
1798 used window while the window with the highest use time is called the
1799 most recently used one (@pxref{Cyclic Window Ordering}).
1800 @end defun
1801
1802
1803 @node Cyclic Window Ordering
1804 @section Cyclic Ordering of Windows
1805 @cindex cyclic ordering of windows
1806 @cindex ordering of windows, cyclic
1807 @cindex window ordering, cyclic
1808
1809 When you use the command @kbd{C-x o} (@code{other-window}) to select
1810 some other window, it moves through live windows in a specific order.
1811 For any given configuration of windows, this order never varies. It
1812 is called the @dfn{cyclic ordering of windows}.
1813
1814 The ordering is determined by a depth-first traversal of each frame's
1815 window tree, retrieving the live windows which are the leaf nodes of the
1816 tree (@pxref{Windows and Frames}). If the minibuffer is active, the
1817 minibuffer window is included too. The ordering is cyclic, so the last
1818 window in the sequence is followed by the first one.
1819
1820 @defun next-window &optional window minibuf all-frames
1821 @cindex minibuffer window, and @code{next-window}
1822 This function returns a live window, the one following @var{window} in
1823 the cyclic ordering of windows. @var{window} should be a live window;
1824 if omitted or @code{nil}, it defaults to the selected window.
1825
1826 The optional argument @var{minibuf} specifies whether minibuffer windows
1827 should be included in the cyclic ordering. Normally, when @var{minibuf}
1828 is @code{nil}, a minibuffer window is included only if it is currently
1829 active; this matches the behavior of @kbd{C-x o}. (Note that a
1830 minibuffer window is active as long as its minibuffer is in use; see
1831 @ref{Minibuffers}).
1832
1833 If @var{minibuf} is @code{t}, the cyclic ordering includes all
1834 minibuffer windows. If @var{minibuf} is neither @code{t} nor
1835 @code{nil}, minibuffer windows are not included even if they are active.
1836
1837 The optional argument @var{all-frames} specifies which frames to
1838 consider:
1839
1840 @itemize @bullet
1841 @item @code{nil}
1842 means to consider windows on @var{window}'s frame. If the minibuffer
1843 window is considered (as specified by the @var{minibuf} argument),
1844 then frames that share the minibuffer window are considered too.
1845
1846 @item @code{t}
1847 means to consider windows on all existing frames.
1848
1849 @item @code{visible}
1850 means to consider windows on all visible frames.
1851
1852 @item 0
1853 means to consider windows on all visible or iconified frames.
1854
1855 @item A frame
1856 means to consider windows on that specific frame.
1857
1858 @item Anything else
1859 means to consider windows on @var{window}'s frame, and no others.
1860 @end itemize
1861
1862 If more than one frame is considered, the cyclic ordering is obtained
1863 by appending the orderings for those frames, in the same order as the
1864 list of all live frames (@pxref{Finding All Frames}).
1865 @end defun
1866
1867 @defun previous-window &optional window minibuf all-frames
1868 This function returns a live window, the one preceding @var{window} in
1869 the cyclic ordering of windows. The other arguments are handled like
1870 in @code{next-window}.
1871 @end defun
1872
1873 @deffn Command other-window count &optional all-frames
1874 This function selects a live window, one @var{count} places from the
1875 selected window in the cyclic ordering of windows. If @var{count} is
1876 a positive number, it skips @var{count} windows forwards; if
1877 @var{count} is negative, it skips @minus{}@var{count} windows
1878 backwards; if @var{count} is zero, that simply re-selects the selected
1879 window. When called interactively, @var{count} is the numeric prefix
1880 argument.
1881
1882 The optional argument @var{all-frames} has the same meaning as in
1883 @code{next-window}, like a @code{nil} @var{minibuf} argument to
1884 @code{next-window}.
1885
1886 This function does not select a window that has a non-@code{nil}
1887 @code{no-other-window} window parameter (@pxref{Window Parameters}).
1888 @end deffn
1889
1890 @defun walk-windows fun &optional minibuf all-frames
1891 This function calls the function @var{fun} once for each live window,
1892 with the window as the argument.
1893
1894 It follows the cyclic ordering of windows. The optional arguments
1895 @var{minibuf} and @var{all-frames} specify the set of windows
1896 included; these have the same arguments as in @code{next-window}. If
1897 @var{all-frames} specifies a frame, the first window walked is the
1898 first window on that frame (the one returned by
1899 @code{frame-first-window}), not necessarily the selected window.
1900
1901 If @var{fun} changes the window configuration by splitting or deleting
1902 windows, that does not alter the set of windows walked, which is
1903 determined prior to calling @var{fun} for the first time.
1904 @end defun
1905
1906 @defun one-window-p &optional no-mini all-frames
1907 This function returns @code{t} if the selected window is the only live
1908 window, and @code{nil} otherwise.
1909
1910 If the minibuffer window is active, it is normally considered (so that
1911 this function returns @code{nil}). However, if the optional argument
1912 @var{no-mini} is non-@code{nil}, the minibuffer window is ignored even
1913 if active. The optional argument @var{all-frames} has the same
1914 meaning as for @code{next-window}.
1915 @end defun
1916
1917 @cindex finding windows
1918 The following functions return a window which satisfies some
1919 criterion, without selecting it:
1920
1921 @cindex least recently used window
1922 @defun get-lru-window &optional all-frames dedicated not-selected
1923 This function returns a live window which is heuristically the least
1924 recently used. The optional argument @var{all-frames} has
1925 the same meaning as in @code{next-window}.
1926
1927 If any full-width windows are present, only those windows are
1928 considered. A minibuffer window is never a candidate. A dedicated
1929 window (@pxref{Dedicated Windows}) is never a candidate unless the
1930 optional argument @var{dedicated} is non-@code{nil}. The selected
1931 window is never returned, unless it is the only candidate. However, if
1932 the optional argument @var{not-selected} is non-@code{nil}, this
1933 function returns @code{nil} in that case.
1934 @end defun
1935
1936 @cindex most recently used window
1937 @defun get-mru-window &optional all-frames dedicated not-selected
1938 This function is like @code{get-lru-window}, but it returns the most
1939 recently used window instead. The meaning of the arguments is the
1940 same as described for @code{get-lru-window}.
1941 @end defun
1942
1943 @cindex largest window
1944 @defun get-largest-window &optional all-frames dedicated not-selected
1945 This function returns the window with the largest area (height times
1946 width). The optional argument @var{all-frames} specifies the windows to
1947 search, and has the same meaning as in @code{next-window}.
1948
1949 A minibuffer window is never a candidate. A dedicated window
1950 (@pxref{Dedicated Windows}) is never a candidate unless the optional
1951 argument @var{dedicated} is non-@code{nil}. The selected window is not
1952 a candidate if the optional argument @var{not-selected} is
1953 non-@code{nil}. If the optional argument @var{not-selected} is
1954 non-@code{nil} and the selected window is the only candidate, this
1955 function returns @code{nil}.
1956
1957 If there are two candidate windows of the same size, this function
1958 prefers the one that comes first in the cyclic ordering of windows,
1959 starting from the selected window.
1960 @end defun
1961
1962 @cindex window that satisfies a predicate
1963 @cindex conditional selection of windows
1964 @defun get-window-with-predicate predicate &optional minibuf all-frames default
1965 This function calls the function @var{predicate} for each of the
1966 windows in the cyclic order of windows in turn, passing it the window
1967 as an argument. If the predicate returns non-@code{nil} for any
1968 window, this function stops and returns that window. If no such
1969 window is found, the return value is @var{default} (which defaults to
1970 @code{nil}).
1971
1972 The optional arguments @var{minibuf} and @var{all-frames} specify the
1973 windows to search, and have the same meanings as in
1974 @code{next-window}.
1975 @end defun
1976
1977
1978 @node Buffers and Windows
1979 @section Buffers and Windows
1980 @cindex examining windows
1981 @cindex windows, controlling precisely
1982 @cindex buffers, controlled in windows
1983
1984 This section describes low-level functions for examining and setting
1985 the contents of windows. @xref{Switching Buffers}, for higher-level
1986 functions for displaying a specific buffer in a window.
1987
1988 @defun window-buffer &optional window
1989 This function returns the buffer that @var{window} is displaying. If
1990 @var{window} is omitted or @code{nil} it defaults to the selected
1991 window. If @var{window} is an internal window, this function returns
1992 @code{nil}.
1993 @end defun
1994
1995 @defun set-window-buffer window buffer-or-name &optional keep-margins
1996 This function makes @var{window} display @var{buffer-or-name}.
1997 @var{window} should be a live window; if @code{nil}, it defaults to
1998 the selected window. @var{buffer-or-name} should be a buffer, or the
1999 name of an existing buffer. This function does not change which
2000 window is selected, nor does it directly change which buffer is
2001 current (@pxref{Current Buffer}). Its return value is @code{nil}.
2002
2003 If @var{window} is @dfn{strongly dedicated} to a buffer and
2004 @var{buffer-or-name} does not specify that buffer, this function
2005 signals an error. @xref{Dedicated Windows}.
2006
2007 By default, this function resets @var{window}'s position, display
2008 margins, fringe widths, and scroll bar settings, based on the local
2009 variables in the specified buffer. However, if the optional argument
2010 @var{keep-margins} is non-@code{nil}, it leaves the display margins
2011 and fringe widths unchanged.
2012
2013 When writing an application, you should normally use the higher-level
2014 functions described in @ref{Switching Buffers}, instead of calling
2015 @code{set-window-buffer} directly.
2016
2017 This runs @code{window-scroll-functions}, followed by
2018 @code{window-configuration-change-hook}. @xref{Window Hooks}.
2019 @end defun
2020
2021 @defvar buffer-display-count
2022 This buffer-local variable records the number of times a buffer has been
2023 displayed in a window. It is incremented each time
2024 @code{set-window-buffer} is called for the buffer.
2025 @end defvar
2026
2027 @defvar buffer-display-time
2028 This buffer-local variable records the time at which a buffer was last
2029 displayed in a window. The value is @code{nil} if the buffer has
2030 never been displayed. It is updated each time
2031 @code{set-window-buffer} is called for the buffer, with the value
2032 returned by @code{current-time} (@pxref{Time of Day}).
2033 @end defvar
2034
2035 @defun get-buffer-window &optional buffer-or-name all-frames
2036 This function returns the first window displaying @var{buffer-or-name}
2037 in the cyclic ordering of windows, starting from the selected window
2038 (@pxref{Cyclic Window Ordering}). If no such window exists, the
2039 return value is @code{nil}.
2040
2041 @var{buffer-or-name} should be a buffer or the name of a buffer; if
2042 omitted or @code{nil}, it defaults to the current buffer. The
2043 optional argument @var{all-frames} specifies which windows to
2044 consider:
2045
2046 @itemize @bullet
2047 @item
2048 @code{t} means consider windows on all existing frames.
2049 @item
2050 @code{visible} means consider windows on all visible frames.
2051 @item
2052 0 means consider windows on all visible or iconified frames.
2053 @item
2054 A frame means consider windows on that frame only.
2055 @item
2056 Any other value means consider windows on the selected frame.
2057 @end itemize
2058
2059 Note that these meanings differ slightly from those of the
2060 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
2061 Ordering}). This function may be changed in a future version of Emacs
2062 to eliminate this discrepancy.
2063 @end defun
2064
2065 @defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
2066 This function returns a list of all windows currently displaying
2067 @var{buffer-or-name}. @var{buffer-or-name} should be a buffer or the
2068 name of an existing buffer. If omitted or @code{nil}, it defaults to
2069 the current buffer. If the currently selected window displays
2070 @var{buffer-or-name}, it will be the first in the list returned by
2071 this function.
2072
2073 The arguments @var{minibuf} and @var{all-frames} have the same
2074 meanings as in the function @code{next-window} (@pxref{Cyclic Window
2075 Ordering}). Note that the @var{all-frames} argument does @emph{not}
2076 behave exactly like in @code{get-buffer-window}.
2077 @end defun
2078
2079 @deffn Command replace-buffer-in-windows &optional buffer-or-name
2080 This command replaces @var{buffer-or-name} with some other buffer, in
2081 all windows displaying it. @var{buffer-or-name} should be a buffer, or
2082 the name of an existing buffer; if omitted or @code{nil}, it defaults to
2083 the current buffer.
2084
2085 The replacement buffer in each window is chosen via
2086 @code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated
2087 window displaying @var{buffer-or-name} is deleted if possible
2088 (@pxref{Dedicated Windows}). If such a window is the only window on its
2089 frame and there are other frames on the same terminal, the frame is
2090 deleted as well. If the dedicated window is the only window on the only
2091 frame on its terminal, the buffer is replaced anyway.
2092 @end deffn
2093
2094
2095 @node Switching Buffers
2096 @section Switching to a Buffer in a Window
2097 @cindex switching to a buffer
2098 @cindex displaying a buffer
2099
2100 This section describes high-level functions for switching to a specified
2101 buffer in some window. In general, ``switching to a buffer'' means to
2102 (1) show the buffer in some window, (2) make that window the selected
2103 window (and its frame the selected frame), and (3) make the buffer the
2104 current buffer.
2105
2106 Do @emph{not} use these functions to make a buffer temporarily
2107 current just so a Lisp program can access or modify it. They have
2108 side-effects, such as changing window histories (@pxref{Window
2109 History}), which will surprise the user if used that way. If you want
2110 to make a buffer current to modify it in Lisp, use
2111 @code{with-current-buffer}, @code{save-current-buffer}, or
2112 @code{set-buffer}. @xref{Current Buffer}.
2113
2114 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
2115 This command attempts to display @var{buffer-or-name} in the selected
2116 window and make it the current buffer. It is often used interactively
2117 (as the binding of @kbd{C-x b}), as well as in Lisp programs. The
2118 return value is the buffer switched to.
2119
2120 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2121 returned by @code{other-buffer} (@pxref{Buffer List}). If
2122 @var{buffer-or-name} is a string that is not the name of any existing
2123 buffer, this function creates a new buffer with that name; the new
2124 buffer's major mode is determined by the variable @code{major-mode}
2125 (@pxref{Major Modes}).
2126
2127 Normally, the specified buffer is put at the front of the buffer
2128 list---both the global buffer list and the selected frame's buffer
2129 list (@pxref{Buffer List}). However, this is not done if the
2130 optional argument @var{norecord} is non-@code{nil}.
2131
2132 Sometimes, the selected window may not be suitable for displaying the
2133 buffer. This happens if the selected window is a minibuffer window, or
2134 if the selected window is strongly dedicated to its buffer
2135 (@pxref{Dedicated Windows}). In such cases, the command normally tries
2136 to display the buffer in some other window, by invoking
2137 @code{pop-to-buffer} (see below).
2138
2139 If the optional argument @var{force-same-window} is non-@code{nil} and
2140 the selected window is not suitable for displaying the buffer, this
2141 function always signals an error when called non-interactively. In
2142 interactive use, if the selected window is a minibuffer window, this
2143 function will try to use some other window instead. If the selected
2144 window is strongly dedicated to its buffer, the option
2145 @code{switch-to-buffer-in-dedicated-window} described next can be used
2146 to proceed.
2147 @end deffn
2148
2149 @defopt switch-to-buffer-in-dedicated-window
2150 This option, if non-@code{nil}, allows @code{switch-to-buffer} to
2151 proceed when called interactively and the selected window is strongly
2152 dedicated to its buffer.
2153
2154 The following values are respected:
2155
2156 @table @code
2157 @item nil
2158 Disallows switching and signals an error as in non-interactive use.
2159
2160 @item prompt
2161 Prompts the user whether to allow switching.
2162
2163 @item pop
2164 Invokes @code{pop-to-buffer} to proceed.
2165
2166 @item t
2167 Marks the selected window as non-dedicated and proceeds.
2168 @end table
2169
2170 This option does not affect non-interactive calls of
2171 @code{switch-to-buffer}.
2172 @end defopt
2173
2174 By default, @code{switch-to-buffer} tries to preserve
2175 @code{window-point}. This behavior can be tuned using the following
2176 option.
2177
2178 @defopt switch-to-buffer-preserve-window-point
2179 If this variable is @code{nil}, @code{switch-to-buffer} displays the
2180 buffer specified by @var{buffer-or-name} at the position of that
2181 buffer's @code{point}. If this variable is @code{already-displayed}, it
2182 tries to display the buffer at its previous position in the selected
2183 window, provided the buffer is currently displayed in some other window
2184 on any visible or iconified frame. If this variable is @code{t},
2185 @code{switch-to-buffer} unconditionally tries to display the buffer at
2186 its previous position in the selected window.
2187
2188 This variable is ignored if the buffer is already displayed in the
2189 selected window or never appeared in it before, or if
2190 @code{switch-to-buffer} calls @code{pop-to-buffer} to display the
2191 buffer.
2192 @end defopt
2193
2194 The next two commands are similar to @code{switch-to-buffer}, except for
2195 the described features.
2196
2197 @deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
2198 This function displays the buffer specified by @var{buffer-or-name} in
2199 some window other than the selected window. It uses the function
2200 @code{pop-to-buffer} internally (see below).
2201
2202 If the selected window already displays the specified buffer, it
2203 continues to do so, but another window is nonetheless found to display
2204 it as well.
2205
2206 The @var{buffer-or-name} and @var{norecord} arguments have the same
2207 meanings as in @code{switch-to-buffer}.
2208 @end deffn
2209
2210 @deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
2211 This function displays the buffer specified by @var{buffer-or-name} in a
2212 new frame. It uses the function @code{pop-to-buffer} internally (see
2213 below).
2214
2215 If the specified buffer is already displayed in another window, in any
2216 frame on the current terminal, this switches to that window instead of
2217 creating a new frame. However, the selected window is never used for
2218 this.
2219
2220 The @var{buffer-or-name} and @var{norecord} arguments have the same
2221 meanings as in @code{switch-to-buffer}.
2222 @end deffn
2223
2224 The above commands use the function @code{pop-to-buffer}, which
2225 flexibly displays a buffer in some window and selects that window for
2226 editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for
2227 displaying the buffer. Hence, all the variables affecting
2228 @code{display-buffer} will affect it as well. @xref{Choosing Window},
2229 for the documentation of @code{display-buffer}.
2230
2231 @deffn Command pop-to-buffer buffer-or-name &optional action norecord
2232 This function makes @var{buffer-or-name} the current buffer and
2233 displays it in some window, preferably not the window currently
2234 selected. It then selects the displaying window. If that window is
2235 on a different graphical frame, that frame is given input focus if
2236 possible (@pxref{Input Focus}). The return value is the buffer that
2237 was switched to.
2238
2239 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
2240 returned by @code{other-buffer} (@pxref{Buffer List}). If
2241 @var{buffer-or-name} is a string that is not the name of any existing
2242 buffer, this function creates a new buffer with that name; the new
2243 buffer's major mode is determined by the variable @code{major-mode}
2244 (@pxref{Major Modes}).
2245
2246 If @var{action} is non-@code{nil}, it should be a display action to
2247 pass to @code{display-buffer} (@pxref{Choosing Window}).
2248 Alternatively, a non-@code{nil}, non-list value means to pop to a
2249 window other than the selected one---even if the buffer is already
2250 displayed in the selected window.
2251
2252 Like @code{switch-to-buffer}, this function updates the buffer list
2253 unless @var{norecord} is non-@code{nil}.
2254 @end deffn
2255
2256
2257 @node Choosing Window
2258 @section Choosing a Window for Display
2259
2260 The command @code{display-buffer} flexibly chooses a window for
2261 display, and displays a specified buffer in that window. It can be
2262 called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
2263 used as a subroutine by many functions and commands, including
2264 @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
2265 Buffers}).
2266
2267 @cindex display action
2268 @cindex action function, for @code{display-buffer}
2269 @cindex action alist, for @code{display-buffer}
2270 This command performs several complex steps to find a window to
2271 display in. These steps are described by means of @dfn{display
2272 actions}, which have the form @code{(@var{function} . @var{alist})}.
2273 Here, @var{function} is either a function or a list of functions,
2274 which we refer to as @dfn{action functions}; @var{alist} is an
2275 association list, which we refer to as an @dfn{action alist}.
2276
2277 An action function accepts two arguments: the buffer to display and
2278 an action alist. It attempts to display the buffer in some window,
2279 picking or creating a window according to its own criteria. If
2280 successful, it returns the window; otherwise, it returns @code{nil}.
2281 @xref{Display Action Functions}, for a list of predefined action
2282 functions.
2283
2284 @code{display-buffer} works by combining display actions from
2285 several sources, and calling the action functions in turn, until one
2286 of them manages to display the buffer and returns a non-@code{nil}
2287 value.
2288
2289 @deffn Command display-buffer buffer-or-name &optional action frame
2290 This command makes @var{buffer-or-name} appear in some window, without
2291 selecting the window or making the buffer current. The argument
2292 @var{buffer-or-name} must be a buffer or the name of an existing
2293 buffer. The return value is the window chosen to display the buffer.
2294
2295 The optional argument @var{action}, if non-@code{nil}, should normally
2296 be a display action (described above). @code{display-buffer} builds a
2297 list of action functions and an action alist, by consolidating display
2298 actions from the following sources (in order):
2299
2300 @itemize
2301 @item
2302 The variable @code{display-buffer-overriding-action}.
2303
2304 @item
2305 The user option @code{display-buffer-alist}.
2306
2307 @item
2308 The @var{action} argument.
2309
2310 @item
2311 The user option @code{display-buffer-base-action}.
2312
2313 @item
2314 The constant @code{display-buffer-fallback-action}.
2315 @end itemize
2316
2317 @noindent
2318 Each action function is called in turn, passing the buffer as the
2319 first argument and the combined action alist as the second argument,
2320 until one of the functions returns non-@code{nil}. The caller can
2321 pass @code{(allow-no-window . t)} as an element of the action alist to
2322 indicate its readiness to handle the case of not displaying the
2323 buffer in a window.
2324
2325 The argument @var{action} can also have a non-@code{nil}, non-list
2326 value. This has the special meaning that the buffer should be
2327 displayed in a window other than the selected one, even if the
2328 selected window is already displaying it. If called interactively
2329 with a prefix argument, @var{action} is @code{t}.
2330
2331 The optional argument @var{frame}, if non-@code{nil}, specifies which
2332 frames to check when deciding whether the buffer is already displayed.
2333 It is equivalent to adding an element @code{(reusable-frames
2334 . @var{frame})} to the action alist of @var{action}. @xref{Display
2335 Action Functions}.
2336 @end deffn
2337
2338 @defvar display-buffer-overriding-action
2339 The value of this variable should be a display action, which is
2340 treated with the highest priority by @code{display-buffer}. The
2341 default value is empty, i.e., @code{(nil . nil)}.
2342 @end defvar
2343
2344 @defopt display-buffer-alist
2345 The value of this option is an alist mapping conditions to display
2346 actions. Each condition may be either a regular expression matching a
2347 buffer name or a function that takes two arguments: a buffer name and
2348 the @var{action} argument passed to @code{display-buffer}. If the name
2349 of the buffer passed to @code{display-buffer} either matches a regular
2350 expression in this alist or the function specified by a condition
2351 returns non-@code{nil}, then @code{display-buffer} uses the
2352 corresponding display action to display the buffer.
2353 @end defopt
2354
2355 @defopt display-buffer-base-action
2356 The value of this option should be a display action. This option can
2357 be used to define a standard display action for calls to
2358 @code{display-buffer}.
2359 @end defopt
2360
2361 @defvr Constant display-buffer-fallback-action
2362 This display action specifies the fallback behavior for
2363 @code{display-buffer} if no other display actions are given.
2364 @end defvr
2365
2366
2367 @node Display Action Functions
2368 @section Action Functions for @code{display-buffer}
2369
2370 The following basic action functions are defined in Emacs. Each of
2371 these functions takes two arguments: @var{buffer}, the buffer to
2372 display, and @var{alist}, an action alist. Each action function
2373 returns the window if it succeeds, and @code{nil} if it fails.
2374
2375 @defun display-buffer-same-window buffer alist
2376 This function tries to display @var{buffer} in the selected window.
2377 It fails if the selected window is a minibuffer window or is dedicated
2378 to another buffer (@pxref{Dedicated Windows}). It also fails if
2379 @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
2380 @end defun
2381
2382 @defun display-buffer-reuse-window buffer alist
2383 This function tries to display @var{buffer} by finding a window
2384 that is already displaying it.
2385
2386 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2387 the selected window is not eligible for reuse. If @var{alist}
2388 contains a @code{reusable-frames} entry, its value determines which
2389 frames to search for a reusable window:
2390
2391 @itemize @bullet
2392 @item
2393 @code{nil} means consider windows on the selected frame.
2394 (Actually, the last non-minibuffer frame.)
2395 @item
2396 @code{t} means consider windows on all frames.
2397 @item
2398 @code{visible} means consider windows on all visible frames.
2399 @item
2400 0 means consider windows on all visible or iconified frames.
2401 @item
2402 A frame means consider windows on that frame only.
2403 @end itemize
2404
2405 Note that these meanings differ slightly from those of the
2406 @var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
2407 Ordering}).
2408
2409 If @var{alist} contains no @code{reusable-frames} entry, this function
2410 normally searches just the selected frame; however, if the variable
2411 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
2412 current terminal. @xref{Choosing Window Options}.
2413
2414 If this function chooses a window on another frame, it makes that frame
2415 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
2416 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
2417 @end defun
2418
2419 @defun display-buffer-reuse-mode-window buffer alist
2420 This function tries to display @var{buffer} by finding a window
2421 that is displaying a buffer in a given mode.
2422
2423 If @var{alist} contains a @code{mode} entry, its value is a major mode
2424 (a symbol) or a list of major modes. If @var{alist} contains no
2425 @code{mode} entry, the current major mode of @var{buffer} is used. A
2426 window is a candidate if it displays a buffer that derives from one of
2427 the given modes.
2428
2429 The behaviour is also controlled by entries for
2430 @code{inhibit-same-window}, @code{reusable-frames} and
2431 @code{inhibit-switch-frame} as is done in the function
2432 @code{display-buffer-reuse-window}.
2433
2434 @end defun
2435
2436 @defun display-buffer-pop-up-frame buffer alist
2437 This function creates a new frame, and displays the buffer in that
2438 frame's window. It actually performs the frame creation by calling
2439 the function specified in @code{pop-up-frame-function}
2440 (@pxref{Choosing Window Options}). If @var{alist} contains a
2441 @code{pop-up-frame-parameters} entry, the associated value
2442 is added to the newly created frame's parameters.
2443 @end defun
2444
2445 @defun display-buffer-use-some-frame buffer alist
2446 This function tries to display @var{buffer} by trying to find a
2447 frame that meets a predicate (by default any frame other than the
2448 current frame).
2449
2450 If this function chooses a window on another frame, it makes that frame
2451 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
2452 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
2453
2454 If @var{alist} has a non-@code{nil} @code{frame-predicate} entry, its
2455 value is a function taking one argument (a frame), returning
2456 non-@code{nil} if the frame is a candidate; this function replaces the
2457 default predicate.
2458
2459 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
2460 the selected window is used; thus if the selected frame has a single
2461 window, it is not used.
2462 @end defun
2463
2464 @defun display-buffer-pop-up-window buffer alist
2465 This function tries to display @var{buffer} by splitting the largest
2466 or least recently-used window (typically one on the selected frame).
2467 It actually performs the split by calling the function specified in
2468 @code{split-window-preferred-function} (@pxref{Choosing Window
2469 Options}).
2470
2471 The size of the new window can be adjusted by supplying
2472 @code{window-height} and @code{window-width} entries in @var{alist}. To
2473 adjust the window's height, use an entry whose @sc{car} is
2474 @code{window-height} and whose @sc{cdr} is one of:
2475
2476 @itemize @bullet
2477 @item
2478 @code{nil} means to leave the height of the new window alone.
2479
2480 @item
2481 A number specifies the desired height of the new window. An integer
2482 specifies the number of lines of the window. A floating-point
2483 number gives the fraction of the window's height with respect to the
2484 height of the frame's root window.
2485
2486 @item
2487 If the @sc{cdr} specifies a function, that function is called with one
2488 argument: the new window. The function is supposed to adjust the
2489 height of the window; its return value is ignored. Suitable functions
2490 are @code{shrink-window-if-larger-than-buffer} and
2491 @code{fit-window-to-buffer}, see @ref{Resizing Windows}.
2492 @end itemize
2493
2494 To adjust the window's width, use an entry whose @sc{car} is
2495 @code{window-width} and whose @sc{cdr} is one of:
2496
2497 @itemize @bullet
2498 @item
2499 @code{nil} means to leave the width of the new window alone.
2500
2501 @item
2502 A number specifies the desired width of the new window. An integer
2503 specifies the number of columns of the window. A floating-point
2504 number gives the fraction of the window's width with respect to the
2505 width of the frame's root window.
2506
2507 @item
2508 If the @sc{cdr} specifies a function, that function is called with one
2509 argument: the new window. The function is supposed to adjust the width
2510 of the window; its return value is ignored.
2511 @end itemize
2512
2513 If @var{alist} contains a @code{preserve-size} entry, Emacs will try to
2514 preserve the size of the new window during future resize operations
2515 (@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a
2516 cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width
2517 of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve
2518 the height of the window.
2519
2520 This function can fail if no window splitting can be performed for some
2521 reason (e.g., if the selected frame has an @code{unsplittable} frame
2522 parameter; @pxref{Buffer Parameters}).
2523 @end defun
2524
2525 @defun display-buffer-below-selected buffer alist
2526 This function tries to display @var{buffer} in a window below the
2527 selected window. This means to either split the selected window or use
2528 the window below the selected one. If it does create a new window, it
2529 will also adjust its size provided @var{alist} contains a suitable
2530 @code{window-height} or @code{window-width} entry, see above.
2531 @end defun
2532
2533 @defun display-buffer-in-previous-window buffer alist
2534 This function tries to display @var{buffer} in a window previously
2535 showing it. If @var{alist} has a non-@code{nil}
2536 @code{inhibit-same-window} entry, the selected window is not eligible
2537 for reuse. If @var{alist} contains a @code{reusable-frames} entry, its
2538 value determines which frames to search for a suitable window as with
2539 @code{display-buffer-reuse-window}.
2540
2541 If @var{alist} has a @code{previous-window} entry, the window
2542 specified by that entry will override any other window found by the
2543 methods above, even if that window never showed @var{buffer} before.
2544 @end defun
2545
2546 @defun display-buffer-at-bottom buffer alist
2547 This function tries to display @var{buffer} in a window at the bottom
2548 of the selected frame.
2549
2550 This either splits the window at the bottom of the frame or the
2551 frame's root window, or reuses an existing window at the bottom of the
2552 selected frame.
2553 @end defun
2554
2555 @defun display-buffer-use-some-window buffer alist
2556 This function tries to display @var{buffer} by choosing an existing
2557 window and displaying the buffer in that window. It can fail if all
2558 windows are dedicated to another buffer (@pxref{Dedicated Windows}).
2559 @end defun
2560
2561 @defun display-buffer-no-window buffer alist
2562 If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then
2563 this function does not display @code{buffer}. This allows you to
2564 override the default action and avoid displaying the buffer. It is
2565 assumed that when the caller specifies a non-@code{nil}
2566 @code{allow-no-window} value it can handle a @code{nil} value returned
2567 from @code{display-buffer} in this case.
2568 @end defun
2569
2570 To illustrate the use of action functions, consider the following
2571 example.
2572
2573 @example
2574 @group
2575 (display-buffer
2576 (get-buffer-create "*foo*")
2577 '((display-buffer-reuse-window
2578 display-buffer-pop-up-window
2579 display-buffer-pop-up-frame)
2580 (reusable-frames . 0)
2581 (window-height . 10) (window-width . 40)))
2582 @end group
2583 @end example
2584
2585 @noindent
2586 Evaluating the form above will cause @code{display-buffer} to proceed as
2587 follows: If a buffer called *foo* already appears on a visible or
2588 iconified frame, it will reuse its window. Otherwise, it will try to
2589 pop up a new window or, if that is impossible, a new frame and show the
2590 buffer there. If all these steps fail, it will proceed using whatever
2591 @code{display-buffer-base-action} and
2592 @code{display-buffer-fallback-action} prescribe.
2593
2594 Furthermore, @code{display-buffer} will try to adjust a reused window
2595 (provided *foo* was put by @code{display-buffer} there before) or a
2596 popped-up window as follows: If the window is part of a vertical
2597 combination, it will set its height to ten lines. Note that if, instead
2598 of the number 10, we specified the function
2599 @code{fit-window-to-buffer}, @code{display-buffer} would come up with a
2600 one-line window to fit the empty buffer. If the window is part of a
2601 horizontal combination, it sets its width to 40 columns. Whether a new
2602 window is vertically or horizontally combined depends on the shape of
2603 the window split and the values of
2604 @code{split-window-preferred-function}, @code{split-height-threshold}
2605 and @code{split-width-threshold} (@pxref{Choosing Window Options}).
2606
2607 Now suppose we combine this call with a preexisting setup for
2608 @code{display-buffer-alist} as follows.
2609
2610 @example
2611 @group
2612 (let ((display-buffer-alist
2613 (cons
2614 '("\\*foo\\*"
2615 (display-buffer-reuse-window display-buffer-below-selected)
2616 (reusable-frames)
2617 (window-height . 5))
2618 display-buffer-alist)))
2619 (display-buffer
2620 (get-buffer-create "*foo*")
2621 '((display-buffer-reuse-window
2622 display-buffer-pop-up-window
2623 display-buffer-pop-up-frame)
2624 (reusable-frames . 0)
2625 (window-height . 10) (window-width . 40))))
2626 @end group
2627 @end example
2628
2629 @noindent
2630 This form will have @code{display-buffer} first try reusing a window
2631 that shows *foo* on the selected frame. If there's no such window, it
2632 will try to split the selected window or, if that is impossible, use the
2633 window below the selected window.
2634
2635 If there's no window below the selected one, or the window below the
2636 selected one is dedicated to its buffer, @code{display-buffer} will
2637 proceed as described in the previous example. Note, however, that when
2638 it tries to adjust the height of any reused or popped-up window, it will
2639 in any case try to set its number of lines to 5 since that value
2640 overrides the corresponding specification in the @var{action} argument
2641 of @code{display-buffer}.
2642
2643
2644 @node Choosing Window Options
2645 @section Additional Options for Displaying Buffers
2646
2647 The behavior of the standard display actions of @code{display-buffer}
2648 (@pxref{Choosing Window}) can be modified by a variety of user
2649 options.
2650
2651 @defopt pop-up-windows
2652 If the value of this variable is non-@code{nil}, @code{display-buffer}
2653 is allowed to split an existing window to make a new window for
2654 displaying in. This is the default.
2655
2656 This variable is provided mainly for backward compatibility. It is
2657 obeyed by @code{display-buffer} via a special mechanism in
2658 @code{display-buffer-fallback-action}, which only calls the action
2659 function @code{display-buffer-pop-up-window} (@pxref{Display Action
2660 Functions}) when the value is @code{nil}. It is not consulted by
2661 @code{display-buffer-pop-up-window} itself, which the user may specify
2662 directly in @code{display-buffer-alist} etc.
2663 @end defopt
2664
2665 @defopt split-window-preferred-function
2666 This variable specifies a function for splitting a window, in order to
2667 make a new window for displaying a buffer. It is used by the
2668 @code{display-buffer-pop-up-window} action function to actually split
2669 the window (@pxref{Display Action Functions}).
2670
2671 The default value is @code{split-window-sensibly}, which is documented
2672 below. The value must be a function that takes one argument, a window,
2673 and return either a new window (which will be used to display the
2674 desired buffer) or @code{nil} (which means the splitting failed).
2675 @end defopt
2676
2677 @defun split-window-sensibly &optional window
2678 This function tries to split @var{window}, and return the newly created
2679 window. If @var{window} cannot be split, it returns @code{nil}. If
2680 @var{window} is omitted or @code{nil}, it defaults to the selected
2681 window.
2682
2683 This function obeys the usual rules that determine when a window may
2684 be split (@pxref{Splitting Windows}). It first tries to split by
2685 placing the new window below, subject to the restriction imposed by
2686 @code{split-height-threshold} (see below), in addition to any other
2687 restrictions. If that fails, it tries to split by placing the new
2688 window to the right, subject to @code{split-width-threshold} (see
2689 below). If that fails, and the window is the only window on its
2690 frame, this function again tries to split and place the new window
2691 below, disregarding @code{split-height-threshold}. If this fails as
2692 well, this function gives up and returns @code{nil}.
2693 @end defun
2694
2695 @defopt split-height-threshold
2696 This variable, used by @code{split-window-sensibly}, specifies whether
2697 to split the window placing the new window below. If it is an
2698 integer, that means to split only if the original window has at least
2699 that many lines. If it is @code{nil}, that means not to split this
2700 way.
2701 @end defopt
2702
2703 @defopt split-width-threshold
2704 This variable, used by @code{split-window-sensibly}, specifies whether
2705 to split the window placing the new window to the right. If the value
2706 is an integer, that means to split only if the original window has at
2707 least that many columns. If the value is @code{nil}, that means not
2708 to split this way.
2709 @end defopt
2710
2711 @defopt even-window-sizes
2712 This variable, if non-@code{nil}, causes @code{display-buffer} to even
2713 window sizes whenever it reuses an existing window and that window is
2714 adjacent to the selected one.
2715
2716 If its value is @code{width-only}, sizes are evened only if the reused
2717 window is on the left or right of the selected one and the selected
2718 window is wider than the reused one. If its value is @code{height-only}
2719 sizes are evened only if the reused window is above or beneath the
2720 selected window and the selected window is higher than the reused one.
2721 Any other non-@code{nil} value means to even sizes in any of these cases
2722 provided the selected window is larger than the reused one in the sense
2723 of their combination.
2724 @end defopt
2725
2726 @defopt pop-up-frames
2727 If the value of this variable is non-@code{nil}, that means
2728 @code{display-buffer} may display buffers by making new frames. The
2729 default is @code{nil}.
2730
2731 A non-@code{nil} value also means that when @code{display-buffer} is
2732 looking for a window already displaying @var{buffer-or-name}, it can
2733 search any visible or iconified frame, not just the selected frame.
2734
2735 This variable is provided mainly for backward compatibility. It is
2736 obeyed by @code{display-buffer} via a special mechanism in
2737 @code{display-buffer-fallback-action}, which calls the action function
2738 @code{display-buffer-pop-up-frame} (@pxref{Display Action Functions})
2739 if the value is non-@code{nil}. (This is done before attempting to
2740 split a window.) This variable is not consulted by
2741 @code{display-buffer-pop-up-frame} itself, which the user may specify
2742 directly in @code{display-buffer-alist} etc.
2743 @end defopt
2744
2745 @defopt pop-up-frame-function
2746 This variable specifies a function for creating a new frame, in order
2747 to make a new window for displaying a buffer. It is used by the
2748 @code{display-buffer-pop-up-frame} action function (@pxref{Display
2749 Action Functions}).
2750
2751 The value should be a function that takes no arguments and returns a
2752 frame, or @code{nil} if no frame could be created. The default value
2753 is a function that creates a frame using the parameters specified by
2754 @code{pop-up-frame-alist} (see below).
2755 @end defopt
2756
2757 @defopt pop-up-frame-alist
2758 This variable holds an alist of frame parameters (@pxref{Frame
2759 Parameters}), which is used by the default function in
2760 @code{pop-up-frame-function} to make a new frame. The default is
2761 @code{nil}.
2762 @end defopt
2763
2764 @defopt same-window-buffer-names
2765 A list of buffer names for buffers that should be displayed in the
2766 selected window. If a buffer's name is in this list,
2767 @code{display-buffer} handles the buffer by showing it in the selected
2768 window.
2769 @end defopt
2770
2771 @defopt same-window-regexps
2772 A list of regular expressions that specify buffers that should be
2773 displayed in the selected window. If the buffer's name matches any of
2774 the regular expressions in this list, @code{display-buffer} handles the
2775 buffer by showing it in the selected window.
2776 @end defopt
2777
2778 @defun same-window-p buffer-name
2779 This function returns @code{t} if displaying a buffer
2780 named @var{buffer-name} with @code{display-buffer} would
2781 put it in the selected window.
2782 @end defun
2783
2784 @node Window History
2785 @section Window History
2786 @cindex window history
2787
2788 Each window remembers in a list the buffers it has previously displayed,
2789 and the order in which these buffers were removed from it. This history
2790 is used, for example, by @code{replace-buffer-in-windows}
2791 (@pxref{Buffers and Windows}). The list is automatically maintained by
2792 Emacs, but you can use the following functions to explicitly inspect or
2793 alter it:
2794
2795 @defun window-prev-buffers &optional window
2796 This function returns a list specifying the previous contents of
2797 @var{window}. The optional argument @var{window} should be a live
2798 window and defaults to the selected one.
2799
2800 Each list element has the form @code{(@var{buffer} @var{window-start}
2801 @var{window-pos})}, where @var{buffer} is a buffer previously shown in
2802 the window, @var{window-start} is the window start position
2803 (@pxref{Window Start and End}) when that buffer was last shown, and
2804 @var{window-pos} is the point position (@pxref{Window Point}) when
2805 that buffer was last shown in @var{window}.
2806
2807 The list is ordered so that earlier elements correspond to more
2808 recently-shown buffers, and the first element usually corresponds to the
2809 buffer most recently removed from the window.
2810 @end defun
2811
2812 @defun set-window-prev-buffers window prev-buffers
2813 This function sets @var{window}'s previous buffers to the value of
2814 @var{prev-buffers}. The argument @var{window} must be a live window
2815 and defaults to the selected one. The argument @var{prev-buffers}
2816 should be a list of the same form as that returned by
2817 @code{window-prev-buffers}.
2818 @end defun
2819
2820 In addition, each buffer maintains a list of @dfn{next buffers}, which
2821 is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
2822 below). This list is mainly used by @code{switch-to-prev-buffer} and
2823 @code{switch-to-next-buffer} for choosing buffers to switch to.
2824
2825 @defun window-next-buffers &optional window
2826 This function returns the list of buffers recently re-shown in
2827 @var{window} via @code{switch-to-prev-buffer}. The @var{window}
2828 argument must denote a live window or @code{nil} (meaning the selected
2829 window).
2830 @end defun
2831
2832 @defun set-window-next-buffers window next-buffers
2833 This function sets the next buffer list of @var{window} to
2834 @var{next-buffers}. The @var{window} argument should be a live window
2835 or @code{nil} (meaning the selected window). The argument
2836 @var{next-buffers} should be a list of buffers.
2837 @end defun
2838
2839 The following commands can be used to cycle through the global buffer
2840 list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
2841 they cycle according to the specified window's history list, rather
2842 than the global buffer list. In addition, they restore
2843 window-specific window start and point positions, and may show a
2844 buffer even if it is already shown in another window. The
2845 @code{switch-to-prev-buffer} command, in particular, is used by
2846 @code{replace-buffer-in-windows}, @code{bury-buffer} and
2847 @code{quit-window} to find a replacement buffer for a window.
2848
2849 @deffn Command switch-to-prev-buffer &optional window bury-or-kill
2850 This command displays the previous buffer in @var{window}. The
2851 argument @var{window} should be a live window or @code{nil} (meaning
2852 the selected window). If the optional argument @var{bury-or-kill} is
2853 non-@code{nil}, this means that the buffer currently shown in
2854 @var{window} is about to be buried or killed and consequently should
2855 not be switched to in future invocations of this command.
2856
2857 The previous buffer is usually the buffer shown before the buffer
2858 currently shown in @var{window}. However, a buffer that has been buried
2859 or killed, or has been already shown by a recent invocation of
2860 @code{switch-to-prev-buffer}, does not qualify as previous buffer.
2861
2862 If repeated invocations of this command have already shown all buffers
2863 previously shown in @var{window}, further invocations will show buffers
2864 from the buffer list of the frame @var{window} appears on (@pxref{Buffer
2865 List}), trying to skip buffers that are already shown in another window
2866 on that frame.
2867 @end deffn
2868
2869 @deffn Command switch-to-next-buffer &optional window
2870 This command switches to the next buffer in @var{window}, thus undoing
2871 the effect of the last @code{switch-to-prev-buffer} command in
2872 @var{window}. The argument @var{window} must be a live window and
2873 defaults to the selected one.
2874
2875 If there is no recent invocation of @code{switch-to-prev-buffer} that
2876 can be undone, this function tries to show a buffer from the buffer list
2877 of the frame @var{window} appears on (@pxref{Buffer List}).
2878 @end deffn
2879
2880 By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
2881 can switch to a buffer that is already shown in another window on the
2882 same frame. The following option can be used to override this behavior.
2883
2884 @defopt switch-to-visible-buffer
2885 If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
2886 @code{switch-to-next-buffer} may switch to a buffer that is already
2887 visible on the same frame, provided the buffer was shown in the
2888 relevant window before. If it is @code{nil},
2889 @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always
2890 try to avoid switching to a buffer that is already visible in another
2891 window on the same frame. The default is @code{t}.
2892 @end defopt
2893
2894
2895 @node Dedicated Windows
2896 @section Dedicated Windows
2897 @cindex dedicated window
2898
2899 Functions for displaying a buffer can be told to not use specific
2900 windows by marking these windows as @dfn{dedicated} to their buffers.
2901 @code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
2902 window for displaying another buffer in it. @code{get-lru-window} and
2903 @code{get-largest-window} (@pxref{Cyclic Window Ordering}) do not
2904 consider dedicated windows as candidates when their @var{dedicated}
2905 argument is non-@code{nil}. The behavior of @code{set-window-buffer}
2906 (@pxref{Buffers and Windows}) with respect to dedicated windows is
2907 slightly different, see below.
2908
2909 Functions supposed to remove a buffer from a window or a window from
2910 a frame can behave specially when a window they operate on is dedicated.
2911 We will distinguish three basic cases, namely where (1) the window is
2912 not the only window on its frame, (2) the window is the only window on
2913 its frame but there are other frames on the same terminal left, and (3)
2914 the window is the only window on the only frame on the same terminal.
2915
2916 In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
2917 handles case (2) by deleting the associated frame and case (3) by
2918 showing another buffer in that frame's only window. The function
2919 @code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
2920 called when a buffer gets killed, deletes the window in case (1) and
2921 behaves like @code{delete-windows-on} otherwise.
2922 @c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)?
2923
2924 When @code{bury-buffer} (@pxref{Buffer List}) operates on the
2925 selected window (which shows the buffer that shall be buried), it
2926 handles case (2) by calling @code{frame-auto-hide-function}
2927 (@pxref{Quitting Windows}) to deal with the selected frame. The other
2928 two cases are handled as with @code{replace-buffer-in-windows}.
2929
2930 @defun window-dedicated-p &optional window
2931 This function returns non-@code{nil} if @var{window} is dedicated to its
2932 buffer and @code{nil} otherwise. More precisely, the return value is
2933 the value assigned by the last call of @code{set-window-dedicated-p} for
2934 @var{window}, or @code{nil} if that function was never called with
2935 @var{window} as its argument. The default for @var{window} is the
2936 selected window.
2937 @end defun
2938
2939 @defun set-window-dedicated-p window flag
2940 This function marks @var{window} as dedicated to its buffer if
2941 @var{flag} is non-@code{nil}, and non-dedicated otherwise.
2942
2943 As a special case, if @var{flag} is @code{t}, @var{window} becomes
2944 @dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
2945 signals an error when the window it acts upon is strongly dedicated to
2946 its buffer and does not already display the buffer it is asked to
2947 display. Other functions do not treat @code{t} differently from any
2948 non-@code{nil} value.
2949 @end defun
2950
2951
2952 @node Quitting Windows
2953 @section Quitting Windows
2954
2955 When you want to get rid of a window used for displaying a buffer, you
2956 can call @code{delete-window} or @code{delete-windows-on}
2957 (@pxref{Deleting Windows}) to remove that window from its frame. If the
2958 buffer is shown on a separate frame, you might want to call
2959 @code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
2960 hand, a window has been reused for displaying the buffer, you might
2961 prefer showing the buffer previously shown in that window, by calling the
2962 function @code{switch-to-prev-buffer} (@pxref{Window History}).
2963 Finally, you might want to either bury (@pxref{Buffer List}) or kill
2964 (@pxref{Killing Buffers}) the window's buffer.
2965
2966 The following command uses information on how the window for
2967 displaying the buffer was obtained in the first place, thus attempting
2968 to automate the above decisions for you.
2969
2970 @deffn Command quit-window &optional kill window
2971 This command quits @var{window} and buries its buffer. The argument
2972 @var{window} must be a live window and defaults to the selected one.
2973 With prefix argument @var{kill} non-@code{nil}, it kills the buffer
2974 instead of burying it. It calls the function @code{quit-restore-window}
2975 described next to deal with the window and its buffer.
2976 @end deffn
2977
2978 @defun quit-restore-window &optional window bury-or-kill
2979 This function tries to restore the state of @var{window} that existed
2980 before its buffer was displayed in it. The optional argument
2981 @var{window} must be a live window and defaults to the selected one.
2982
2983 If @var{window} was created specially for displaying its buffer, this
2984 function deletes @var{window} provided its frame contains at least one
2985 other live window. If @var{window} is the only window on its frame and
2986 there are other frames on the frame's terminal, the value of the
2987 optional argument @var{bury-or-kill} determines how to proceed with the
2988 window. If @var{bury-or-kill} equals @code{kill}, the frame is deleted
2989 unconditionally. Otherwise, the fate of the frame is determined by
2990 calling @code{frame-auto-hide-function} (see below) with that frame as
2991 sole argument.
2992
2993 Otherwise, this function tries to redisplay the buffer previously shown
2994 in @var{window}. It also tries to restore the window start
2995 (@pxref{Window Start and End}) and point (@pxref{Window Point})
2996 positions of the previously shown buffer. If, in addition,
2997 @var{window}'s buffer was temporarily resized, this function will also
2998 try to restore the original height of @var{window}.
2999
3000 The cases described so far require that the buffer shown in @var{window}
3001 is still the buffer displayed by the last buffer display function for
3002 this window. If another buffer has been shown in the meantime, or the
3003 buffer previously shown no longer exists, this function calls
3004 @code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
3005 buffer instead.
3006
3007 The optional argument @var{bury-or-kill} specifies how to deal with
3008 @var{window}'s buffer. The following values are handled:
3009
3010 @table @code
3011 @item nil
3012 This means to not deal with the buffer in any particular way. As a
3013 consequence, if @var{window} is not deleted, invoking
3014 @code{switch-to-prev-buffer} will usually show the buffer again.
3015
3016 @item append
3017 This means that if @var{window} is not deleted, its buffer is moved to
3018 the end of @var{window}'s list of previous buffers, so it's less likely
3019 that a future invocation of @code{switch-to-prev-buffer} will switch to
3020 it. Also, it moves the buffer to the end of the frame's buffer list.
3021
3022 @item bury
3023 This means that if @var{window} is not deleted, its buffer is removed
3024 from @var{window}'s list of previous buffers. Also, it moves the buffer
3025 to the end of the frame's buffer list. This value provides the most
3026 reliable remedy to not have @code{switch-to-prev-buffer} switch to this
3027 buffer again without killing the buffer.
3028
3029 @item kill
3030 This means to kill @var{window}'s buffer.
3031 @end table
3032
3033 @code{quit-restore-window} bases its decisions on information stored in
3034 @var{window}'s @code{quit-restore} window parameter (@pxref{Window
3035 Parameters}), and resets that parameter to @code{nil} after it's done.
3036 @end defun
3037
3038 The following option specifies how to deal with a frame containing just
3039 one window that should be either quit, or whose buffer should be buried.
3040
3041 @defopt frame-auto-hide-function
3042 The function specified by this option is called to automatically hide
3043 frames. This function is called with one argument---a frame.
3044
3045 The function specified here is called by @code{bury-buffer}
3046 (@pxref{Buffer List}) when the selected window is dedicated and shows
3047 the buffer to bury. It is also called by @code{quit-restore-window}
3048 (see above) when the frame of the window to quit has been specially
3049 created for displaying that window's buffer and the buffer is not
3050 killed.
3051
3052 The default is to call @code{iconify-frame} (@pxref{Visibility of
3053 Frames}). Alternatively, you may specify either @code{delete-frame}
3054 (@pxref{Deleting Frames}) to remove the frame from its display,
3055 @code{ignore} to leave the frame unchanged, or any other function that
3056 can take a frame as its sole argument.
3057
3058 Note that the function specified by this option is called only if the
3059 specified frame contains just one live window and there is at least one
3060 other frame on the same terminal.
3061 @end defopt
3062
3063
3064 @node Window Point
3065 @section Windows and Point
3066 @cindex window position
3067 @cindex window point
3068 @cindex position in window
3069 @cindex point in window
3070
3071 Each window has its own value of point (@pxref{Point}), independent of
3072 the value of point in other windows displaying the same buffer. This
3073 makes it useful to have multiple windows showing one buffer.
3074
3075 @itemize @bullet
3076 @item
3077 The window point is established when a window is first created; it is
3078 initialized from the buffer's point, or from the window point of another
3079 window opened on the buffer if such a window exists.
3080
3081 @item
3082 Selecting a window sets the value of point in its buffer from the
3083 window's value of point. Conversely, deselecting a window sets the
3084 window's value of point from that of the buffer. Thus, when you switch
3085 between windows that display a given buffer, the point value for the
3086 selected window is in effect in the buffer, while the point values for
3087 the other windows are stored in those windows.
3088
3089 @item
3090 As long as the selected window displays the current buffer, the window's
3091 point and the buffer's point always move together; they remain equal.
3092 @end itemize
3093
3094 @cindex cursor
3095 As far as the user is concerned, point is where the cursor is, and
3096 when the user switches to another buffer, the cursor jumps to the
3097 position of point in that buffer.
3098
3099 @defun window-point &optional window
3100 This function returns the current position of point in @var{window}.
3101 For a nonselected window, this is the value point would have (in that
3102 window's buffer) if that window were selected. The default for
3103 @var{window} is the selected window.
3104
3105 When @var{window} is the selected window, the value returned is the
3106 value of point in that window's buffer. Strictly speaking, it would be
3107 more correct to return the top-level value of point, outside of any
3108 @code{save-excursion} forms. But that value is hard to find.
3109 @end defun
3110
3111 @defun set-window-point window position
3112 This function positions point in @var{window} at position
3113 @var{position} in @var{window}'s buffer. It returns @var{position}.
3114
3115 If @var{window} is selected, this simply does @code{goto-char} in
3116 @var{window}'s buffer.
3117 @end defun
3118
3119 @defvar window-point-insertion-type
3120 This variable specifies the marker insertion type (@pxref{Marker
3121 Insertion Types}) of @code{window-point}. The default is @code{nil},
3122 so @code{window-point} will stay behind text inserted there.
3123 @end defvar
3124
3125 @node Window Start and End
3126 @section The Window Start and End Positions
3127 @cindex window start position
3128 @cindex display-start position
3129
3130 Each window maintains a marker used to keep track of a buffer position
3131 that specifies where in the buffer display should start. This position
3132 is called the @dfn{display-start} position of the window (or just the
3133 @dfn{start}). The character after this position is the one that appears
3134 at the upper left corner of the window. It is usually, but not
3135 inevitably, at the beginning of a text line.
3136
3137 After switching windows or buffers, and in some other cases, if the
3138 window start is in the middle of a line, Emacs adjusts the window
3139 start to the start of a line. This prevents certain operations from
3140 leaving the window start at a meaningless point within a line. This
3141 feature may interfere with testing some Lisp code by executing it
3142 using the commands of Lisp mode, because they trigger this
3143 readjustment. To test such code, put it into a command and bind the
3144 command to a key.
3145
3146 @defun window-start &optional window
3147 @cindex window top line
3148 This function returns the display-start position of window
3149 @var{window}. If @var{window} is @code{nil}, the selected window is
3150 used.
3151
3152 When you create a window, or display a different buffer in it, the
3153 display-start position is set to a display-start position recently used
3154 for the same buffer, or to @code{point-min} if the buffer doesn't have
3155 any.
3156
3157 Redisplay updates the window-start position (if you have not specified
3158 it explicitly since the previous redisplay)---to make sure point appears
3159 on the screen. Nothing except redisplay automatically changes the
3160 window-start position; if you move point, do not expect the window-start
3161 position to change in response until after the next redisplay.
3162 @end defun
3163
3164 @defun window-group-start &optional window
3165 @vindex window-group-start-function
3166 This function is like @code{window-start}, except that when
3167 @var{window} is a part of a group of windows (@pxref{Window Group}),
3168 @code{window-group-start} returns the start position of the entire
3169 group. This condition holds when the buffer local variable
3170 @code{window-group-start-function} is set to a function. In this
3171 case, @code{window-group-start} calls the function with the single
3172 argument @var{window}, then returns its result.
3173 @end defun
3174
3175 @cindex window end position
3176 @defun window-end &optional window update
3177 This function returns the position where display of its buffer ends in
3178 @var{window}. The default for @var{window} is the selected window.
3179
3180 Simply changing the buffer text or moving point does not update the
3181 value that @code{window-end} returns. The value is updated only when
3182 Emacs redisplays and redisplay completes without being preempted.
3183
3184 If the last redisplay of @var{window} was preempted, and did not finish,
3185 Emacs does not know the position of the end of display in that window.
3186 In that case, this function returns @code{nil}.
3187
3188 If @var{update} is non-@code{nil}, @code{window-end} always returns an
3189 up-to-date value for where display ends, based on the current
3190 @code{window-start} value. If a previously saved value of that position
3191 is still valid, @code{window-end} returns that value; otherwise it
3192 computes the correct value by scanning the buffer text.
3193
3194 Even if @var{update} is non-@code{nil}, @code{window-end} does not
3195 attempt to scroll the display if point has moved off the screen, the
3196 way real redisplay would do. It does not alter the
3197 @code{window-start} value. In effect, it reports where the displayed
3198 text will end if scrolling is not required.
3199 @end defun
3200
3201 @vindex window-group-end-function
3202 @defun window-group-end &optional window update
3203 This function is like @code{window-end}, except that when @var{window}
3204 is a part of a group of windows (@pxref{Window Group}),
3205 @code{window-group-end} returns the end position of the entire group.
3206 This condition holds when the buffer local variable
3207 @code{window-group-end-function} is set to a function. In this case,
3208 @code{window-group-end} calls the function with the two arguments
3209 @var{window} and @var{update}, then returns its result. The argument
3210 @var{update} has the same meaning as in @code{window-end}.
3211 @end defun
3212
3213 @defun set-window-start window position &optional noforce
3214 This function sets the display-start position of @var{window} to
3215 @var{position} in @var{window}'s buffer. It returns @var{position}.
3216
3217 The display routines insist that the position of point be visible when a
3218 buffer is displayed. Normally, they change the display-start position
3219 (that is, scroll the window) whenever necessary to make point visible.
3220 However, if you specify the start position with this function using
3221 @code{nil} for @var{noforce}, it means you want display to start at
3222 @var{position} even if that would put the location of point off the
3223 screen. If this does place point off screen, the display routines move
3224 point to the left margin on the middle line in the window.
3225
3226 For example, if point @w{is 1} and you set the start of the window
3227 @w{to 37}, the start of the next line, point will be above the top
3228 of the window. The display routines will automatically move point if
3229 it is still 1 when redisplay occurs. Here is an example:
3230
3231 @example
3232 @group
3233 ;; @r{Here is what @samp{foo} looks like before executing}
3234 ;; @r{the @code{set-window-start} expression.}
3235 @end group
3236
3237 @group
3238 ---------- Buffer: foo ----------
3239 @point{}This is the contents of buffer foo.
3240 2
3241 3
3242 4
3243 5
3244 6
3245 ---------- Buffer: foo ----------
3246 @end group
3247
3248 @group
3249 (set-window-start
3250 (selected-window)
3251 (save-excursion
3252 (goto-char 1)
3253 (forward-line 1)
3254 (point)))
3255 @result{} 37
3256 @end group
3257
3258 @group
3259 ;; @r{Here is what @samp{foo} looks like after executing}
3260 ;; @r{the @code{set-window-start} expression.}
3261 ---------- Buffer: foo ----------
3262 2
3263 3
3264 @point{}4
3265 5
3266 6
3267 ---------- Buffer: foo ----------
3268 @end group
3269 @end example
3270
3271 If @var{noforce} is non-@code{nil}, and @var{position} would place point
3272 off screen at the next redisplay, then redisplay computes a new window-start
3273 position that works well with point, and thus @var{position} is not used.
3274 @end defun
3275
3276 @vindex set-window-group-start-function
3277 @defun set-window-group-start window position &optional noforce
3278 This function is like @code{set-window-start}, except that when
3279 @var{window} is a part of a group of windows (@pxref{Window Group}),
3280 @code{set-window-group-start} sets the start position of the entire
3281 group. This condition holds when the buffer local variable
3282 @code{set-window-group-start-function} is set to a function. In this
3283 case, @code{set-window-group-start} calls the function with the three
3284 arguments @var{window}, @var{position}, and @var{noforce}, then
3285 returns its result. The arguments @var{position} and @var{noforce} in
3286 this function have the same meaning as in @code{set-window-start}.
3287 @end defun
3288
3289 @defun pos-visible-in-window-p &optional position window partially
3290 This function returns non-@code{nil} if @var{position} is within the
3291 range of text currently visible on the screen in @var{window}. It
3292 returns @code{nil} if @var{position} is scrolled vertically out of
3293 view. Locations that are partially obscured are not considered
3294 visible unless @var{partially} is non-@code{nil}. The argument
3295 @var{position} defaults to the current position of point in
3296 @var{window}; @var{window} defaults to the selected window. If
3297 @var{position} is @code{t}, that means to check either the first
3298 visible position of the last screen line in @var{window}, or the
3299 end-of-buffer position, whichever comes first.
3300
3301 This function considers only vertical scrolling. If @var{position} is
3302 out of view only because @var{window} has been scrolled horizontally,
3303 @code{pos-visible-in-window-p} returns non-@code{nil} anyway.
3304 @xref{Horizontal Scrolling}.
3305
3306 If @var{position} is visible, @code{pos-visible-in-window-p} returns
3307 @code{t} if @var{partially} is @code{nil}; if @var{partially} is
3308 non-@code{nil}, and the character following @var{position} is fully
3309 visible, it returns a list of the form @code{(@var{x} @var{y})}, where
3310 @var{x} and @var{y} are the pixel coordinates relative to the top left
3311 corner of the window; otherwise it returns an extended list of the form
3312 @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})},
3313 where @var{rtop} and @var{rbot} specify the number of off-window pixels
3314 at the top and bottom of the row at @var{position}, @var{rowh} specifies
3315 the visible height of that row, and @var{vpos} specifies the vertical
3316 position (zero-based row number) of that row.
3317
3318 Here is an example:
3319
3320 @example
3321 @group
3322 ;; @r{If point is off the screen now, recenter it now.}
3323 (or (pos-visible-in-window-p
3324 (point) (selected-window))
3325 (recenter 0))
3326 @end group
3327 @end example
3328 @end defun
3329
3330 @vindex pos-visible-in-window-group-p-function
3331 @defun pos-visible-in-window-group-p &optional position window partially
3332 This function is like @code{pos-visible-in-window-p}, except that when
3333 @var{window} is a part of a group of windows (@pxref{Window Group}),
3334 @code{pos-visible-in-window-group-p} tests the visibility of @var{pos}
3335 in the entire group, not just in the single @var{window}. This
3336 condition holds when the buffer local variable
3337 @code{pos-visible-in-window-group-p-function} is set to a function.
3338 In this case @code{pos-visible-in-window-group-p} calls the function
3339 with the three arguments @var{position}, @var{window}, and
3340 @var{partially}, then returns its result. The arguments
3341 @var{position} and @var{partially} have the same meaning as in
3342 @code{pos-visible-in-window-p}.
3343 @end defun
3344
3345 @defun window-line-height &optional line window
3346 This function returns the height of text line @var{line} in
3347 @var{window}. If @var{line} is one of @code{header-line} or
3348 @code{mode-line}, @code{window-line-height} returns information about
3349 the corresponding line of the window. Otherwise, @var{line} is a text
3350 line number starting from 0. A negative number counts from the end of
3351 the window. The default for @var{line} is the current line in
3352 @var{window}; the default for @var{window} is the selected window.
3353
3354 If the display is not up to date, @code{window-line-height} returns
3355 @code{nil}. In that case, @code{pos-visible-in-window-p} may be used
3356 to obtain related information.
3357
3358 If there is no line corresponding to the specified @var{line},
3359 @code{window-line-height} returns @code{nil}. Otherwise, it returns
3360 a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
3361 where @var{height} is the height in pixels of the visible part of the
3362 line, @var{vpos} and @var{ypos} are the vertical position in lines and
3363 pixels of the line relative to the top of the first text line, and
3364 @var{offbot} is the number of off-window pixels at the bottom of the
3365 text line. If there are off-window pixels at the top of the (first)
3366 text line, @var{ypos} is negative.
3367 @end defun
3368
3369 @node Textual Scrolling
3370 @section Textual Scrolling
3371 @cindex textual scrolling
3372 @cindex scrolling textually
3373
3374 @dfn{Textual scrolling} means moving the text up or down through a
3375 window. It works by changing the window's display-start location. It
3376 may also change the value of @code{window-point} to keep point on the
3377 screen (@pxref{Window Point}).
3378
3379 The basic textual scrolling functions are @code{scroll-up} (which
3380 scrolls forward) and @code{scroll-down} (which scrolls backward). In
3381 these function names, ``up'' and ``down'' refer to the direction of
3382 motion of the buffer text relative to the window. Imagine that the
3383 text is written on a long roll of paper and that the scrolling
3384 commands move the paper up and down. Thus, if you are looking at the
3385 middle of a buffer and repeatedly call @code{scroll-down}, you will
3386 eventually see the beginning of the buffer.
3387
3388 Unfortunately, this sometimes causes confusion, because some people
3389 tend to think in terms of the opposite convention: they
3390 imagine the window moving over text that remains in place, so that
3391 ``down'' commands take you to the end of the buffer. This convention
3392 is consistent with fact that such a command is bound to a key named
3393 @key{PageDown} on modern keyboards.
3394 @ignore
3395 We have not switched to this convention as that is likely to break
3396 existing Emacs Lisp code.
3397 @end ignore
3398
3399 Textual scrolling functions (aside from @code{scroll-other-window})
3400 have unpredictable results if the current buffer is not the one
3401 displayed in the selected window. @xref{Current Buffer}.
3402
3403 If the window contains a row taller than the height of the window
3404 (for example in the presence of a large image), the scroll functions
3405 will adjust the window's vertical scroll position to scroll the
3406 partially visible row. Lisp callers can disable this feature by
3407 binding the variable @code{auto-window-vscroll} to @code{nil}
3408 (@pxref{Vertical Scrolling}).
3409
3410 @deffn Command scroll-up &optional count
3411 This function scrolls forward by @var{count} lines in the selected
3412 window.
3413
3414 If @var{count} is negative, it scrolls backward instead. If
3415 @var{count} is @code{nil} (or omitted), the distance scrolled is
3416 @code{next-screen-context-lines} lines less than the height of the
3417 window's text area.
3418
3419 If the selected window cannot be scrolled any further, this function
3420 signals an error. Otherwise, it returns @code{nil}.
3421 @end deffn
3422
3423 @deffn Command scroll-down &optional count
3424 This function scrolls backward by @var{count} lines in the selected
3425 window.
3426
3427 If @var{count} is negative, it scrolls forward instead. In other
3428 respects, it behaves the same way as @code{scroll-up} does.
3429 @end deffn
3430
3431 @deffn Command scroll-up-command &optional count
3432 This behaves like @code{scroll-up}, except that if the selected window
3433 cannot be scrolled any further and the value of the variable
3434 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3435 end of the buffer instead. If point is already there, it signals an
3436 error.
3437 @end deffn
3438
3439 @deffn Command scroll-down-command &optional count
3440 This behaves like @code{scroll-down}, except that if the selected
3441 window cannot be scrolled any further and the value of the variable
3442 @code{scroll-error-top-bottom} is @code{t}, it tries to move to the
3443 beginning of the buffer instead. If point is already there, it
3444 signals an error.
3445 @end deffn
3446
3447 @deffn Command scroll-other-window &optional count
3448 This function scrolls the text in another window upward @var{count}
3449 lines. Negative values of @var{count}, or @code{nil}, are handled
3450 as in @code{scroll-up}.
3451
3452 You can specify which buffer to scroll by setting the variable
3453 @code{other-window-scroll-buffer} to a buffer. If that buffer isn't
3454 already displayed, @code{scroll-other-window} displays it in some
3455 window.
3456
3457 When the selected window is the minibuffer, the next window is normally
3458 the leftmost one immediately above it. You can specify a different
3459 window to scroll, when the minibuffer is selected, by setting the variable
3460 @code{minibuffer-scroll-window}. This variable has no effect when any
3461 other window is selected. When it is non-@code{nil} and the
3462 minibuffer is selected, it takes precedence over
3463 @code{other-window-scroll-buffer}. @xref{Definition of
3464 minibuffer-scroll-window}.
3465
3466 When the minibuffer is active, it is the next window if the selected
3467 window is the one at the bottom right corner. In this case,
3468 @code{scroll-other-window} attempts to scroll the minibuffer. If the
3469 minibuffer contains just one line, it has nowhere to scroll to, so the
3470 line reappears after the echo area momentarily displays the message
3471 @samp{End of buffer}.
3472 @end deffn
3473
3474 @defvar other-window-scroll-buffer
3475 If this variable is non-@code{nil}, it tells @code{scroll-other-window}
3476 which buffer's window to scroll.
3477 @end defvar
3478
3479 @defopt scroll-margin
3480 This option specifies the size of the scroll margin---a minimum number
3481 of lines between point and the top or bottom of a window. Whenever
3482 point gets within this many lines of the top or bottom of the window,
3483 redisplay scrolls the text automatically (if possible) to move point
3484 out of the margin, closer to the center of the window.
3485 @end defopt
3486
3487 @defopt scroll-conservatively
3488 This variable controls how scrolling is done automatically when point
3489 moves off the screen (or into the scroll margin). If the value is a
3490 positive integer @var{n}, then redisplay scrolls the text up to
3491 @var{n} lines in either direction, if that will bring point back into
3492 proper view. This behavior is called @dfn{conservative scrolling}.
3493 Otherwise, scrolling happens in the usual way, under the control of
3494 other variables such as @code{scroll-up-aggressively} and
3495 @code{scroll-down-aggressively}.
3496
3497 The default value is zero, which means that conservative scrolling
3498 never happens.
3499 @end defopt
3500
3501 @defopt scroll-down-aggressively
3502 The value of this variable should be either @code{nil} or a fraction
3503 @var{f} between 0 and 1. If it is a fraction, that specifies where on
3504 the screen to put point when scrolling down. More precisely, when a
3505 window scrolls down because point is above the window start, the new
3506 start position is chosen to put point @var{f} part of the window
3507 height from the top. The larger @var{f}, the more aggressive the
3508 scrolling.
3509
3510 A value of @code{nil} is equivalent to .5, since its effect is to center
3511 point. This variable automatically becomes buffer-local when set in any
3512 fashion.
3513 @end defopt
3514
3515 @defopt scroll-up-aggressively
3516 Likewise, for scrolling up. The value, @var{f}, specifies how far
3517 point should be placed from the bottom of the window; thus, as with
3518 @code{scroll-up-aggressively}, a larger value scrolls more aggressively.
3519 @end defopt
3520
3521 @defopt scroll-step
3522 This variable is an older variant of @code{scroll-conservatively}.
3523 The difference is that if its value is @var{n}, that permits scrolling
3524 only by precisely @var{n} lines, not a smaller number. This feature
3525 does not work with @code{scroll-margin}. The default value is zero.
3526 @end defopt
3527
3528 @cindex @code{scroll-command} property
3529 @defopt scroll-preserve-screen-position
3530 If this option is @code{t}, whenever a scrolling command moves point
3531 off-window, Emacs tries to adjust point to keep the cursor at its old
3532 vertical position in the window, rather than the window edge.
3533
3534 If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
3535 to keep the cursor at the same vertical position, even if the
3536 scrolling command didn't move point off-window.
3537
3538 This option affects all scroll commands that have a non-@code{nil}
3539 @code{scroll-command} symbol property.
3540 @end defopt
3541
3542 @defopt next-screen-context-lines
3543 The value of this variable is the number of lines of continuity to
3544 retain when scrolling by full screens. For example, @code{scroll-up}
3545 with an argument of @code{nil} scrolls so that this many lines at the
3546 bottom of the window appear instead at the top. The default value is
3547 @code{2}.
3548 @end defopt
3549
3550 @defopt scroll-error-top-bottom
3551 If this option is @code{nil} (the default), @code{scroll-up-command}
3552 and @code{scroll-down-command} simply signal an error when no more
3553 scrolling is possible.
3554
3555 If the value is @code{t}, these commands instead move point to the
3556 beginning or end of the buffer (depending on scrolling direction);
3557 only if point is already on that position do they signal an error.
3558 @end defopt
3559
3560 @deffn Command recenter &optional count
3561 @cindex centering point
3562 This function scrolls the text in the selected window so that point is
3563 displayed at a specified vertical position within the window. It does
3564 not move point with respect to the text.
3565
3566 If @var{count} is a non-negative number, that puts the line containing
3567 point @var{count} lines down from the top of the window. If
3568 @var{count} is a negative number, then it counts upward from the
3569 bottom of the window, so that @minus{}1 stands for the last usable
3570 line in the window.
3571
3572 If @var{count} is @code{nil} (or a non-@code{nil} list),
3573 @code{recenter} puts the line containing point in the middle of the
3574 window. If @var{count} is @code{nil}, this function may redraw the
3575 frame, according to the value of @code{recenter-redisplay}.
3576
3577 When @code{recenter} is called interactively, @var{count} is the raw
3578 prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
3579 @var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
3580 @var{count} to 4, which positions the current line four lines from the
3581 top.
3582
3583 With an argument of zero, @code{recenter} positions the current line at
3584 the top of the window. The command @code{recenter-top-bottom} offers
3585 a more convenient way to achieve this.
3586 @end deffn
3587
3588 @vindex recenter-window-group-function
3589 @defun recenter-window-group &optional count
3590 This function is like @code{recenter}, except that when the selected
3591 window is part of a group of windows (@pxref{Window Group}),
3592 @code{recenter-window-group} scrolls the entire group. This condition
3593 holds when the buffer local variable
3594 @code{recenter-window-group-function} is set to a function. In this
3595 case, @code{recenter-window-group} calls the function with the
3596 argument @var{count}, then returns its result. The argument
3597 @var{count} has the same meaning as in @code{recenter}, but with
3598 respect to the entire window group.
3599 @end defun
3600
3601 @defopt recenter-redisplay
3602 If this variable is non-@code{nil}, calling @code{recenter} with a
3603 @code{nil} argument redraws the frame. The default value is
3604 @code{tty}, which means only redraw the frame if it is a tty frame.
3605 @end defopt
3606
3607 @deffn Command recenter-top-bottom &optional count
3608 This command, which is the default binding for @kbd{C-l}, acts like
3609 @code{recenter}, except if called with no argument. In that case,
3610 successive calls place point according to the cycling order defined
3611 by the variable @code{recenter-positions}.
3612 @end deffn
3613
3614 @defopt recenter-positions
3615 This variable controls how @code{recenter-top-bottom} behaves when
3616 called with no argument. The default value is @code{(middle top
3617 bottom)}, which means that successive calls of
3618 @code{recenter-top-bottom} with no argument cycle between placing
3619 point at the middle, top, and bottom of the window.
3620 @end defopt
3621
3622
3623 @node Vertical Scrolling
3624 @section Vertical Fractional Scrolling
3625 @cindex vertical fractional scrolling
3626 @cindex vertical scroll position
3627
3628 @dfn{Vertical fractional scrolling} means shifting text in a window
3629 up or down by a specified multiple or fraction of a line. Each window
3630 has a @dfn{vertical scroll position}, which is a number, never less than
3631 zero. It specifies how far to raise the contents of the window.
3632 Raising the window contents generally makes all or part of some lines
3633 disappear off the top, and all or part of some other lines appear at the
3634 bottom. The usual value is zero.
3635
3636 The vertical scroll position is measured in units of the normal line
3637 height, which is the height of the default font. Thus, if the value is
3638 .5, that means the window contents are scrolled up half the normal line
3639 height. If it is 3.3, that means the window contents are scrolled up
3640 somewhat over three times the normal line height.
3641
3642 What fraction of a line the vertical scrolling covers, or how many
3643 lines, depends on what the lines contain. A value of .5 could scroll a
3644 line whose height is very short off the screen, while a value of 3.3
3645 could scroll just part of the way through a tall line or an image.
3646
3647 @defun window-vscroll &optional window pixels-p
3648 This function returns the current vertical scroll position of
3649 @var{window}. The default for @var{window} is the selected window.
3650 If @var{pixels-p} is non-@code{nil}, the return value is measured in
3651 pixels, rather than in units of the normal line height.
3652
3653 @example
3654 @group
3655 (window-vscroll)
3656 @result{} 0
3657 @end group
3658 @end example
3659 @end defun
3660
3661 @defun set-window-vscroll window lines &optional pixels-p
3662 This function sets @var{window}'s vertical scroll position to
3663 @var{lines}. If @var{window} is @code{nil}, the selected window is
3664 used. The argument @var{lines} should be zero or positive; if not, it
3665 is taken as zero.
3666
3667
3668 The actual vertical scroll position must always correspond
3669 to an integral number of pixels, so the value you specify
3670 is rounded accordingly.
3671
3672 The return value is the result of this rounding.
3673
3674 @example
3675 @group
3676 (set-window-vscroll (selected-window) 1.2)
3677 @result{} 1.13
3678 @end group
3679 @end example
3680
3681 If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
3682 pixels. In this case, the return value is @var{lines}.
3683 @end defun
3684
3685 @defvar auto-window-vscroll
3686 If this variable is non-@code{nil}, the @code{line-move},
3687 @code{scroll-up}, and @code{scroll-down} functions will automatically
3688 modify the vertical scroll position to scroll through display rows
3689 that are taller than the height of the window, for example in the
3690 presence of large images.
3691 @end defvar
3692
3693 @node Horizontal Scrolling
3694 @section Horizontal Scrolling
3695 @cindex horizontal scrolling
3696
3697 @dfn{Horizontal scrolling} means shifting the image in the window left
3698 or right by a specified multiple of the normal character width. Each
3699 window has a @dfn{horizontal scroll position}, which is a number, never
3700 less than zero. It specifies how far to shift the contents left.
3701 Shifting the window contents left generally makes all or part of some
3702 characters disappear off the left, and all or part of some other
3703 characters appear at the right. The usual value is zero.
3704
3705 The horizontal scroll position is measured in units of the normal
3706 character width, which is the width of space in the default font. Thus,
3707 if the value is 5, that means the window contents are scrolled left by 5
3708 times the normal character width. How many characters actually
3709 disappear off to the left depends on their width, and could vary from
3710 line to line.
3711
3712 Because we read from side to side in the inner loop, and from top
3713 to bottom in the outer loop, the effect of horizontal scrolling is
3714 not like that of textual or vertical scrolling. Textual scrolling
3715 involves selection of a portion of text to display, and vertical
3716 scrolling moves the window contents contiguously; but horizontal
3717 scrolling causes part of @emph{each line} to go off screen.
3718
3719 Usually, no horizontal scrolling is in effect; then the leftmost
3720 column is at the left edge of the window. In this state, scrolling to
3721 the right is meaningless, since there is no data to the left of the edge
3722 to be revealed by it; so this is not allowed. Scrolling to the left is
3723 allowed; it scrolls the first columns of text off the edge of the window
3724 and can reveal additional columns on the right that were truncated
3725 before. Once a window has a nonzero amount of leftward horizontal
3726 scrolling, you can scroll it back to the right, but only so far as to
3727 reduce the net horizontal scroll to zero. There is no limit to how far
3728 left you can scroll, but eventually all the text will disappear off the
3729 left edge.
3730
3731 @vindex auto-hscroll-mode
3732 If @code{auto-hscroll-mode} is set, redisplay automatically alters
3733 the horizontal scrolling of a window as necessary to ensure that point
3734 is always visible. However, you can still set the horizontal
3735 scrolling value explicitly. The value you specify serves as a lower
3736 bound for automatic scrolling, i.e., automatic scrolling will not
3737 scroll a window to a column less than the specified one.
3738
3739 @deffn Command scroll-left &optional count set-minimum
3740 This function scrolls the selected window @var{count} columns to the
3741 left (or to the right if @var{count} is negative). The default
3742 for @var{count} is the window width, minus 2.
3743
3744 The return value is the total amount of leftward horizontal scrolling in
3745 effect after the change---just like the value returned by
3746 @code{window-hscroll} (below).
3747
3748 Note that text in paragraphs whose base direction is right-to-left
3749 (@pxref{Bidirectional Display}) moves in the opposite direction: e.g.,
3750 it moves to the right when @code{scroll-left} is invoked with a
3751 positive value of @var{count}.
3752
3753 Once you scroll a window as far right as it can go, back to its normal
3754 position where the total leftward scrolling is zero, attempts to scroll
3755 any farther right have no effect.
3756
3757 If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
3758 the lower bound for automatic scrolling; that is, automatic scrolling
3759 will not scroll a window to a column less than the value returned by
3760 this function. Interactive calls pass non-@code{nil} for
3761 @var{set-minimum}.
3762 @end deffn
3763
3764 @deffn Command scroll-right &optional count set-minimum
3765 This function scrolls the selected window @var{count} columns to the
3766 right (or to the left if @var{count} is negative). The default
3767 for @var{count} is the window width, minus 2. Aside from the direction
3768 of scrolling, this works just like @code{scroll-left}.
3769 @end deffn
3770
3771 @defun window-hscroll &optional window
3772 This function returns the total leftward horizontal scrolling of
3773 @var{window}---the number of columns by which the text in @var{window}
3774 is scrolled left past the left margin. (In right-to-left paragraphs,
3775 the value is the total amount of the rightward scrolling instead.)
3776 The default for @var{window} is the selected window.
3777
3778 The return value is never negative. It is zero when no horizontal
3779 scrolling has been done in @var{window} (which is usually the case).
3780
3781
3782 @example
3783 @group
3784 (window-hscroll)
3785 @result{} 0
3786 @end group
3787 @group
3788 (scroll-left 5)
3789 @result{} 5
3790 @end group
3791 @group
3792 (window-hscroll)
3793 @result{} 5
3794 @end group
3795 @end example
3796 @end defun
3797
3798 @defun set-window-hscroll window columns
3799 This function sets horizontal scrolling of @var{window}. The value of
3800 @var{columns} specifies the amount of scrolling, in terms of columns
3801 from the left margin (right margin in right-to-left paragraphs). The
3802 argument @var{columns} should be zero or positive; if not, it is taken
3803 as zero. Fractional values of @var{columns} are not supported at
3804 present.
3805
3806 Note that @code{set-window-hscroll} may appear not to work if you test
3807 it by evaluating a call with @kbd{M-:} in a simple way. What happens
3808 is that the function sets the horizontal scroll value and returns, but
3809 then redisplay adjusts the horizontal scrolling to make point visible,
3810 and this overrides what the function did. You can observe the
3811 function's effect if you call it while point is sufficiently far from
3812 the left margin that it will remain visible.
3813
3814 The value returned is @var{columns}.
3815
3816 @example
3817 @group
3818 (set-window-hscroll (selected-window) 10)
3819 @result{} 10
3820 @end group
3821 @end example
3822 @end defun
3823
3824 Here is how you can determine whether a given position @var{position}
3825 is off the screen due to horizontal scrolling:
3826
3827 @c FIXME: Maybe hscroll-on-screen-p is a better name?
3828 @example
3829 @group
3830 (defun hscroll-on-screen (window position)
3831 (save-excursion
3832 (goto-char position)
3833 (and
3834 (>= (- (current-column) (window-hscroll window)) 0)
3835 (< (- (current-column) (window-hscroll window))
3836 (window-width window)))))
3837 @end group
3838 @end example
3839
3840
3841 @node Coordinates and Windows
3842 @section Coordinates and Windows
3843 @cindex frame-relative coordinate
3844 @cindex coordinate, relative to frame
3845 @cindex window position
3846
3847 This section describes functions that report the position of a window.
3848 Most of these functions report positions relative to an origin at the
3849 native position of the window's frame (@pxref{Frame Geometry}). Some
3850 functions report positions relative to the origin of the display of the
3851 window's frame. In any case, the origin has the coordinates (0, 0) and
3852 X and Y coordinates increase rightward and downward
3853 respectively.
3854
3855 For the following functions, X and Y coordinates are reported in
3856 integer character units, i.e., numbers of lines and columns
3857 respectively. On a graphical display, each ``line'' and ``column''
3858 corresponds to the height and width of the default character specified by
3859 the frame's default font (@pxref{Frame Font}).
3860
3861 @defun window-edges &optional window body absolute pixelwise
3862 This function returns a list of the edge coordinates of @var{window}.
3863 If @var{window} is omitted or @code{nil}, it defaults to the selected
3864 window.
3865
3866 The return value has the form @code{(@var{left} @var{top} @var{right}
3867 @var{bottom})}. These list elements are, respectively, the X
3868 coordinate of the leftmost column occupied by the window, the Y
3869 coordinate of the topmost row, the X coordinate one column to the
3870 right of the rightmost column, and the Y coordinate one row down from
3871 the bottommost row.
3872
3873 Note that these are the actual outer edges of the window, including any
3874 header line, mode line, scroll bar, fringes, window divider and display
3875 margins. On a text terminal, if the window has a neighbor on its right,
3876 its right edge includes the separator line between the window and its
3877 neighbor.
3878
3879 If the optional argument @var{body} is @code{nil}, this means to
3880 return the edges corresponding to the total size of @var{window}.
3881 @var{body} non-@code{nil} means to return the edges of @var{window}'s
3882 body (aka text area). If @var{body} is non-@code{nil}, @var{window}
3883 must specify a live window.
3884
3885 If the optional argument @var{absolute} is @code{nil}, this means to
3886 return edges relative to the native position of @var{window}'s frame.
3887 @var{absolute} non-@code{nil} means to return coordinates relative to
3888 the origin (0, 0) of @var{window}'s display. On non-graphical systems
3889 this argument has no effect.
3890
3891 If the optional argument @var{pixelwise} is @code{nil}, this means to
3892 return the coordinates in terms of the default character width and
3893 height of @var{window}'s frame (@pxref{Frame Font}), rounded if
3894 necessary. @var{pixelwise} non-@code{nil} means to return the
3895 coordinates in pixels. Note that the pixel specified by @var{right} and
3896 @var{bottom} is immediately outside of these edges. If @var{absolute}
3897 is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too.
3898 @end defun
3899
3900 @defun window-body-edges &optional window
3901 This function returns the edges of @var{window}'s body (@pxref{Window
3902 Sizes}). Calling @code{(window-body-edges window)} is equivalent to
3903 calling @code{(window-edges window t)}, see above.
3904 @end defun
3905
3906 @comment The following two functions are confusing and hardly used.
3907 @ignore
3908 @defun window-left-column &optional window
3909 This function returns the leftmost column of @var{window}. This value
3910 equals the @var{left} entry in the list returned by @code{(window-edges
3911 window)} minus the number of columns occupied by the internal border of
3912 @var{window}'s frame.
3913 @end defun
3914
3915 @defun window-top-line &optional window
3916 This function returns the topmost row of @var{window}. This value is
3917 equal to the @var{top} entry in the list returned by @code{(window-edges
3918 window)} minus the number of lines occupied by the internal border of
3919 @var{window}'s frame.
3920 @end defun
3921 @end ignore
3922
3923 The following functions can be used to relate a set of
3924 frame-relative coordinates to a window:
3925
3926 @defun window-at x y &optional frame
3927 This function returns the live window at the coordinates @var{x} and
3928 @var{y} given in default character sizes (@pxref{Frame Font}) relative
3929 to the native position of @var{frame} (@pxref{Frame Geometry}).
3930
3931 If there is no window at that position, the return value is @code{nil}.
3932 If @var{frame} is omitted or @code{nil}, it defaults to the selected
3933 frame.
3934 @end defun
3935
3936 @defun coordinates-in-window-p coordinates window
3937 This function checks whether a window @var{window} occupies the frame
3938 relative coordinates @var{coordinates}, and if so, which part of the
3939 window that is. @var{window} should be a live window.
3940
3941 @var{coordinates} should be a cons cell of the form @code{(@var{x}
3942 . @var{y})}, where @var{x} and @var{y} are given in default character
3943 sizes (@pxref{Frame Font}) relative to the native position of
3944 @var{window}'s frame (@pxref{Frame Geometry}).
3945
3946 If there is no window at the specified position, the return value is
3947 @code{nil} . Otherwise, the return value is one of the following:
3948
3949 @table @code
3950 @item (@var{relx} . @var{rely})
3951 The coordinates are inside @var{window}. The numbers @var{relx} and
3952 @var{rely} are the equivalent window-relative coordinates for the
3953 specified position, counting from 0 at the top left corner of the
3954 window.
3955
3956 @item mode-line
3957 The coordinates are in the mode line of @var{window}.
3958
3959 @item header-line
3960 The coordinates are in the header line of @var{window}.
3961
3962 @item right-divider
3963 The coordinates are in the divider separating @var{window} from a
3964 window on the right.
3965
3966 @item bottom-divider
3967 The coordinates are in the divider separating @var{window} from a
3968 window beneath.
3969
3970 @item vertical-line
3971 The coordinates are in the vertical line between @var{window} and its
3972 neighbor to the right. This value occurs only if the window doesn't
3973 have a scroll bar; positions in a scroll bar are considered outside the
3974 window for these purposes.
3975
3976 @item left-fringe
3977 @itemx right-fringe
3978 The coordinates are in the left or right fringe of the window.
3979
3980 @item left-margin
3981 @itemx right-margin
3982 The coordinates are in the left or right margin of the window.
3983
3984 @item nil
3985 The coordinates are not in any part of @var{window}.
3986 @end table
3987
3988 The function @code{coordinates-in-window-p} does not require a frame as
3989 argument because it always uses the frame that @var{window} is on.
3990 @end defun
3991
3992 The following functions return window positions in pixels, rather
3993 than character units. Though mostly useful on graphical displays,
3994 they can also be called on text terminals, where the screen area of
3995 each text character is taken to be one pixel.
3996
3997 @defun window-pixel-edges &optional window
3998 This function returns a list of pixel coordinates for the edges of
3999 @var{window}. Calling @code{(window-pixel-edges window)} is equivalent
4000 to calling @code{(window-edges window nil nil t)}, see above.
4001 @end defun
4002
4003 @comment The following two functions are confusing and hardly used.
4004 @ignore
4005 @defun window-pixel-left &optional window
4006 This function returns the left pixel edge of window @var{window}. This
4007 value equals the @var{left} entry in the list returned by
4008 @code{(window-pixel-edges window)} minus the number of pixels occupied
4009 by the internal border of @var{window}'s frame. @var{window} must be a
4010 valid window and defaults to the selected one.
4011 @end defun
4012
4013 @defun window-pixel-top &optional window
4014 This function returns the top pixel edge of window @var{window}. This
4015 value is equal to the @var{top} entry in the list returned by
4016 @code{(window-pixel-edges window)} minus the number of pixels occupied
4017 by the internal border of @var{window}'s frame. @var{window} must be a
4018 valid window and defaults to the selected one.
4019 @end defun
4020 @end ignore
4021
4022 @defun window-body-pixel-edges &optional window
4023 This function returns the pixel edges of @var{window}'s body. Calling
4024 @code{(window-body-pixel-edges window)} is equivalent to calling
4025 @code{(window-edges window t nil t)}, see above.
4026 @end defun
4027
4028 The following functions return window positions in pixels, relative to
4029 the origin of the display screen rather than that of the frame:
4030
4031 @defun window-absolute-pixel-edges &optional window
4032 This function returns the pixel coordinates of @var{WINDOW} relative to
4033 an origin at (0, 0) of the display of @var{window}'s frame. Calling
4034 @code{(window-absolute-pixel-edges)} is equivalent to calling
4035 @code{(window-edges window nil t t)}, see above.
4036 @end defun
4037
4038 @defun window-absolute-body-pixel-edges &optional window
4039 This function returns the pixel coordinates of @var{WINDOW}'s body
4040 relative to an origin at (0, 0) of the display of @var{window}'s frame.
4041 Calling @code{(window-absolute-body-pixel-edges window)} is equivalent
4042 to calling @code{(window-edges window t t t)}, see above.
4043
4044 Combined with @code{set-mouse-absolute-pixel-position}, this function
4045 can be used to move the mouse pointer to an arbitrary buffer position
4046 visible in some window:
4047
4048 @example
4049 @group
4050 (let ((edges (window-absolute-body-pixel-edges))
4051 (position (pos-visible-in-window-p nil nil t)))
4052 (set-mouse-absolute-pixel-position
4053 (+ (nth 0 edges) (nth 0 position))
4054 (+ (nth 1 edges) (nth 1 position))))
4055 @end group
4056 @end example
4057
4058 On a graphical terminal this form ``warps'' the mouse cursor to the
4059 upper left corner of the glyph at the selected window's point. A
4060 position calculated this way can be also used to show a tooltip window
4061 there.
4062 @end defun
4063
4064 The following function returns the screen coordinates of a buffer
4065 position visible in a window:
4066
4067 @defun window-absolute-pixel-position &optional position window
4068 If the buffer position @var{position} is visible in window @var{window},
4069 this function returns the display coordinates of the upper/left corner
4070 of the glyph at @var{position}. The return value is a cons of the X-
4071 and Y-coordinates of that corner, relative to an origin at (0, 0) of
4072 @var{window}'s display. It returns @code{nil} if @var{position} is not
4073 visible in @var{window}.
4074
4075 @var{window} must be a live window and defaults to the selected
4076 window. @var{position} defaults to the value of @code{window-point}
4077 of @var{window}.
4078
4079 This means that in order to move the mouse pointer to the position of
4080 point in the selected window, it's sufficient to write:
4081
4082 @example
4083 @group
4084 (let ((position (window-absolute-pixel-position)))
4085 (set-mouse-absolute-pixel-position
4086 (car position) (cdr position)))
4087 @end group
4088 @end example
4089 @end defun
4090
4091
4092 @node Window Configurations
4093 @section Window Configurations
4094 @cindex window configurations
4095 @cindex saving window information
4096
4097 A @dfn{window configuration} records the entire layout of one
4098 frame---all windows, their sizes, which buffers they contain, how those
4099 buffers are scrolled, and their value of point; also their
4100 fringes, margins, and scroll bar settings. It also includes the value
4101 of @code{minibuffer-scroll-window}. As a special exception, the window
4102 configuration does not record the value of point in the selected window
4103 for the current buffer.
4104
4105 You can bring back an entire frame layout by restoring a previously
4106 saved window configuration. If you want to record the layout of all
4107 frames instead of just one, use a frame configuration instead of a
4108 window configuration. @xref{Frame Configurations}.
4109
4110 @defun current-window-configuration &optional frame
4111 This function returns a new object representing @var{frame}'s current
4112 window configuration. The default for @var{frame} is the selected
4113 frame. The variable @code{window-persistent-parameters} specifies
4114 which window parameters (if any) are saved by this function.
4115 @xref{Window Parameters}.
4116 @end defun
4117
4118 @defun set-window-configuration configuration
4119 This function restores the configuration of windows and buffers as
4120 specified by @var{configuration}, for the frame that @var{configuration}
4121 was created for.
4122
4123 The argument @var{configuration} must be a value that was previously
4124 returned by @code{current-window-configuration}. The configuration is
4125 restored in the frame from which @var{configuration} was made, whether
4126 that frame is selected or not. In some rare cases this may trigger
4127 execution of the @code{window-size-change-functions} (@pxref{Window
4128 Hooks}) even if the size of windows did not change at all. The
4129 @code{window-configuration-change-hook} functions will be called if and
4130 only if at least one window was added to or deleted from the frame.
4131
4132 If the frame from which @var{configuration} was saved is dead, all this
4133 function does is restore the three variables @code{window-min-height},
4134 @code{window-min-width} and @code{minibuffer-scroll-window}. In this
4135 case, the function returns @code{nil}. Otherwise, it returns @code{t}.
4136
4137 Here is a way of using this function to get the same effect
4138 as @code{save-window-excursion}:
4139
4140 @example
4141 @group
4142 (let ((config (current-window-configuration)))
4143 (unwind-protect
4144 (progn (split-window-below nil)
4145 @dots{})
4146 (set-window-configuration config)))
4147 @end group
4148 @end example
4149 @end defun
4150
4151 @defmac save-window-excursion forms@dots{}
4152 This macro records the window configuration of the selected frame,
4153 executes @var{forms} in sequence, then restores the earlier window
4154 configuration. The return value is the value of the final form in
4155 @var{forms}.
4156
4157 Most Lisp code should not use this macro; @code{save-selected-window}
4158 is typically sufficient. In particular, this macro cannot reliably
4159 prevent the code in @var{forms} from opening new windows, because new
4160 windows might be opened in other frames (@pxref{Choosing Window}), and
4161 @code{save-window-excursion} only saves and restores the window
4162 configuration on the current frame.
4163
4164 Do not use this macro in @code{window-size-change-functions}; exiting
4165 the macro triggers execution of @code{window-size-change-functions},
4166 leading to an endless loop.
4167 @end defmac
4168
4169 @defun window-configuration-p object
4170 This function returns @code{t} if @var{object} is a window configuration.
4171 @end defun
4172
4173 @defun compare-window-configurations config1 config2
4174 This function compares two window configurations as regards the
4175 structure of windows, but ignores the values of point and the
4176 saved scrolling positions---it can return @code{t} even if those
4177 aspects differ.
4178
4179 The function @code{equal} can also compare two window configurations; it
4180 regards configurations as unequal if they differ in any respect, even a
4181 saved point.
4182 @end defun
4183
4184 @defun window-configuration-frame config
4185 This function returns the frame for which the window configuration
4186 @var{config} was made.
4187 @end defun
4188
4189 Other primitives to look inside of window configurations would make
4190 sense, but are not implemented because we did not need them. See the
4191 file @file{winner.el} for some more operations on windows
4192 configurations.
4193
4194 The objects returned by @code{current-window-configuration} die
4195 together with the Emacs process. In order to store a window
4196 configuration on disk and read it back in another Emacs session, you
4197 can use the functions described next. These functions are also useful
4198 to clone the state of a frame into an arbitrary live window
4199 (@code{set-window-configuration} effectively clones the windows of a
4200 frame into the root window of that very frame only).
4201
4202 @cindex window state
4203 @defun window-state-get &optional window writable
4204 This function returns the state of @var{window} as a Lisp object. The
4205 argument @var{window} must be a valid window and defaults to the root
4206 window of the selected frame.
4207
4208 If the optional argument @var{writable} is non-@code{nil}, this means to
4209 not use markers for sampling positions like @code{window-point} or
4210 @code{window-start}. This argument should be non-@code{nil} when the
4211 state will be written to disk and read back in another session.
4212
4213 Together, the argument @var{writable} and the variable
4214 @code{window-persistent-parameters} specify which window parameters are
4215 saved by this function. @xref{Window Parameters}.
4216 @end defun
4217
4218 The value returned by @code{window-state-get} can be used in the same
4219 session to make a clone of a window in another window. It can be also
4220 written to disk and read back in another session. In either case, use
4221 the following function to restore the state of the window.
4222
4223 @defun window-state-put state &optional window ignore
4224 This function puts the window state @var{state} into @var{window}.
4225 The argument @var{state} should be the state of a window returned by
4226 an earlier invocation of @code{window-state-get}, see above. The
4227 optional argument @var{window} can be either a live window or an
4228 internal window (@pxref{Windows and Frames}) and defaults to the
4229 selected one. If @var{window} is not live, it is replaced by a live
4230 window before putting @var{state} into it.
4231
4232 If the optional argument @var{ignore} is non-@code{nil}, it means to ignore
4233 minimum window sizes and fixed-size restrictions. If @var{ignore}
4234 is @code{safe}, this means windows can get as small as one line
4235 and/or two columns.
4236 @end defun
4237
4238
4239 @node Window Parameters
4240 @section Window Parameters
4241 @cindex window parameters
4242
4243 This section describes how window parameters can be used to associate
4244 additional information with windows.
4245
4246 @defun window-parameter window parameter
4247 This function returns @var{window}'s value for @var{parameter}. The
4248 default for @var{window} is the selected window. If @var{window} has no
4249 setting for @var{parameter}, this function returns @code{nil}.
4250 @end defun
4251
4252 @defun window-parameters &optional window
4253 This function returns all parameters of @var{window} and their values.
4254 The default for @var{window} is the selected window. The return value
4255 is either @code{nil}, or an association list whose elements have the form
4256 @code{(@var{parameter} . @var{value})}.
4257 @end defun
4258
4259 @defun set-window-parameter window parameter value
4260 This function sets @var{window}'s value of @var{parameter} to
4261 @var{value} and returns @var{value}. The default for @var{window}
4262 is the selected window.
4263 @end defun
4264
4265 By default, the functions that save and restore window configurations or the
4266 states of windows (@pxref{Window Configurations}) do not care about
4267 window parameters. This means that when you change the value of a
4268 parameter within the body of a @code{save-window-excursion}, the
4269 previous value is not restored when that macro exits. It also means
4270 that when you restore via @code{window-state-put} a window state saved
4271 earlier by @code{window-state-get}, all cloned windows have their
4272 parameters reset to @code{nil}. The following variable allows you to
4273 override the standard behavior:
4274
4275 @defvar window-persistent-parameters
4276 This variable is an alist specifying which parameters get saved by
4277 @code{current-window-configuration} and @code{window-state-get}, and
4278 subsequently restored by @code{set-window-configuration} and
4279 @code{window-state-put}. @xref{Window Configurations}.
4280
4281 The @sc{car} of each entry of this alist is a symbol specifying the
4282 parameter. The @sc{cdr} should be one of the following:
4283
4284 @table @asis
4285 @item @code{nil}
4286 This value means the parameter is saved neither by
4287 @code{window-state-get} nor by @code{current-window-configuration}.
4288
4289 @item @code{t}
4290 This value specifies that the parameter is saved by
4291 @code{current-window-configuration} and (provided its @var{writable}
4292 argument is @code{nil}) by @code{window-state-get}.
4293
4294 @item @code{writable}
4295 This means that the parameter is saved unconditionally by both
4296 @code{current-window-configuration} and @code{window-state-get}. This
4297 value should not be used for parameters whose values do not have a read
4298 syntax. Otherwise, invoking @code{window-state-put} in another session
4299 may fail with an @code{invalid-read-syntax} error.
4300 @end table
4301 @end defvar
4302
4303 Some functions (notably @code{delete-window},
4304 @code{delete-other-windows} and @code{split-window}), may behave specially
4305 when their @var{window} argument has a parameter set. You can override
4306 such special behavior by binding the following variable to a
4307 non-@code{nil} value:
4308
4309 @defvar ignore-window-parameters
4310 If this variable is non-@code{nil}, some standard functions do not
4311 process window parameters. The functions currently affected by this are
4312 @code{split-window}, @code{delete-window}, @code{delete-other-windows},
4313 and @code{other-window}.
4314
4315 An application can bind this variable to a non-@code{nil} value around
4316 calls to these functions. If it does so, the application is fully
4317 responsible for correctly assigning the parameters of all involved
4318 windows when exiting that function.
4319 @end defvar
4320
4321 The following parameters are currently used by the window management
4322 code:
4323
4324 @table @asis
4325 @item @code{delete-window}
4326 This parameter affects the execution of @code{delete-window}
4327 (@pxref{Deleting Windows}).
4328
4329 @item @code{delete-other-windows}
4330 This parameter affects the execution of @code{delete-other-windows}
4331 (@pxref{Deleting Windows}).
4332
4333 @item @code{split-window}
4334 This parameter affects the execution of @code{split-window}
4335 (@pxref{Splitting Windows}).
4336
4337 @item @code{other-window}
4338 This parameter affects the execution of @code{other-window}
4339 (@pxref{Cyclic Window Ordering}).
4340
4341 @item @code{no-other-window}
4342 This parameter marks the window as not selectable by @code{other-window}
4343 (@pxref{Cyclic Window Ordering}).
4344
4345 @item @code{clone-of}
4346 This parameter specifies the window that this one has been cloned
4347 from. It is installed by @code{window-state-get} (@pxref{Window
4348 Configurations}).
4349
4350 @item @code{preserved-size}
4351 This parameter specifies a buffer, a direction where @code{nil} means
4352 vertical and @code{t} horizontal, and a size in pixels. If this window
4353 displays the specified buffer and its size in the indicated direction
4354 equals the size specified by this parameter, then Emacs will try to
4355 preserve the size of this window in the indicated direction. This
4356 parameter is installed and updated by the function
4357 @code{window-preserve-size} (@pxref{Preserving Window Sizes}).
4358
4359 @item @code{quit-restore}
4360 This parameter is installed by the buffer display functions
4361 (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
4362 (@pxref{Quitting Windows}). It contains four elements:
4363
4364 The first element is one of the symbols @code{window}, meaning that the
4365 window has been specially created by @code{display-buffer}; @code{frame},
4366 a separate frame has been created; @code{same}, the window has
4367 displayed the same buffer before; or @code{other}, the window showed
4368 another buffer before.
4369
4370 The second element is either one of the symbols @code{window} or
4371 @code{frame}, or a list whose elements are the buffer shown in the
4372 window before, that buffer's window start and window point positions,
4373 and the window's height at that time.
4374
4375 The third element is the window selected at the time the parameter was
4376 created. The function @code{quit-restore-window} tries to reselect that
4377 window when it deletes the window passed to it as argument.
4378
4379 The fourth element is the buffer whose display caused the creation of
4380 this parameter. @code{quit-restore-window} deletes the specified window
4381 only if it still shows that buffer.
4382 @end table
4383
4384 There are additional parameters @code{window-atom} and @code{window-side};
4385 these are reserved and should not be used by applications.
4386
4387
4388 @node Window Hooks
4389 @section Hooks for Window Scrolling and Changes
4390 @cindex hooks for window operations
4391
4392 This section describes how a Lisp program can take action whenever a
4393 window displays a different part of its buffer or a different buffer.
4394 There are three actions that can change this: scrolling the window,
4395 switching buffers in the window, and changing the size of the window.
4396 The first two actions run @code{window-scroll-functions}; the last runs
4397 @code{window-size-change-functions}.
4398
4399 @defvar window-scroll-functions
4400 This variable holds a list of functions that Emacs should call before
4401 redisplaying a window with scrolling. Displaying a different buffer in
4402 the window also runs these functions.
4403
4404 This variable is not a normal hook, because each function is called with
4405 two arguments: the window, and its new display-start position.
4406
4407 These functions must take care when using @code{window-end}
4408 (@pxref{Window Start and End}); if you need an up-to-date value, you
4409 must use the @var{update} argument to ensure you get it.
4410
4411 @strong{Warning:} don't use this feature to alter the way the window
4412 is scrolled. It's not designed for that, and such use probably won't
4413 work.
4414 @end defvar
4415
4416 @defvar window-size-change-functions
4417 This variable holds a list of functions to be called if the size of any
4418 window changes for any reason. The functions are called once per
4419 redisplay, and once for each frame on which size changes have occurred.
4420
4421 Each function receives the frame as its sole argument. To find out
4422 whether a specific window has changed size, compare the return values of
4423 @code{window-pixel-width-before-size-change} and
4424 @code{window-pixel-width} respectively
4425 @code{window-pixel-height-before-size-change} and
4426 @code{window-pixel-height} for that window (@pxref{Window Sizes}).
4427
4428 These function are usually only called when at least one window was
4429 added or has changed size since the last time this hook was run for the
4430 associated frame. In some rare cases this hook also runs when a window
4431 that was added intermittently has been deleted afterwards. In these
4432 cases none of the windows on the frame will appear to have changed its
4433 size.
4434
4435 You may use @code{save-selected-window} in these functions
4436 (@pxref{Selecting Windows}). However, do not use
4437 @code{save-window-excursion} (@pxref{Window Configurations}); exiting
4438 that macro counts as a size change, which would cause these functions to
4439 be called again.
4440 @end defvar
4441
4442 @defvar window-configuration-change-hook
4443 A normal hook that is run every time the window configuration of a frame
4444 changes. Window configuration changes include splitting and deleting
4445 windows and the display of a different buffer in a window. Resizing the
4446 frame or individual windows do not count as configuration changes. Use
4447 @code{window-size-change-functions}, see above, when you want to track
4448 size changes that are not caused by the deletion or creation of windows.
4449
4450 The buffer-local part of this hook is run once for each window on the
4451 affected frame, with the relevant window selected and its buffer
4452 current. The global part is run once for the modified frame, with that
4453 frame selected.
4454 @end defvar
4455
4456 In addition, you can use @code{jit-lock-register} to register a Font
4457 Lock fontification function, which will be called whenever parts of a
4458 buffer are (re)fontified because a window was scrolled or its size
4459 changed. @xref{Other Font Lock Variables}.