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