Add arch taglines
[bpt/emacs.git] / lispref / windows.texi
CommitLineData
b1b12a8e
RS
1@c -*-texinfo-*-
2@c This is part of the GNU Emacs Lisp Reference Manual.
fd897522
GM
3@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4@c Free Software Foundation, Inc.
b1b12a8e
RS
5@c See the file elisp.texi for copying conditions.
6@setfilename ../info/windows
7@node Windows, Frames, Buffers, Top
8@chapter Windows
9
10 This chapter describes most of the functions and variables related to
11Emacs windows. See @ref{Display}, for information on how text is
12displayed in windows.
13
14@menu
3c29caa8
DH
15* Basic Windows:: Basic information on using windows.
16* Splitting Windows:: Splitting one window into two windows.
17* Deleting Windows:: Deleting a window gives its space to other windows.
18* Selecting Windows:: The selected window is the one that you edit in.
19* Cyclic Window Ordering:: Moving around the existing windows.
20* Buffers and Windows:: Each window displays the contents of a buffer.
21* Displaying Buffers:: Higher-lever functions for displaying a buffer
22 and choosing a window for it.
23* Choosing Window:: How to choose a window for displaying a buffer.
24* Window Point:: Each window has its own location of point.
25* Window Start:: The display-start position controls which text
26 is on-screen in the window.
8241495d
RS
27* Textual Scrolling:: Moving text up and down through the window.
28* Vertical Scrolling:: Moving the contents up and down on the window.
29* Horizontal Scrolling:: Moving the contents sideways on the window.
3c29caa8
DH
30* Size of Window:: Accessing the size of a window.
31* Resizing Windows:: Changing the size of a window.
32* Coordinates and Windows:: Converting coordinates to windows.
33* Window Configurations:: Saving and restoring the state of the screen.
f9f59935
RS
34* Window Hooks:: Hooks for scrolling, window size changes,
35 redisplay going past a certain point,
36 or window configuration changes.
b1b12a8e
RS
37@end menu
38
39@node Basic Windows
40@section Basic Concepts of Emacs Windows
41@cindex window
42@cindex selected window
43
bfe721d1
KH
44 A @dfn{window} in Emacs is the physical area of the screen in which a
45buffer is displayed. The term is also used to refer to a Lisp object that
b1b12a8e
RS
46represents that screen area in Emacs Lisp. It should be
47clear from the context which is meant.
48
bfe721d1
KH
49 Emacs groups windows into frames. A frame represents an area of
50screen available for Emacs to use. Each frame always contains at least
51one window, but you can subdivide it vertically or horizontally into
52multiple nonoverlapping Emacs windows.
53
54 In each frame, at any time, one and only one window is designated as
55@dfn{selected within the frame}. The frame's cursor appears in that
f9f59935 56window. At any time, one frame is the selected frame; and the window
bfe721d1
KH
57selected within that frame is @dfn{the selected window}. The selected
58window's buffer is usually the current buffer (except when
59@code{set-buffer} has been used). @xref{Current Buffer}.
60
61 For practical purposes, a window exists only while it is displayed in
62a frame. Once removed from the frame, the window is effectively deleted
63and should not be used, @emph{even though there may still be references
64to it} from other Lisp objects. Restoring a saved window configuration
65is the only way for a window no longer on the screen to come back to
66life. (@xref{Deleting Windows}.)
b1b12a8e
RS
67
68 Each window has the following attributes:
69
70@itemize @bullet
71@item
72containing frame
73
3c29caa8 74@item
b1b12a8e
RS
75window height
76
3c29caa8 77@item
b1b12a8e
RS
78window width
79
3c29caa8 80@item
b1b12a8e
RS
81window edges with respect to the screen or frame
82
3c29caa8 83@item
b1b12a8e
RS
84the buffer it displays
85
3c29caa8 86@item
b1b12a8e
RS
87position within the buffer at the upper left of the window
88
3c29caa8 89@item
c638661f 90amount of horizontal scrolling, in columns
b1b12a8e 91
3c29caa8 92@item
b1b12a8e
RS
93point
94
3c29caa8 95@item
b1b12a8e
RS
96the mark
97
3c29caa8 98@item
b1b12a8e
RS
99how recently the window was selected
100@end itemize
101
102@cindex multiple windows
103 Users create multiple windows so they can look at several buffers at
104once. Lisp libraries use multiple windows for a variety of reasons, but
bfe721d1
KH
105most often to display related information. In Rmail, for example, you
106can move through a summary buffer in one window while the other window
107shows messages one at a time as they are reached.
b1b12a8e
RS
108
109 The meaning of ``window'' in Emacs is similar to what it means in the
c638661f 110context of general-purpose window systems such as X, but not identical.
bfe721d1
KH
111The X Window System places X windows on the screen; Emacs uses one or
112more X windows as frames, and subdivides them into
113Emacs windows. When you use Emacs on a character-only terminal, Emacs
114treats the whole terminal screen as one frame.
b1b12a8e
RS
115
116@cindex terminal screen
117@cindex screen of terminal
118@cindex tiled windows
119 Most window systems support arbitrarily located overlapping windows.
120In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
f9f59935
RS
121together they fill the whole screen or frame. Because of the way in
122which Emacs creates new windows and resizes them, not all conceivable
123tilings of windows on an Emacs frame are actually possible.
124@xref{Splitting Windows}, and @ref{Size of Window}.
b1b12a8e
RS
125
126 @xref{Display}, for information on how the contents of the
127window's buffer are displayed in the window.
128
129@defun windowp object
f9f59935 130This function returns @code{t} if @var{object} is a window.
b1b12a8e
RS
131@end defun
132
133@node Splitting Windows
134@section Splitting Windows
135@cindex splitting windows
136@cindex window splitting
137
138 The functions described here are the primitives used to split a window
139into two windows. Two higher level functions sometimes split a window,
140but not always: @code{pop-to-buffer} and @code{display-buffer}
141(@pxref{Displaying Buffers}).
142
143 The functions described here do not accept a buffer as an argument.
144The two ``halves'' of the split window initially display the same buffer
145previously visible in the window that was split.
146
147@deffn Command split-window &optional window size horizontal
148This function splits @var{window} into two windows. The original
149window @var{window} remains the selected window, but occupies only
150part of its former screen area. The rest is occupied by a newly created
151window which is returned as the value of this function.
152
2726b68b 153If @var{horizontal} is non-@code{nil}, then @var{window} splits into
b1b12a8e
RS
154two side by side windows. The original window @var{window} keeps the
155leftmost @var{size} columns, and gives the rest of the columns to the
156new window. Otherwise, it splits into windows one above the other, and
157@var{window} keeps the upper @var{size} lines and gives the rest of the
158lines to the new window. The original window is therefore the
c638661f 159left-hand or upper of the two, and the new window is the right-hand or
b1b12a8e
RS
160lower.
161
2726b68b 162If @var{window} is omitted or @code{nil}, then the selected window is
b1b12a8e
RS
163split. If @var{size} is omitted or @code{nil}, then @var{window} is
164divided evenly into two parts. (If there is an odd line, it is
165allocated to the new window.) When @code{split-window} is called
166interactively, all its arguments are @code{nil}.
167
2726b68b
RS
168If splitting would result in making a window that is smaller than
169@code{window-min-height} or @code{window-min-width}, the function
170signals an error and does not split the window at all.
171
172The following example starts with one window on a screen that is 50
926a5166 173lines high by 80 columns wide; then it splits the window.
b1b12a8e
RS
174
175@smallexample
176@group
177(setq w (selected-window))
178 @result{} #<window 8 on windows.texi>
179(window-edges) ; @r{Edges in order:}
180 @result{} (0 0 80 50) ; @r{left--top--right--bottom}
181@end group
182
183@group
184;; @r{Returns window created}
3c29caa8 185(setq w2 (split-window w 15))
b1b12a8e
RS
186 @result{} #<window 28 on windows.texi>
187@end group
188@group
189(window-edges w2)
190 @result{} (0 15 80 50) ; @r{Bottom window;}
191 ; @r{top is line 15}
192@end group
193@group
194(window-edges w)
195 @result{} (0 0 80 15) ; @r{Top window}
196@end group
197@end smallexample
198
199The screen looks like this:
200
201@smallexample
202@group
3c29caa8
DH
203 __________
204 | | line 0
b1b12a8e
RS
205 | w |
206 |__________|
207 | | line 15
208 | w2 |
209 |__________|
210 line 50
211 column 0 column 80
212@end group
213@end smallexample
214
926a5166 215Next, split the top window horizontally:
b1b12a8e
RS
216
217@smallexample
218@group
219(setq w3 (split-window w 35 t))
220 @result{} #<window 32 on windows.texi>
221@end group
222@group
223(window-edges w3)
224 @result{} (35 0 80 15) ; @r{Left edge at column 35}
225@end group
226@group
227(window-edges w)
228 @result{} (0 0 35 15) ; @r{Right edge at column 35}
229@end group
230@group
231(window-edges w2)
232 @result{} (0 15 80 50) ; @r{Bottom window unchanged}
233@end group
234@end smallexample
235
bda144f4 236@need 3000
926a5166 237Now the screen looks like this:
b1b12a8e
RS
238
239@smallexample
240@group
241 column 35
3c29caa8
DH
242 __________
243 | | | line 0
b1b12a8e
RS
244 | w | w3 |
245 |___|______|
246 | | line 15
247 | w2 |
248 |__________|
249 line 50
250 column 0 column 80
251@end group
252@end smallexample
aeb2c306
JB
253
254Normally, Emacs indicates the border between two side-by-side windows
969fe9b5 255with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
aeb2c306
JB
256characters. The display table can specify alternative border
257characters; see @ref{Display Tables}.
b1b12a8e
RS
258@end deffn
259
8241495d 260@deffn Command split-window-vertically &optional size
1911e6e5 261This function splits the selected window into two windows, one above the
ebc6903b 262other, leaving the upper of the two windows selected, with @var{size}
1911e6e5
RS
263lines. (If @var{size} is negative, then the lower of the two windows
264gets @minus{} @var{size} lines and the upper window gets the rest, but
265the upper window is still the one selected.)
b1b12a8e
RS
266@end deffn
267
2468d0c0 268@deffn Command split-window-horizontally &optional size
b1b12a8e
RS
269This function splits the selected window into two windows
270side-by-side, leaving the selected window with @var{size} columns.
271
8241495d
RS
272This function is basically an interface to @code{split-window}.
273You could define a simplified version of the function like this:
b1b12a8e
RS
274
275@smallexample
276@group
277(defun split-window-horizontally (&optional arg)
278 "Split selected window into two windows, side by side..."
279 (interactive "P")
513331d3 280@end group
8241495d
RS
281@group
282 (let ((size (and arg (prefix-numeric-value arg))))
283 (and size (< size 0)
284 (setq size (+ (window-width) size)))
285 (split-window nil size t)))
b1b12a8e
RS
286@end group
287@end smallexample
288@end deffn
289
290@defun one-window-p &optional no-mini all-frames
291This function returns non-@code{nil} if there is only one window. The
292argument @var{no-mini}, if non-@code{nil}, means don't count the
293minibuffer even if it is active; otherwise, the minibuffer window is
eaac2be1 294included, if active, in the total number of windows, which is compared
b1b12a8e
RS
295against one.
296
297The argument @var{all-frames} specifies which frames to consider. Here
298are the possible values and their meanings:
299
300@table @asis
301@item @code{nil}
302Count the windows in the selected frame, plus the minibuffer used
303by that frame even if it lies in some other frame.
304
305@item @code{t}
306Count all windows in all existing frames.
307
308@item @code{visible}
309Count all windows in all visible frames.
310
bfe721d1
KH
311@item 0
312Count all windows in all visible or iconified frames.
313
b1b12a8e
RS
314@item anything else
315Count precisely the windows in the selected frame, and no others.
316@end table
317@end defun
318
319@node Deleting Windows
320@section Deleting Windows
321@cindex deleting windows
322
323A window remains visible on its frame unless you @dfn{delete} it by
324calling certain functions that delete windows. A deleted window cannot
325appear on the screen, but continues to exist as a Lisp object until
326there are no references to it. There is no way to cancel the deletion
327of a window aside from restoring a saved window configuration
328(@pxref{Window Configurations}). Restoring a window configuration also
329deletes any windows that aren't part of that configuration.
330
331 When you delete a window, the space it took up is given to one
969fe9b5 332adjacent sibling.
b1b12a8e
RS
333
334@c Emacs 19 feature
335@defun window-live-p window
336This function returns @code{nil} if @var{window} is deleted, and
337@code{t} otherwise.
338
b22f3a19 339@strong{Warning:} Erroneous information or fatal errors may result from
b1b12a8e
RS
340using a deleted window as if it were live.
341@end defun
342
343@deffn Command delete-window &optional window
969fe9b5
RS
344This function removes @var{window} from display, and returns @code{nil}.
345If @var{window} is omitted, then the selected window is deleted. An
346error is signaled if there is only one window when @code{delete-window}
347is called.
b1b12a8e
RS
348@end deffn
349
350@deffn Command delete-other-windows &optional window
351This function makes @var{window} the only window on its frame, by
352deleting the other windows in that frame. If @var{window} is omitted or
353@code{nil}, then the selected window is used by default.
354
969fe9b5 355The return value is @code{nil}.
b1b12a8e
RS
356@end deffn
357
358@deffn Command delete-windows-on buffer &optional frame
359This function deletes all windows showing @var{buffer}. If there are
360no windows showing @var{buffer}, it does nothing.
361
362@code{delete-windows-on} operates frame by frame. If a frame has
363several windows showing different buffers, then those showing
364@var{buffer} are removed, and the others expand to fill the space. If
365all windows in some frame are showing @var{buffer} (including the case
366where there is only one window), then the frame reverts to having a
367single window showing another buffer chosen with @code{other-buffer}.
368@xref{The Buffer List}.
369
1911e6e5
RS
370The argument @var{frame} controls which frames to operate on. This
371function does not use it in quite the same way as the other functions
372which scan all windows; specifically, the values @code{t} and @code{nil}
373have the opposite of their meanings in other functions. Here are the
374full details:
b1b12a8e
RS
375
376@itemize @bullet
377@item
1911e6e5 378If it is @code{nil}, operate on all frames.
b1b12a8e 379@item
1911e6e5 380If it is @code{t}, operate on the selected frame.
b1b12a8e
RS
381@item
382If it is @code{visible}, operate on all visible frames.
1911e6e5 383@item
bfe721d1 384If it is 0, operate on all visible or iconified frames.
b1b12a8e
RS
385@item
386If it is a frame, operate on that frame.
387@end itemize
388
389This function always returns @code{nil}.
390@end deffn
391
392@node Selecting Windows
393@section Selecting Windows
394@cindex selecting windows
395
396 When a window is selected, the buffer in the window becomes the current
397buffer, and the cursor will appear in it.
398
399@defun selected-window
400This function returns the selected window. This is the window in
401which the cursor appears and to which many commands apply.
402@end defun
403
5a8a6af8 404@defun select-window window &optional norecord
b1b12a8e
RS
405This function makes @var{window} the selected window. The cursor then
406appears in @var{window} (on redisplay). The buffer being displayed in
407@var{window} is immediately designated the current buffer.
408
5a8a6af8
RS
409Normally @var{window}'s selected buffer is moved to the front of the
410buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
411order is unchanged.
412
b1b12a8e
RS
413The return value is @var{window}.
414
415@example
416@group
417(setq w (next-window))
418(select-window w)
419 @result{} #<window 65 on windows.texi>
420@end group
421@end example
422@end defun
423
bfe721d1 424@defmac save-selected-window forms@dots{}
9258d604
RS
425This macro records the selected window of eac frame, executes
426@var{forms} in sequence, then restores the earlier selected windows.
427
428This macro does not save or restore anything about the sizes,
429arrangement or contents of windows; therefore, if the @var{forms}
430change them, the change persists. If the previously selected window
431of some frame is no longer live at the time of exit from this form,
432that frame's selected window is left alone.
bfe721d1
KH
433@end defmac
434
5a8a6af8
RS
435@defmac with-selected-window window forms@dots{}
436This macro selects @var{window} (without changing the buffer list),
437executes @var{forms} in sequence, then restores the previously
438selected window (unless that window is no longer alive). It is similar
439to @code{save-selected-window} except that it explicitly selects
440@var{window} and that it does not alter the buffer list sequence.
441@end defmac
442
b1b12a8e
RS
443@cindex finding windows
444 The following functions choose one of the windows on the screen,
445offering various criteria for the choice.
446
447@defun get-lru-window &optional frame
448This function returns the window least recently ``used'' (that is,
449selected). The selected window is always the most recently used window.
450
451The selected window can be the least recently used window if it is the
452only window. A newly created window becomes the least recently used
453window until it is selected. A minibuffer window is never a candidate.
454
c638661f 455The argument @var{frame} controls which windows are considered.
b1b12a8e
RS
456
457@itemize @bullet
458@item
459If it is @code{nil}, consider windows on the selected frame.
460@item
461If it is @code{t}, consider windows on all frames.
462@item
463If it is @code{visible}, consider windows on all visible frames.
464@item
bfe721d1
KH
465If it is 0, consider windows on all visible or iconified frames.
466@item
b1b12a8e
RS
467If it is a frame, consider windows on that frame.
468@end itemize
469@end defun
470
471@defun get-largest-window &optional frame
472This function returns the window with the largest area (height times
473width). If there are no side-by-side windows, then this is the window
474with the most lines. A minibuffer window is never a candidate.
475
476If there are two windows of the same size, then the function returns
c638661f 477the window that is first in the cyclic ordering of windows (see
b1b12a8e
RS
478following section), starting from the selected window.
479
1911e6e5
RS
480The argument @var{frame} controls which set of windows to
481consider. See @code{get-lru-window}, above.
b1b12a8e
RS
482@end defun
483
1e8ca3a9
EZ
484@cindex window that satisfies a predicate
485@cindex conditional selection of windows
486@defun get-window-with-predicate predicate &optional minibuf all-frames default
487This function returns a window satisfying @var{predicate}. It cycles
488through all visible windows using @code{walk-windows} (@pxref{Cyclic
b0d4743a 489Window Ordering}), calling @var{predicate} on each one of them
1e8ca3a9
EZ
490with that window as its argument. The function returns the first
491window for which @var{predicate} returns a non-@code{nil} value; if
492that never happens, it returns @var{default}.
493
494The optional arguments @var{minibuf} and @var{all-frames} specify the
495set of windows to include in the scan. See the description of
496@code{next-window} in @ref{Cyclic Window Ordering}, for details.
497@end defun
498
b1b12a8e
RS
499@node Cyclic Window Ordering
500@comment node-name, next, previous, up
501@section Cyclic Ordering of Windows
502@cindex cyclic ordering of windows
503@cindex ordering of windows, cyclic
3c29caa8 504@cindex window ordering, cyclic
b1b12a8e
RS
505
506 When you use the command @kbd{C-x o} (@code{other-window}) to select
507the next window, it moves through all the windows on the screen in a
508specific cyclic order. For any given configuration of windows, this
509order never varies. It is called the @dfn{cyclic ordering of windows}.
510
511 This ordering generally goes from top to bottom, and from left to
512right. But it may go down first or go right first, depending on the
513order in which the windows were split.
514
515 If the first split was vertical (into windows one above each other),
516and then the subwindows were split horizontally, then the ordering is
517left to right in the top of the frame, and then left to right in the
518next lower part of the frame, and so on. If the first split was
519horizontal, the ordering is top to bottom in the left part, and so on.
520In general, within each set of siblings at any level in the window tree,
521the order is left to right, or top to bottom.
522
523@defun next-window &optional window minibuf all-frames
524@cindex minibuffer window
525This function returns the window following @var{window} in the cyclic
c638661f
RS
526ordering of windows. This is the window that @kbd{C-x o} would select
527if typed when @var{window} is selected. If @var{window} is the only
b1b12a8e
RS
528window visible, then this function returns @var{window}. If omitted,
529@var{window} defaults to the selected window.
530
531The value of the argument @var{minibuf} determines whether the
532minibuffer is included in the window order. Normally, when
533@var{minibuf} is @code{nil}, the minibuffer is included if it is
534currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
535window is active while the minibuffer is in use. @xref{Minibuffers}.)
536
537If @var{minibuf} is @code{t}, then the cyclic ordering includes the
538minibuffer window even if it is not active.
539
540If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
541window is not included even if it is active.
542
543The argument @var{all-frames} specifies which frames to consider. Here
544are the possible values and their meanings:
545
546@table @asis
547@item @code{nil}
548Consider all the windows in @var{window}'s frame, plus the minibuffer
549used by that frame even if it lies in some other frame.
550
551@item @code{t}
552Consider all windows in all existing frames.
553
554@item @code{visible}
555Consider all windows in all visible frames. (To get useful results, you
556must ensure @var{window} is in a visible frame.)
557
83abd543 558@item 0
bfe721d1
KH
559Consider all windows in all visible or iconified frames.
560
b1b12a8e
RS
561@item anything else
562Consider precisely the windows in @var{window}'s frame, and no others.
563@end table
564
3c29caa8 565This example assumes there are two windows, both displaying the
b1b12a8e
RS
566buffer @samp{windows.texi}:
567
568@example
569@group
570(selected-window)
571 @result{} #<window 56 on windows.texi>
572@end group
573@group
574(next-window (selected-window))
575 @result{} #<window 52 on windows.texi>
576@end group
577@group
578(next-window (next-window (selected-window)))
579 @result{} #<window 56 on windows.texi>
580@end group
581@end example
582@end defun
583
584@defun previous-window &optional window minibuf all-frames
585This function returns the window preceding @var{window} in the cyclic
586ordering of windows. The other arguments specify which windows to
587include in the cycle, as in @code{next-window}.
588@end defun
589
8241495d 590@deffn Command other-window count &optional all-frames
b1b12a8e 591This function selects the @var{count}th following window in the cyclic
969fe9b5
RS
592order. If count is negative, then it moves back @minus{}@var{count}
593windows in the cycle, rather than forward. It returns @code{nil}.
b1b12a8e 594
75708135 595The argument @var{all-frames} has the same meaning as in
8241495d
RS
596@code{next-window}, but the @var{minibuf} argument of @code{next-window}
597is always effectively @code{nil}.
598
b1b12a8e
RS
599In an interactive call, @var{count} is the numeric prefix argument.
600@end deffn
601
602@c Emacs 19 feature
603@defun walk-windows proc &optional minibuf all-frames
604This function cycles through all windows, calling @code{proc}
605once for each window with the window as its sole argument.
606
607The optional arguments @var{minibuf} and @var{all-frames} specify the
608set of windows to include in the scan. See @code{next-window}, above,
609for details.
610@end defun
611
e258eedc
GM
612@defun window-list &optional frame minibuf window
613This function returns a list of the windows on @var{frame}, starting
614with @var{window}. If @var{frame} is @code{nil} or omitted, the
615selected frame is used instead; if @var{window} is @code{nil} or
616omitted, the selected window is used instead.
617
618The value of @var{minibuf} determines if the minibuffer window will be
619included in the result list. If @var{minibuf} is @code{t}, the
620minibuffer window will be included, even if it isn't active. If
429994d8 621@var{minibuf} is @code{nil} or omitted, the minibuffer window will
e258eedc
GM
622only be included in the list if it is active. If @var{minibuf} is
623neither @code{nil} nor @code{t}, the minibuffer window is not
624included, whether or not it is active.
429994d8 625@end defun
e258eedc 626
b1b12a8e
RS
627@node Buffers and Windows
628@section Buffers and Windows
629@cindex examining windows
630@cindex windows, controlling precisely
631@cindex buffers, controlled in windows
632
633 This section describes low-level functions to examine windows or to
634display buffers in windows in a precisely controlled fashion.
635@iftex
636See the following section for
637@end iftex
37680279 638@ifnottex
b1b12a8e 639@xref{Displaying Buffers}, for
37680279 640@end ifnottex
b1b12a8e
RS
641related functions that find a window to use and specify a buffer for it.
642The functions described there are easier to use than these, but they
643employ heuristics in choosing or creating a window; use these functions
644when you need complete control.
645
6ab4745b 646@defun set-window-buffer window buffer-or-name &optional keep-margins
b1b12a8e 647This function makes @var{window} display @var{buffer-or-name} as its
a9f0a989
RS
648contents. It returns @code{nil}. This is the fundamental primitive
649for changing which buffer is displayed in a window, and all ways
650of doing that call this function.
b1b12a8e
RS
651
652@example
653@group
654(set-window-buffer (selected-window) "foo")
655 @result{} nil
656@end group
657@end example
6ab4745b
RS
658
659Normally, displaying @var{buffer} in @var{window} resets the window's
660fringe widths and position based on the local variables of @var{buffer}.
661However, if @var{keep-margins} is non-@code{nil}, the fringe widths and
662position of @var{window} remain unchanged. @xref{Fringes}.
b1b12a8e
RS
663@end defun
664
665@defun window-buffer &optional window
666This function returns the buffer that @var{window} is displaying. If
667@var{window} is omitted, this function returns the buffer for the
668selected window.
669
670@example
671@group
672(window-buffer)
673 @result{} #<buffer windows.texi>
674@end group
675@end example
676@end defun
677
678@defun get-buffer-window buffer-or-name &optional all-frames
679This function returns a window currently displaying
680@var{buffer-or-name}, or @code{nil} if there is none. If there are
681several such windows, then the function returns the first one in the
682cyclic ordering of windows, starting from the selected window.
683@xref{Cyclic Window Ordering}.
684
685The argument @var{all-frames} controls which windows to consider.
686
687@itemize @bullet
688@item
689If it is @code{nil}, consider windows on the selected frame.
690@item
691If it is @code{t}, consider windows on all frames.
692@item
693If it is @code{visible}, consider windows on all visible frames.
694@item
bfe721d1
KH
695If it is 0, consider windows on all visible or iconified frames.
696@item
b1b12a8e
RS
697If it is a frame, consider windows on that frame.
698@end itemize
699@end defun
700
3c29caa8
DH
701@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
702This function returns a list of all the windows currently displaying
703@var{buffer-or-name}.
704
705The two optional arguments work like the optional arguments of
706@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
707like the single optional argument of @code{get-buffer-window}. Perhaps
708we should change @code{get-buffer-window} in the future to make it
709compatible with the other functions.
710
711The argument @var{all-frames} controls which windows to consider.
712
713@itemize @bullet
714@item
715If it is @code{nil}, consider windows on the selected frame.
716@item
717If it is @code{t}, consider windows on all frames.
718@item
719If it is @code{visible}, consider windows on all visible frames.
720@item
721If it is 0, consider windows on all visible or iconified frames.
722@item
723If it is a frame, consider windows on that frame.
724@end itemize
725@end defun
726
a9f0a989 727@defvar buffer-display-time
a9f0a989
RS
728This variable records the time at which a buffer was last made visible
729in a window. It is always local in each buffer; each time
730@code{set-window-buffer} is called, it sets this variable to
731@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
1911e6e5 732When a buffer is first created, @code{buffer-display-time} starts out
a9f0a989
RS
733with the value @code{nil}.
734@end defvar
735
b1b12a8e
RS
736@node Displaying Buffers
737@section Displaying Buffers in Windows
738@cindex switching to a buffer
739@cindex displaying a buffer
740
741 In this section we describe convenient functions that choose a window
742automatically and use it to display a specified buffer. These functions
743can also split an existing window in certain circumstances. We also
744describe variables that parameterize the heuristics used for choosing a
745window.
746@iftex
747See the preceding section for
748@end iftex
37680279 749@ifnottex
b1b12a8e 750@xref{Buffers and Windows}, for
37680279 751@end ifnottex
a9f0a989
RS
752low-level functions that give you more precise control. All of these
753functions work by calling @code{set-window-buffer}.
b1b12a8e
RS
754
755 Do not use the functions in this section in order to make a buffer
756current so that a Lisp program can access or modify it; they are too
757drastic for that purpose, since they change the display of buffers in
969fe9b5 758windows, which would be gratuitous and surprise the user. Instead, use
1911e6e5
RS
759@code{set-buffer} and @code{save-current-buffer} (@pxref{Current
760Buffer}), which designate buffers as current for programmed access
761without affecting the display of buffers in windows.
b1b12a8e
RS
762
763@deffn Command switch-to-buffer buffer-or-name &optional norecord
764This function makes @var{buffer-or-name} the current buffer, and also
765displays the buffer in the selected window. This means that a human can
766see the buffer and subsequent keyboard commands will apply to it.
767Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
768the current buffer but does not display it in the selected window.
769@xref{Current Buffer}.
770
22697dac
KH
771If @var{buffer-or-name} does not identify an existing buffer, then a new
772buffer by that name is created. The major mode for the new buffer is
773set according to the variable @code{default-major-mode}. @xref{Auto
774Major Mode}.
b1b12a8e 775
969fe9b5
RS
776Normally the specified buffer is put at the front of the buffer list
777(both the selected frame's buffer list and the frame-independent buffer
778list). This affects the operation of @code{other-buffer}. However, if
b1b12a8e
RS
779@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
780List}.
781
782The @code{switch-to-buffer} function is often used interactively, as
783the binding of @kbd{C-x b}. It is also used frequently in programs. It
996d82f8 784returns the buffer that it switched to.
b1b12a8e
RS
785@end deffn
786
f9f59935 787@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
b1b12a8e
RS
788This function makes @var{buffer-or-name} the current buffer and
789displays it in a window not currently selected. It then selects that
790window. The handling of the buffer is the same as in
791@code{switch-to-buffer}.
792
c638661f
RS
793The currently selected window is absolutely never used to do the job.
794If it is the only window, then it is split to make a distinct window for
795this purpose. If the selected window is already displaying the buffer,
796then it continues to do so, but another window is nonetheless found to
797display it in as well.
f9f59935
RS
798
799This function updates the buffer list just like @code{switch-to-buffer}
800unless @var{norecord} is non-@code{nil}.
b1b12a8e
RS
801@end deffn
802
f9f59935 803@defun pop-to-buffer buffer-or-name &optional other-window norecord
b1b12a8e
RS
804This function makes @var{buffer-or-name} the current buffer and
805switches to it in some window, preferably not the window previously
806selected. The ``popped-to'' window becomes the selected window within
996d82f8 807its frame. The return value is the buffer that was switched to.
b1b12a8e
RS
808
809If the variable @code{pop-up-frames} is non-@code{nil},
810@code{pop-to-buffer} looks for a window in any visible frame already
811displaying the buffer; if there is one, it returns that window and makes
812it be selected within its frame. If there is none, it creates a new
813frame and displays the buffer in it.
814
815If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
816operates entirely within the selected frame. (If the selected frame has
817just a minibuffer, @code{pop-to-buffer} operates within the most
818recently selected frame that was not just a minibuffer.)
819
820If the variable @code{pop-up-windows} is non-@code{nil}, windows may
821be split to create a new window that is different from the original
822window. For details, see @ref{Choosing Window}.
823
824If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
825creates another window even if @var{buffer-or-name} is already visible
826in the selected window. Thus @var{buffer-or-name} could end up
827displayed in two windows. On the other hand, if @var{buffer-or-name} is
828already displayed in the selected window and @var{other-window} is
829@code{nil}, then the selected window is considered sufficient display
830for @var{buffer-or-name}, so that nothing needs to be done.
831
bfe721d1
KH
832All the variables that affect @code{display-buffer} affect
833@code{pop-to-buffer} as well. @xref{Choosing Window}.
834
b1b12a8e 835If @var{buffer-or-name} is a string that does not name an existing
22697dac
KH
836buffer, a buffer by that name is created. The major mode for the new
837buffer is set according to the variable @code{default-major-mode}.
838@xref{Auto Major Mode}.
f9f59935
RS
839
840This function updates the buffer list just like @code{switch-to-buffer}
841unless @var{norecord} is non-@code{nil}.
b1b12a8e
RS
842@end defun
843
bfe721d1
KH
844@deffn Command replace-buffer-in-windows buffer
845This function replaces @var{buffer} with some other buffer in all
846windows displaying it. The other buffer used is chosen with
847@code{other-buffer}. In the usual applications of this function, you
848don't care which other buffer is used; you just want to make sure that
849@var{buffer} is no longer displayed.
850
851This function returns @code{nil}.
852@end deffn
853
b1b12a8e
RS
854@node Choosing Window
855@section Choosing a Window for Display
856
c638661f 857 This section describes the basic facility that chooses a window to
b1b12a8e
RS
858display a buffer in---@code{display-buffer}. All the higher-level
859functions and commands use this subroutine. Here we describe how to use
860@code{display-buffer} and how to customize it.
861
f9f59935 862@deffn Command display-buffer buffer-or-name &optional not-this-window frame
b1b12a8e
RS
863This command makes @var{buffer-or-name} appear in some window, like
864@code{pop-to-buffer}, but it does not select that window and does not
865make the buffer current. The identity of the selected window is
866unaltered by this function.
867
868If @var{not-this-window} is non-@code{nil}, it means to display the
869specified buffer in a window other than the selected one, even if it is
870already on display in the selected window. This can cause the buffer to
871appear in two windows at once. Otherwise, if @var{buffer-or-name} is
872already being displayed in any window, that is good enough, so this
873function does nothing.
874
875@code{display-buffer} returns the window chosen to display
876@var{buffer-or-name}.
877
f9f59935 878If the argument @var{frame} is non-@code{nil}, it specifies which frames
1911e6e5
RS
879to check when deciding whether the buffer is already displayed. If the
880buffer is already displayed in some window on one of these frames,
881@code{display-buffer} simply returns that window. Here are the possible
882values of @var{frame}:
883
884@itemize @bullet
885@item
886If it is @code{nil}, consider windows on the selected frame.
887@item
888If it is @code{t}, consider windows on all frames.
889@item
890If it is @code{visible}, consider windows on all visible frames.
891@item
892If it is 0, consider windows on all visible or iconified frames.
893@item
894If it is a frame, consider windows on that frame.
895@end itemize
f9f59935 896
b1b12a8e
RS
897Precisely how @code{display-buffer} finds or creates a window depends on
898the variables described below.
899@end deffn
900
704bdba1
GM
901@defopt display-buffer-reuse-frames
902If this variable is non-@code{nil}, @code{display-buffer} searches
903existing frames for a window displaying the buffer. If the buffer is
904already displayed in a window in some frame, @code{display-buffer} makes
905the frame visible and raises it, to use that window. If the buffer is
906not already displayed, or if @code{display-buffer-reuse-frames} is
907@code{nil}, @code{display-buffer}'s behavior is determined by other
908variables, described below.
909@end defopt
910
b1b12a8e
RS
911@defopt pop-up-windows
912This variable controls whether @code{display-buffer} makes new windows.
913If it is non-@code{nil} and there is only one window, then that window
914is split. If it is @code{nil}, then @code{display-buffer} does not
915split the single window, but uses it whole.
916@end defopt
917
918@defopt split-height-threshold
919This variable determines when @code{display-buffer} may split a window,
920if there are multiple windows. @code{display-buffer} always splits the
921largest window if it has at least this many lines. If the largest
922window is not this tall, it is split only if it is the sole window and
923@code{pop-up-windows} is non-@code{nil}.
924@end defopt
925
4f0308e1
GM
926@defopt even-window-heights
927This variable determines if @code{display-buffer} should even out window
928heights if the buffer gets displayed in an existing window, above or
929beneath another existing window. If @code{even-window-heights} is
930@code{t}, the default, window heights will be evened out. If
5fe3b9bc 931@code{even-window-heights} is @code{nil}, the original window heights
4f0308e1 932will be left alone.
fbd9f276 933@end defopt
4f0308e1 934
b1b12a8e
RS
935@c Emacs 19 feature
936@defopt pop-up-frames
937This variable controls whether @code{display-buffer} makes new frames.
938If it is non-@code{nil}, @code{display-buffer} looks for an existing
939window already displaying the desired buffer, on any visible frame. If
940it finds one, it returns that window. Otherwise it makes a new frame.
941The variables @code{pop-up-windows} and @code{split-height-threshold} do
942not matter if @code{pop-up-frames} is non-@code{nil}.
943
944If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
945splits a window or reuses one.
946
947@xref{Frames}, for more information.
948@end defopt
949
950@c Emacs 19 feature
951@defvar pop-up-frame-function
952This variable specifies how to make a new frame if @code{pop-up-frames}
953is non-@code{nil}.
954
955Its value should be a function of no arguments. When
956@code{display-buffer} makes a new frame, it does so by calling that
957function, which should return a frame. The default value of the
c638661f 958variable is a function that creates a frame using parameters from
b1b12a8e
RS
959@code{pop-up-frame-alist}.
960@end defvar
961
8241495d 962@defopt pop-up-frame-alist
b1b12a8e
RS
963This variable holds an alist specifying frame parameters used when
964@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
965more information about frame parameters.
8241495d 966@end defopt
b1b12a8e 967
1911e6e5 968@defopt special-display-buffer-names
c2264295
RS
969A list of buffer names for buffers that should be displayed specially.
970If the buffer's name is in this list, @code{display-buffer} handles the
971buffer specially.
972
973By default, special display means to give the buffer a dedicated frame.
bfe721d1
KH
974
975If an element is a list, instead of a string, then the @sc{car} of the
c1f21754
RS
976list is the buffer name, and the rest of the list says how to create
977the frame. There are two possibilities for the rest of the list (its
978@sc{cdr}). It can be an alist, specifying frame parameters, or it can
979contain a function and arguments to give to it. (The function's first
980argument is always the buffer to be displayed; the arguments from the
981list come after that.)
982
983For example:
984
985@example
986(("myfile" (minibuffer) (menu-bar-lines . 0)))
987@end example
988
989@noindent
990specifies to display a buffer named @samp{myfile} in a dedicated frame
991with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
1911e6e5 992@end defopt
c2264295 993
1911e6e5 994@defopt special-display-regexps
c2264295
RS
995A list of regular expressions that specify buffers that should be
996displayed specially. If the buffer's name matches any of the regular
997expressions in this list, @code{display-buffer} handles the buffer
998specially.
999
1000By default, special display means to give the buffer a dedicated frame.
bfe721d1
KH
1001
1002If an element is a list, instead of a string, then the @sc{car} of the
1003list is the regular expression, and the rest of the list says how to
1004create the frame. See above, under @code{special-display-buffer-names}.
1911e6e5 1005@end defopt
c2264295
RS
1006
1007@defvar special-display-function
1008This variable holds the function to call to display a buffer specially.
1009It receives the buffer as an argument, and should return the window in
1010which it is displayed.
1011
1012The default value of this variable is
1013@code{special-display-popup-frame}.
1014@end defvar
1015
8241495d 1016@defun special-display-popup-frame buffer &rest args
c2264295
RS
1017This function makes @var{buffer} visible in a frame of its own. If
1018@var{buffer} is already displayed in a window in some frame, it makes
1019the frame visible and raises it, to use that window. Otherwise, it
1020creates a frame that will be dedicated to @var{buffer}.
c638661f 1021
8241495d
RS
1022If @var{args} is an alist, it specifies frame parameters for the new
1023frame.
1024
1025If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
1026@var{args})} is called as a function to actually create and set up the
1027frame; it is called with @var{buffer} as first argument, and @code{(cdr
1028@var{args})} as additional arguments.
1029
1030This function always uses an existing window displaying @var{buffer},
1031whether or not it is in a frame of its own; but if you set up the above
1032variables in your init file, before @var{buffer} was created, then
1033presumably the window was previously made by this function.
c2264295
RS
1034@end defun
1035
1036@defopt special-display-frame-alist
1037This variable holds frame parameters for
1038@code{special-display-popup-frame} to use when it creates a frame.
1039@end defopt
1040
864bd34b 1041@defopt same-window-buffer-names
bfe721d1
KH
1042A list of buffer names for buffers that should be displayed in the
1043selected window. If the buffer's name is in this list,
1044@code{display-buffer} handles the buffer by switching to it in the
1045selected window.
864bd34b 1046@end defopt
bfe721d1 1047
864bd34b 1048@defopt same-window-regexps
bfe721d1
KH
1049A list of regular expressions that specify buffers that should be
1050displayed in the selected window. If the buffer's name matches any of
1051the regular expressions in this list, @code{display-buffer} handles the
1052buffer by switching to it in the selected window.
864bd34b 1053@end defopt
bfe721d1 1054
b1b12a8e
RS
1055@c Emacs 19 feature
1056@defvar display-buffer-function
1057This variable is the most flexible way to customize the behavior of
1058@code{display-buffer}. If it is non-@code{nil}, it should be a function
1059that @code{display-buffer} calls to do the work. The function should
1060accept two arguments, the same two arguments that @code{display-buffer}
1061received. It should choose or create a window, display the specified
1062buffer, and then return the window.
1063
1064This hook takes precedence over all the other options and hooks
1065described above.
1066@end defvar
1067
1068@c Emacs 19 feature
1069@cindex dedicated window
1070A window can be marked as ``dedicated'' to its buffer. Then
969fe9b5
RS
1071@code{display-buffer} will not try to use that window to display any
1072other buffer.
b1b12a8e
RS
1073
1074@defun window-dedicated-p window
1075This function returns @code{t} if @var{window} is marked as dedicated;
1076otherwise @code{nil}.
1077@end defun
1078
1079@defun set-window-dedicated-p window flag
1080This function marks @var{window} as dedicated if @var{flag} is
1081non-@code{nil}, and nondedicated otherwise.
1082@end defun
1083
1084@node Window Point
1085@section Windows and Point
1086@cindex window position
1087@cindex window point
1088@cindex position in window
1089@cindex point in window
1090
1091 Each window has its own value of point, independent of the value of
1092point in other windows displaying the same buffer. This makes it useful
1093to have multiple windows showing one buffer.
1094
1095@itemize @bullet
1096@item
1097The window point is established when a window is first created; it is
1098initialized from the buffer's point, or from the window point of another
1099window opened on the buffer if such a window exists.
1100
1101@item
f9f59935
RS
1102Selecting a window sets the value of point in its buffer from the
1103window's value of point. Conversely, deselecting a window sets the
1104window's value of point from that of the buffer. Thus, when you switch
1105between windows that display a given buffer, the point value for the
1106selected window is in effect in the buffer, while the point values for
1107the other windows are stored in those windows.
b1b12a8e
RS
1108
1109@item
1110As long as the selected window displays the current buffer, the window's
1111point and the buffer's point always move together; they remain equal.
1112
1113@item
1114@xref{Positions}, for more details on buffer positions.
1115@end itemize
1116
1117 As far as the user is concerned, point is where the cursor is, and
1118when the user switches to another buffer, the cursor jumps to the
1119position of point in that buffer.
1120
8241495d 1121@defun window-point &optional window
b1b12a8e
RS
1122This function returns the current position of point in @var{window}.
1123For a nonselected window, this is the value point would have (in that
8241495d
RS
1124window's buffer) if that window were selected. If @var{window} is
1125@code{nil}, the selected window is used.
b1b12a8e
RS
1126
1127When @var{window} is the selected window and its buffer is also the
1128current buffer, the value returned is the same as point in that buffer.
1129
1130Strictly speaking, it would be more correct to return the
1131``top-level'' value of point, outside of any @code{save-excursion}
1132forms. But that value is hard to find.
1133@end defun
1134
1135@defun set-window-point window position
1136This function positions point in @var{window} at position
1137@var{position} in @var{window}'s buffer.
1138@end defun
1139
1140@node Window Start
1141@section The Window Start Position
1142
1143 Each window contains a marker used to keep track of a buffer position
c638661f 1144that specifies where in the buffer display should start. This position
b1b12a8e
RS
1145is called the @dfn{display-start} position of the window (or just the
1146@dfn{start}). The character after this position is the one that appears
1147at the upper left corner of the window. It is usually, but not
1148inevitably, at the beginning of a text line.
1149
1150@defun window-start &optional window
1151@cindex window top line
1152This function returns the display-start position of window
1153@var{window}. If @var{window} is @code{nil}, the selected window is
3c29caa8 1154used. For example,
b1b12a8e
RS
1155
1156@example
1157@group
1158(window-start)
1159 @result{} 7058
1160@end group
1161@end example
1162
c638661f 1163When you create a window, or display a different buffer in it, the
b1b12a8e
RS
1164display-start position is set to a display-start position recently used
1165for the same buffer, or 1 if the buffer doesn't have any.
1166
ea951766 1167Redisplay updates the window-start position (if you have not specified
8241495d
RS
1168it explicitly since the previous redisplay)---for example, to make sure
1169point appears on the screen. Nothing except redisplay automatically
1170changes the window-start position; if you move point, do not expect the
1171window-start position to change in response until after the next
1172redisplay.
ea951766
RS
1173
1174For a realistic example of using @code{window-start}, see the
1175description of @code{count-lines} in @ref{Text Lines}.
b1b12a8e
RS
1176@end defun
1177
969fe9b5 1178@defun window-end &optional window update
b1b12a8e
RS
1179This function returns the position of the end of the display in window
1180@var{window}. If @var{window} is @code{nil}, the selected window is
1181used.
c638661f 1182
6c7418db
RS
1183Simply changing the buffer text or moving point does not update the
1184value that @code{window-end} returns. The value is updated only when
969fe9b5 1185Emacs redisplays and redisplay completes without being preempted.
6c7418db 1186
c638661f 1187If the last redisplay of @var{window} was preempted, and did not finish,
a283f4a3 1188Emacs does not know the position of the end of display in that window.
969fe9b5 1189In that case, this function returns @code{nil}.
c638661f 1190
41448f63
RS
1191If @var{update} is non-@code{nil}, @code{window-end} always returns an
1192up-to-date value for where the window ends, based on the current
1193@code{window-start} value. If the saved value is valid,
1194@code{window-end} returns that; otherwise it computes the correct
969fe9b5 1195value by scanning the buffer text.
41448f63
RS
1196
1197Even if @var{update} is non-@code{nil}, @code{window-end} does not
1198attempt to scroll the display if point has moved off the screen, the
1199way real redisplay would do. It does not alter the
1200@code{window-start} value. In effect, it reports where the displayed
1201text will end if scrolling is not required.
b1b12a8e
RS
1202@end defun
1203
1204@defun set-window-start window position &optional noforce
1205This function sets the display-start position of @var{window} to
c638661f 1206@var{position} in @var{window}'s buffer. It returns @var{position}.
b1b12a8e
RS
1207
1208The display routines insist that the position of point be visible when a
1209buffer is displayed. Normally, they change the display-start position
1210(that is, scroll the window) whenever necessary to make point visible.
1211However, if you specify the start position with this function using
1212@code{nil} for @var{noforce}, it means you want display to start at
1213@var{position} even if that would put the location of point off the
1214screen. If this does place point off screen, the display routines move
1215point to the left margin on the middle line in the window.
1216
1217For example, if point @w{is 1} and you set the start of the window @w{to
12182}, then point would be ``above'' the top of the window. The display
1219routines will automatically move point if it is still 1 when redisplay
1220occurs. Here is an example:
1221
1222@example
1223@group
1224;; @r{Here is what @samp{foo} looks like before executing}
1225;; @r{the @code{set-window-start} expression.}
1226@end group
1227
1228@group
1229---------- Buffer: foo ----------
1230@point{}This is the contents of buffer foo.
12312
12323
12334
12345
12356
1236---------- Buffer: foo ----------
1237@end group
1238
1239@group
1240(set-window-start
1241 (selected-window)
1242 (1+ (window-start)))
1243@result{} 2
1244@end group
1245
1246@group
1247;; @r{Here is what @samp{foo} looks like after executing}
1248;; @r{the @code{set-window-start} expression.}
1249---------- Buffer: foo ----------
1250his is the contents of buffer foo.
12512
12523
1253@point{}4
12545
12556
1256---------- Buffer: foo ----------
1257@end group
1258@end example
1259
1260If @var{noforce} is non-@code{nil}, and @var{position} would place point
1261off screen at the next redisplay, then redisplay computes a new window-start
1262position that works well with point, and thus @var{position} is not used.
b1b12a8e
RS
1263@end defun
1264
00480554 1265@defun pos-visible-in-window-p &optional position window partially
601bda2e 1266This function returns @code{t} if @var{position} is within the range of
00480554
MB
1267text currently visible on the screen in @var{window}. It returns
1268@code{nil} if @var{position} is scrolled vertically or horizontally out
1269of view. Locations that are partially obscured are not considered
1270visible unless @var{partially} is non-@code{nil}. The argument
1271@var{position} defaults to the current position of point in
1272@var{window}; @var{window}, to the selected window.
1273
1274Here is an example:
b1b12a8e
RS
1275
1276@example
1277@group
1278(or (pos-visible-in-window-p
1279 (point) (selected-window))
1280 (recenter 0))
1281@end group
1282@end example
b1b12a8e
RS
1283@end defun
1284
8241495d
RS
1285@node Textual Scrolling
1286@section Textual Scrolling
1287@cindex textual scrolling
1288@cindex scrolling textually
1289
1290 @dfn{Textual scrolling} means moving the text up or down though a
1291window. It works by changing the value of the window's display-start
1292location. It may also change the value of @code{window-point} to keep
1293point on the screen.
b1b12a8e 1294
8241495d
RS
1295 Textual scrolling was formerly called ``vertical scrolling,'' but we
1296changed its name to distinguish it from the new vertical fractional
1297scrolling feature (@pxref{Vertical Scrolling}).
b1b12a8e
RS
1298
1299 In the commands @code{scroll-up} and @code{scroll-down}, the directions
1300``up'' and ``down'' refer to the motion of the text in the buffer at which
1301you are looking through the window. Imagine that the text is
1302written on a long roll of paper and that the scrolling commands move the
1303paper up and down. Thus, if you are looking at text in the middle of a
1304buffer and repeatedly call @code{scroll-down}, you will eventually see
1305the beginning of the buffer.
1306
1307 Some people have urged that the opposite convention be used: they
1308imagine that the window moves over text that remains in place. Then
1309``down'' commands would take you to the end of the buffer. This view is
1310more consistent with the actual relationship between windows and the
1311text in the buffer, but it is less like what the user sees. The
1312position of a window on the terminal does not move, and short scrolling
1313commands clearly move the text up or down on the screen. We have chosen
1314names that fit the user's point of view.
1315
8241495d
RS
1316 The textual scrolling functions (aside from
1317@code{scroll-other-window}) have unpredictable results if the current
1318buffer is different from the buffer that is displayed in the selected
1319window. @xref{Current Buffer}.
b1b12a8e
RS
1320
1321@deffn Command scroll-up &optional count
1322This function scrolls the text in the selected window upward
1323@var{count} lines. If @var{count} is negative, scrolling is actually
1324downward.
1325
1326If @var{count} is @code{nil} (or omitted), then the length of scroll
1327is @code{next-screen-context-lines} lines less than the usable height of
1328the window (not counting its mode line).
1329
1330@code{scroll-up} returns @code{nil}.
1331@end deffn
1332
1333@deffn Command scroll-down &optional count
1334This function scrolls the text in the selected window downward
1335@var{count} lines. If @var{count} is negative, scrolling is actually
1336upward.
1337
1338If @var{count} is omitted or @code{nil}, then the length of the scroll
1339is @code{next-screen-context-lines} lines less than the usable height of
c638661f 1340the window (not counting its mode line).
b1b12a8e
RS
1341
1342@code{scroll-down} returns @code{nil}.
1343@end deffn
1344
1345@deffn Command scroll-other-window &optional count
1346This function scrolls the text in another window upward @var{count}
1347lines. Negative values of @var{count}, or @code{nil}, are handled
1348as in @code{scroll-up}.
1349
8241495d
RS
1350You can specify which buffer to scroll by setting the variable
1351@code{other-window-scroll-buffer} to a buffer. If that buffer isn't
1352already displayed, @code{scroll-other-window} displays it in some
1353window.
1354
1355When the selected window is the minibuffer, the next window is normally
1356the one at the top left corner. You can specify a different window to
1357scroll, when the minibuffer is selected, by setting the variable
b1b12a8e
RS
1358@code{minibuffer-scroll-window}. This variable has no effect when any
1359other window is selected. @xref{Minibuffer Misc}.
1360
1361When the minibuffer is active, it is the next window if the selected
1362window is the one at the bottom right corner. In this case,
1363@code{scroll-other-window} attempts to scroll the minibuffer. If the
1364minibuffer contains just one line, it has nowhere to scroll to, so the
1365line reappears after the echo area momentarily displays the message
1366``Beginning of buffer''.
1367@end deffn
1368
1369@c Emacs 19 feature
1370@defvar other-window-scroll-buffer
1371If this variable is non-@code{nil}, it tells @code{scroll-other-window}
1372which buffer to scroll.
1373@end defvar
1374
1911e6e5
RS
1375@defopt scroll-margin
1376This option specifies the size of the scroll margin---a minimum number
1377of lines between point and the top or bottom of a window. Whenever
1378point gets within this many lines of the top or bottom of the window,
ac7845fd
RS
1379redisplay scrolls the text automatically (if possible) to move point
1380out of the margin, closer to the center of the window.
1911e6e5
RS
1381@end defopt
1382
1911e6e5 1383@defopt scroll-conservatively
b1b12a8e 1384This variable controls how scrolling is done automatically when point
ac7845fd
RS
1385moves off the screen (or into the scroll margin). If the value is a
1386positive integer @var{n}, then redisplay scrolls the text up to
1387@var{n} lines in either direction, if that will bring point back into
1388proper view. This action is called @dfn{conservative scrolling}.
1389Otherwise, scrolling happens in the usual way, under the control of
1390other variables such as @code{scroll-up-aggressively} and
1391@code{scroll-down-aggressively}.
1392
1393The default value is zero, which means that conservative scrolling
1394never happens.
1911e6e5
RS
1395@end defopt
1396
9db0af9e
RS
1397@defopt scroll-down-aggressively
1398@tindex scroll-down-aggressively
04c1025b
GM
1399The value of this variable should be either @code{nil} or a fraction
1400@var{f} between 0 and 1. If it is a fraction, that specifies where on
9db0af9e
RS
1401the screen to put point when scrolling down. More precisely, when a
1402window scrolls down because point is above the window start, the new
1403start position is chosen to put point @var{f} part of the window
1404height from the top. The larger @var{f}, the more aggressive the
1405scrolling.
04c1025b 1406
2468d0c0
DL
1407A value of @code{nil} is equivalent to .5, since its effect is to center
1408point. This variable automatically becomes buffer-local when set in any
1409fashion.
04c1025b
GM
1410@end defopt
1411
9db0af9e
RS
1412@defopt scroll-up-aggressively
1413@tindex scroll-up-aggressively
1414Likewise, for scrolling up. The value, @var{f}, specifies how far
04c1025b
GM
1415point should be placed from the bottom of the window; thus, as with
1416@code{scroll-up-aggressively}, a larger value scrolls more aggressively.
1417@end defopt
1418
1911e6e5
RS
1419@defopt scroll-step
1420This variable is an older variant of @code{scroll-conservatively}. The
1421difference is that it if its value is @var{n}, that permits scrolling
1422only by precisely @var{n} lines, not a smaller number. This feature
1423does not work with @code{scroll-margin}. The default value is zero.
1424@end defopt
1425
1911e6e5
RS
1426@defopt scroll-preserve-screen-position
1427If this option is non-@code{nil}, the scroll functions move point so
1428that the vertical position of the cursor is unchanged, when that is
1429possible.
b1b12a8e
RS
1430@end defopt
1431
1432@defopt next-screen-context-lines
1433The value of this variable is the number of lines of continuity to
1434retain when scrolling by full screens. For example, @code{scroll-up}
1435with an argument of @code{nil} scrolls so that this many lines at the
1436bottom of the window appear instead at the top. The default value is
1437@code{2}.
1438@end defopt
1439
1440@deffn Command recenter &optional count
1441@cindex centering point
ac7845fd
RS
1442This function scrolls the text in the selected window so that point is
1443displayed at a specified vertical position within the window. It does
1444not ``move point'' with respect to the text.
1445
1446If @var{count} is a nonnegative number, that puts the line containing
1447point @var{count} lines down from the top of the window. If
1448@var{count} is a negative number, then it counts upward from the
1449bottom of the window, so that @minus{}1 stands for the last usable
1450line in the window. If @var{count} is a non-@code{nil} list, then it
1451stands for the line in the middle of the window.
b1b12a8e
RS
1452
1453If @var{count} is @code{nil}, @code{recenter} puts the line containing
1454point in the middle of the window, then clears and redisplays the entire
1455selected frame.
1456
1457When @code{recenter} is called interactively, @var{count} is the raw
1458prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
1459@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
1460@var{count} to 4, which positions the current line four lines from the
1461top.
1462
c638661f
RS
1463With an argument of zero, @code{recenter} positions the current line at
1464the top of the window. This action is so handy that some people make a
1465separate key binding to do this. For example,
b1b12a8e
RS
1466
1467@example
1468@group
1469(defun line-to-top-of-window ()
1470 "Scroll current line to top of window.
1471Replaces three keystroke sequence C-u 0 C-l."
3c29caa8 1472 (interactive)
b1b12a8e
RS
1473 (recenter 0))
1474
3c29caa8 1475(global-set-key [kp-multiply] 'line-to-top-of-window)
b1b12a8e
RS
1476@end group
1477@end example
1478@end deffn
1479
8241495d
RS
1480@node Vertical Scrolling
1481@section Vertical Fractional Scrolling
1482@cindex Vertical Fractional Scrolling
1483
1484 @dfn{Vertical fractional scrolling} means shifting the image in the
1485window up or down by a specified multiple or fraction of a line.
1486Starting in Emacs 21, each window has a @dfn{vertical scroll position},
1487which is a number, never less than zero. It specifies how far to raise
1488the contents of the window. Raising the window contents generally makes
1489all or part of some lines disappear off the top, and all or part of some
1490other lines appear at the bottom. The usual value is zero.
1491
1492 The vertical scroll position is measured in units of the normal line
1493height, which is the height of the default font. Thus, if the value is
1494.5, that means the window contents are scrolled up half the normal line
1495height. If it is 3.3, that means the window contents are scrolled up
1496somewhat over three times the normal line height.
1497
1498 What fraction of a line the vertical scrolling covers, or how many
1499lines, depends on what the lines contain. A value of .5 could scroll a
1500line whose height is very short off the screen, while a value of 3.3
1501could scroll just part of the way through a tall line or an image.
1502
1503@defun window-vscroll &optional window
1504This function returns the current vertical scroll position of
1505@var{window}, If @var{window} is @code{nil}, the selected window is
1506used.
1507
1508@example
1509@group
1510(window-vscroll)
1511 @result{} 0
1512@end group
1513@end example
1514@end defun
1515
1516@defun set-window-vscroll window lines
1517This function sets @var{window}'s vertical scroll position to
1518@var{lines}. The argument @var{lines} should be zero or positive; if
1519not, it is taken as zero.
1520
eb687116
EZ
1521If @var{window} is @code{nil}, the selected window is used.
1522
8241495d
RS
1523The actual vertical scroll position must always correspond
1524to an integral number of pixels, so the value you specify
1525is rounded accordingly.
1526
1527The return value is the result of this rounding.
1528
1529@example
1530@group
1531(set-window-vscroll (selected-window) 1.2)
1532 @result{} 1.13
1533@end group
1534@end example
1535@end defun
1536
b1b12a8e
RS
1537@node Horizontal Scrolling
1538@section Horizontal Scrolling
1539@cindex horizontal scrolling
1540
8241495d
RS
1541 @dfn{Horizontal scrolling} means shifting the image in the window left
1542or right by a specified multiple of the normal character width. Each
061967de 1543window has a @dfn{horizontal scroll position}, which is a number, never
8241495d
RS
1544less than zero. It specifies how far to shift the contents left.
1545Shifting the window contents left generally makes all or part of some
1546characters disappear off the left, and all or part of some other
1547characters appear at the right. The usual value is zero.
1548
1549 The horizontal scroll position is measured in units of the normal
1550character width, which is the width of space in the default font. Thus,
1551if the value is 5, that means the window contents are scrolled left by 5
c400241b 1552times the normal character width. How many characters actually
8241495d
RS
1553disappear off to the left depends on their width, and could vary from
1554line to line.
1555
1556 Because we read from side to side in the ``inner loop'', and from top
1557to bottom in the ``outer loop'', the effect of horizontal scrolling is
1558not like that of textual or vertical scrolling. Textual scrolling
1559involves selection of a portion of text to display, and vertical
1560scrolling moves the window contents contiguously; but horizontal
1561scrolling causes part of @emph{each line} to go off screen.
b1b12a8e
RS
1562
1563 Usually, no horizontal scrolling is in effect; then the leftmost
1564column is at the left edge of the window. In this state, scrolling to
8241495d
RS
1565the right is meaningless, since there is no data to the left of the edge
1566to be revealed by it; so this is not allowed. Scrolling to the left is
1567allowed; it scrolls the first columns of text off the edge of the window
1568and can reveal additional columns on the right that were truncated
1569before. Once a window has a nonzero amount of leftward horizontal
1570scrolling, you can scroll it back to the right, but only so far as to
1571reduce the net horizontal scroll to zero. There is no limit to how far
1572left you can scroll, but eventually all the text will disappear off the
1573left edge.
1574
0594fc7f 1575@vindex auto-hscroll-mode
8241495d 1576 In Emacs 21, redisplay automatically alters the horizontal scrolling
03ff8aab 1577of a window as necessary to ensure that point is always visible, if
0594fc7f 1578@code{auto-hscroll-mode} is set. However, you can still set the
03ff8aab
GM
1579horizontal scrolling value explicitly. The value you specify serves as
1580a lower bound for automatic scrolling, i.e. automatic scrolling
1581will not scroll a window to a column less than the specified one.
8241495d
RS
1582
1583@deffn Command scroll-left &optional count
b1b12a8e 1584This function scrolls the selected window @var{count} columns to the
8241495d
RS
1585left (or to the right if @var{count} is negative). The default
1586for @var{count} is the window width, minus 2.
1587
1588The return value is the total amount of leftward horizontal scrolling in
1589effect after the change---just like the value returned by
1590@code{window-hscroll} (below).
b1b12a8e
RS
1591@end deffn
1592
8241495d 1593@deffn Command scroll-right &optional count
b1b12a8e 1594This function scrolls the selected window @var{count} columns to the
8241495d
RS
1595right (or to the left if @var{count} is negative). The default
1596for @var{count} is the window width, minus 2.
1597
1598The return value is the total amount of leftward horizontal scrolling in
1599effect after the change---just like the value returned by
1600@code{window-hscroll} (below).
b1b12a8e
RS
1601
1602Once you scroll a window as far right as it can go, back to its normal
1603position where the total leftward scrolling is zero, attempts to scroll
1604any farther right have no effect.
1605@end deffn
1606
1607@defun window-hscroll &optional window
1608This function returns the total leftward horizontal scrolling of
1609@var{window}---the number of columns by which the text in @var{window}
1610is scrolled left past the left margin.
1611
1612The value is never negative. It is zero when no horizontal scrolling
1613has been done in @var{window} (which is usually the case).
1614
1615If @var{window} is @code{nil}, the selected window is used.
1616
1617@example
1618@group
1619(window-hscroll)
1620 @result{} 0
1621@end group
1622@group
1623(scroll-left 5)
1624 @result{} 5
1625@end group
1626@group
1627(window-hscroll)
1628 @result{} 5
1629@end group
1630@end example
1631@end defun
1632
1633@defun set-window-hscroll window columns
1634This function sets the number of columns from the left margin that
f9f59935 1635@var{window} is scrolled from the value of @var{columns}. The argument
b1b12a8e 1636@var{columns} should be zero or positive; if not, it is taken as zero.
8241495d 1637Fractional values of @var{columns} are not supported at present.
b1b12a8e 1638
515a9a0f
RS
1639Note that @code{set-window-hscroll} may appear not to work if you test
1640it by evaluating a call with @kbd{M-:} in a simple way. What happens
1641is that the function sets the horizontal scroll value and returns, but
1642then redisplay adjusts the horizontal scrolling to make point visible,
1643and this overrides what the function did. You can observe the
1644function's effect if you call it while point is sufficiently far from
1645the left margin that it will remain visible.
1646
b1b12a8e
RS
1647The value returned is @var{columns}.
1648
1649@example
1650@group
1651(set-window-hscroll (selected-window) 10)
1652 @result{} 10
1653@end group
1654@end example
1655@end defun
1656
1657 Here is how you can determine whether a given position @var{position}
1658is off the screen due to horizontal scrolling:
1659
1660@example
1661@group
c638661f 1662(defun hscroll-on-screen (window position)
3c29caa8 1663 (save-excursion
c638661f 1664 (goto-char position)
3c29caa8 1665 (and
c638661f
RS
1666 (>= (- (current-column) (window-hscroll window)) 0)
1667 (< (- (current-column) (window-hscroll window))
1668 (window-width window)))))
b1b12a8e
RS
1669@end group
1670@end example
1671
1672@node Size of Window
1673@section The Size of a Window
1674@cindex window size
1675@cindex size of window
1676
1677 An Emacs window is rectangular, and its size information consists of
1678the height (the number of lines) and the width (the number of character
1679positions in each line). The mode line is included in the height. But
1680the width does not count the scroll bar or the column of @samp{|}
c638661f 1681characters that separates side-by-side windows.
b1b12a8e
RS
1682
1683 The following three functions return size information about a window:
1684
1685@defun window-height &optional window
88f7b76a
RS
1686This function returns the number of lines in @var{window}, including
1687its mode line and header line, if any. If @var{window} fills its
1688entire frame except for the echo area, and there is no tool bar, this
1689is typically one less than the value of @code{frame-height} on that
1690frame.
b1b12a8e
RS
1691
1692If @var{window} is @code{nil}, the function uses the selected window.
1693
1694@example
1695@group
1696(window-height)
1697 @result{} 23
1698@end group
1699@group
1700(split-window-vertically)
1701 @result{} #<window 4 on windows.texi>
1702@end group
1703@group
1704(window-height)
1705 @result{} 11
1706@end group
1707@end example
1708@end defun
1709
88f7b76a
RS
1710@tindex window-body-height
1711@defun window-body-height &optional window
177c0ea7 1712Like @code{window-height} but the value does not include the
88f7b76a
RS
1713mode line (if any) or the header line (if any).
1714@end defun
1715
b1b12a8e
RS
1716@defun window-width &optional window
1717This function returns the number of columns in @var{window}. If
1718@var{window} fills its entire frame, this is the same as the value of
1719@code{frame-width} on that frame. The width does not include the
1720window's scroll bar or the column of @samp{|} characters that separates
1721side-by-side windows.
1722
1723If @var{window} is @code{nil}, the function uses the selected window.
1724
1725@example
1726@group
1727(window-width)
1728 @result{} 80
1729@end group
1730@end example
1731@end defun
1732
1733@defun window-edges &optional window
1734This function returns a list of the edge coordinates of @var{window}.
1735If @var{window} is @code{nil}, the selected window is used.
1736
1737The order of the list is @code{(@var{left} @var{top} @var{right}
1738@var{bottom})}, all elements relative to 0, 0 at the top left corner of
1739the frame. The element @var{right} of the value is one more than the
1740rightmost column used by @var{window}, and @var{bottom} is one more than
1741the bottommost row used by @var{window} and its mode-line.
1742
8241495d
RS
1743If a window has a scroll bar, the right edge value includes the width of
1744the scroll bar. Otherwise, if the window has a neighbor on the right,
1745its right edge value includes the width of the separator line between
1746the window and that neighbor. Since the width of the window does not
1747include this separator, the width does not usually equal the difference
1748between the right and left edges.
5a8a6af8
RS
1749@end defun
1750
1751@defun window-inside-edges window
1752This is similar to @code{window-edges}, but the edge values
1753it returns include only the text area of the window. They
1754do not include the header line, mode line, scroll bar or
1755vertical separator, fringes, or display margins.
1756@end defun
b1b12a8e 1757
5a8a6af8
RS
1758Here are the results obtained on a typical 24-line terminal with just
1759one window, with menu bar enabled:
b1b12a8e
RS
1760
1761@example
1762@group
1763(window-edges (selected-window))
5a8a6af8
RS
1764 @result{} (0 1 80 23)
1765@end group
1766@group
1767(window-inside-edges (selected-window))
1768 @result{} (0 1 80 22)
b1b12a8e
RS
1769@end group
1770@end example
1771
c638661f
RS
1772@noindent
1773The bottom edge is at line 23 because the last line is the echo area.
5a8a6af8
RS
1774The bottom inside edge is at line 22, which is the window's mode line.
1775
1776If @var{window} is at the upper left corner of its frame, and there is
1777no menu bar, then @var{bottom} returned by @code{window-edges} is the
1778same as the value of @code{(window-height)}, @var{right} is almost the
1779same as the value of @code{(window-width)}, and @var{top} and
1780@var{left} are zero. For example, the edges of the following window
1781are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8
1782columns, the last column of the window (column 7) holds a border
1783rather than text. The last row (row 4) holds the mode line, shown
1784here with @samp{xxxxxxxxx}.
b1b12a8e
RS
1785
1786@example
1787@group
3c29caa8 1788 0
b1b12a8e 1789 _______
3c29caa8
DH
1790 0 | |
1791 | |
1792 | |
1793 | |
b1b12a8e
RS
1794 xxxxxxxxx 4
1795
3c29caa8 1796 7
b1b12a8e
RS
1797@end group
1798@end example
1799
b1b12a8e
RS
1800In the following example, let's suppose that the frame is 7
1801columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
5a8a6af8
RS
1802and the edges of the right window are @w{@samp{4 0 7 3}}.
1803The inside edges of the left window are @w{@samp{0 0 3 2}},
1804and the inside edges of the right window are @w{@samp{4 0 7 2}},
b1b12a8e
RS
1805
1806@example
1807@group
1808 ___ ___
3c29caa8
DH
1809 | | |
1810 | | |
1811 xxxxxxxxx
b1b12a8e
RS
1812
1813 0 34 7
1814@end group
1815@end example
5a8a6af8
RS
1816
1817@defun window-pixel-edges window
1818This function is like @code{window-edges} except that, on a graphical
1819display, the edge values are measured in pixels instead of in
1820character lines and columns.
1821@end defun
1822
1823@defun window-inside-pixel-edges window
1824This function is like @code{window-inside-edges} except that, on a
1825graphical display, the edge values are measured in pixels instead of
1826in character lines and columns.
b1b12a8e
RS
1827@end defun
1828
1829@node Resizing Windows
1830@section Changing the Size of a Window
1831@cindex window resizing
1832@cindex changing window size
1833@cindex window size, changing
1834
1835 The window size functions fall into two classes: high-level commands
1836that change the size of windows and low-level functions that access
1837window size. Emacs does not permit overlapping windows or gaps between
1838windows, so resizing one window affects other windows.
1839
1840@deffn Command enlarge-window size &optional horizontal
c638661f 1841This function makes the selected window @var{size} lines taller,
b1b12a8e
RS
1842stealing lines from neighboring windows. It takes the lines from one
1843window at a time until that window is used up, then takes from another.
1844If a window from which lines are stolen shrinks below
1845@code{window-min-height} lines, that window disappears.
1846
1847If @var{horizontal} is non-@code{nil}, this function makes
1848@var{window} wider by @var{size} columns, stealing columns instead of
1849lines. If a window from which columns are stolen shrinks below
1850@code{window-min-width} columns, that window disappears.
1851
c638661f
RS
1852If the requested size would exceed that of the window's frame, then the
1853function makes the window occupy the entire height (or width) of the
1854frame.
b1b12a8e 1855
8241495d
RS
1856If there are various other windows from which lines or columns can be
1857stolen, and some of them specify fixed size (using
1858@code{window-size-fixed}, see below), they are left untouched while
1859other windows are ``robbed.'' If it would be necessary to alter the
1860size of a fixed-size window, @code{enlarge-window} gets an error
1861instead.
1862
b1b12a8e
RS
1863If @var{size} is negative, this function shrinks the window by
1864@minus{}@var{size} lines or columns. If that makes the window smaller
1865than the minimum size (@code{window-min-height} and
1866@code{window-min-width}), @code{enlarge-window} deletes the window.
1867
3c29caa8 1868@code{enlarge-window} returns @code{nil}.
b1b12a8e
RS
1869@end deffn
1870
1871@deffn Command enlarge-window-horizontally columns
1872This function makes the selected window @var{columns} wider.
1873It could be defined as follows:
1874
1875@example
1876@group
1877(defun enlarge-window-horizontally (columns)
1878 (enlarge-window columns t))
1879@end group
1880@end example
1881@end deffn
1882
1883@deffn Command shrink-window size &optional horizontal
1884This function is like @code{enlarge-window} but negates the argument
1885@var{size}, making the selected window smaller by giving lines (or
1886columns) to the other windows. If the window shrinks below
1887@code{window-min-height} or @code{window-min-width}, then it disappears.
1888
1889If @var{size} is negative, the window is enlarged by @minus{}@var{size}
1890lines or columns.
1891@end deffn
1892
1893@deffn Command shrink-window-horizontally columns
1894This function makes the selected window @var{columns} narrower.
1895It could be defined as follows:
1896
1897@example
1898@group
1899(defun shrink-window-horizontally (columns)
1900 (shrink-window columns t))
1901@end group
1902@end example
1903@end deffn
1904
8241495d 1905@deffn Command shrink-window-if-larger-than-buffer &optional window
1911e6e5
RS
1906This command shrinks @var{window} to be as small as possible while still
1907showing the full contents of its buffer---but not less than
8241495d
RS
1908@code{window-min-height} lines. If @var{window} is not given,
1909it defaults to the selected window.
1911e6e5
RS
1910
1911However, the command does nothing if the window is already too small to
1912display the whole text of the buffer, or if part of the contents are
1913currently scrolled off screen, or if the window is not the full width of
1914its frame, or if the window is the only window in its frame.
1915@end deffn
1916
8241495d
RS
1917@tindex window-size-fixed
1918@defvar window-size-fixed
1919If this variable is non-@code{nil}, in any given buffer,
1920then the size of any window displaying the buffer remains fixed
1921unless you explicitly change it or Emacs has no other choice.
1922(This feature is new in Emacs 21.)
1923
1924If the value is @code{height}, then only the window's height is fixed;
1925if the value is @code{width}, then only the window's width is fixed.
1926Any other non-@code{nil} value fixes both the width and the height.
1927
1928The usual way to use this variable is to give it a buffer-local value in
1929a particular buffer. That way, the windows (but usually there is only
1930one) displaying that buffer have fixed size.
1931
1932Explicit size-change functions such as @code{enlarge-window}
1933get an error if they would have to change a window size which is fixed.
1934Therefore, when you want to change the size of such a window,
1935you should bind @code{window-size-fixed} to @code{nil}, like this:
1936
1937@example
1938(let ((window-size-fixed nil))
1939 (enlarge-window 10))
1940@end example
1941
1942Note that changing the frame size will change the size of a
1943fixed-size window, if there is no other alternative.
1944@end defvar
1945
b1b12a8e 1946@cindex minimum window size
926a5166 1947 The following two variables constrain the window-structure-changing
b1b12a8e
RS
1948functions to a minimum height and width.
1949
1950@defopt window-min-height
1951The value of this variable determines how short a window may become
1952before it is automatically deleted. Making a window smaller than
926a5166
RS
1953@code{window-min-height} automatically deletes it, and no window may
1954be created shorter than this. The default value is 4.
1955
1956The absolute minimum window height is one; actions that change window
1957sizes reset this variable to one if it is less than one.
b1b12a8e
RS
1958@end defopt
1959
1960@defopt window-min-width
1961The value of this variable determines how narrow a window may become
1911e6e5 1962before it is automatically deleted. Making a window smaller than
b1b12a8e 1963@code{window-min-width} automatically deletes it, and no window may be
926a5166
RS
1964created narrower than this. The default value is 10.
1965
1966The absolute minimum window width is two; actions that change window
1967sizes reset this variable to two if it is less than two.
b1b12a8e
RS
1968@end defopt
1969
1970@node Coordinates and Windows
1971@section Coordinates and Windows
1972
c638661f 1973This section describes how to relate screen coordinates to windows.
b1b12a8e
RS
1974
1975@defun window-at x y &optional frame
1976This function returns the window containing the specified cursor
1977position in the frame @var{frame}. The coordinates @var{x} and @var{y}
1978are measured in characters and count from the top left corner of the
1979frame. If they are out of range, @code{window-at} returns @code{nil}.
1980
1981If you omit @var{frame}, the selected frame is used.
1982@end defun
1983
1984@defun coordinates-in-window-p coordinates window
1985This function checks whether a particular frame position falls within
1986the window @var{window}.
1987
969fe9b5
RS
1988The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
1989. @var{y})}. The coordinates @var{x} and @var{y} are measured in
1990characters, and count from the top left corner of the screen or frame.
b1b12a8e 1991
f9f59935
RS
1992The value returned by @code{coordinates-in-window-p} is non-@code{nil}
1993if the coordinates are inside @var{window}. The value also indicates
1994what part of the window the position is in, as follows:
b1b12a8e
RS
1995
1996@table @code
1997@item (@var{relx} . @var{rely})
1998The coordinates are inside @var{window}. The numbers @var{relx} and
1999@var{rely} are the equivalent window-relative coordinates for the
2000specified position, counting from 0 at the top left corner of the
2001window.
2002
2003@item mode-line
2004The coordinates are in the mode line of @var{window}.
2005
8241495d
RS
2006@item header-line
2007The coordinates are in the header line of @var{window}.
2008
2009@item vertical-line
b1b12a8e 2010The coordinates are in the vertical line between @var{window} and its
3c29caa8 2011neighbor to the right. This value occurs only if the window doesn't
b1b12a8e 2012have a scroll bar; positions in a scroll bar are considered outside the
8241495d 2013window for these purposes.
b1b12a8e
RS
2014
2015@item nil
2016The coordinates are not in any part of @var{window}.
2017@end table
2018
2019The function @code{coordinates-in-window-p} does not require a frame as
2020argument because it always uses the frame that @var{window} is on.
2021@end defun
2022
2023@node Window Configurations
2024@section Window Configurations
2025@cindex window configurations
2026@cindex saving window information
2027
f9f59935 2028 A @dfn{window configuration} records the entire layout of one
c02dd51a
RS
2029frame---all windows, their sizes, which buffers they contain, what
2030part of each buffer is displayed, and the values of point and the
2031mark. It also includes the values of @code{window-min-height},
2032@code{window-min-width} and @code{minibuffer-scroll-window}. An
2033exception is made for point in the selected window for the current
2034buffer; its value is not saved in the window configuration.
2035
2036 You can bring back an entire previous layout by restoring a window
2037configuration previously saved. If you want to record all frames
2038instead of just one, use a frame configuration instead of a window
2039configuration. @xref{Frame Configurations}.
b1b12a8e 2040
8241495d 2041@defun current-window-configuration &optional frame
c02dd51a
RS
2042This function returns a new object representing @var{frame}'s current
2043window configuration. If @var{frame} is omitted, the selected frame
2044is used.
b1b12a8e
RS
2045@end defun
2046
2047@defun set-window-configuration configuration
f9f59935 2048This function restores the configuration of windows and buffers as
8241495d
RS
2049specified by @var{configuration}, for the frame that @var{configuration}
2050was created for.
2051
2052The argument @var{configuration} must be a value that was previously
2053returned by @code{current-window-configuration}. This configuration is
2054restored in the frame from which @var{configuration} was made, whether
2055that frame is selected or not. This always counts as a window size
2056change and triggers execution of the @code{window-size-change-functions}
969fe9b5
RS
2057(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
2058know how to tell whether the new configuration actually differs from the
2059old one.
2060
2061If the frame which @var{configuration} was saved from is dead, all this
2062function does is restore the three variables @code{window-min-height},
2063@code{window-min-width} and @code{minibuffer-scroll-window}.
bfe721d1 2064
b1b12a8e
RS
2065Here is a way of using this function to get the same effect
2066as @code{save-window-excursion}:
2067
2068@example
2069@group
2070(let ((config (current-window-configuration)))
2071 (unwind-protect
2072 (progn (split-window-vertically nil)
2073 @dots{})
2074 (set-window-configuration config)))
2075@end group
2076@end example
2077@end defun
2078
2079@defspec save-window-excursion forms@dots{}
2080This special form records the window configuration, executes @var{forms}
2081in sequence, then restores the earlier window configuration. The window
2082configuration includes the value of point and the portion of the buffer
c638661f 2083that is visible. It also includes the choice of selected window.
b1b12a8e 2084However, it does not include the value of point in the current buffer;
f9f59935 2085use @code{save-excursion} also, if you wish to preserve that.
b1b12a8e 2086
9258d604 2087Don't use this construct when @code{save-selected-window} is sufficient.
bfe721d1
KH
2088
2089Exit from @code{save-window-excursion} always triggers execution of the
2090@code{window-size-change-functions}. (It doesn't know how to tell
2091whether the restored configuration actually differs from the one in
2092effect at the end of the @var{forms}.)
2093
b1b12a8e
RS
2094The return value is the value of the final form in @var{forms}.
2095For example:
2096
2097@example
2098@group
2099(split-window)
2100 @result{} #<window 25 on control.texi>
2101@end group
2102@group
2103(setq w (selected-window))
2104 @result{} #<window 19 on control.texi>
2105@end group
2106@group
2107(save-window-excursion
2108 (delete-other-windows w)
2109 (switch-to-buffer "foo")
2110 'do-something)
2111 @result{} do-something
2112 ;; @r{The screen is now split again.}
2113@end group
2114@end example
2115@end defspec
2116
2117@defun window-configuration-p object
2118This function returns @code{t} if @var{object} is a window configuration.
969fe9b5
RS
2119@end defun
2120
2121@defun compare-window-configurations config1 config2
2122This function compares two window configurations as regards the
2123structure of windows, but ignores the values of point and mark and the
2124saved scrolling positions---it can return @code{t} even if those
2125aspects differ.
2126
2127The function @code{equal} can also compare two window configurations; it
2128regards configurations as unequal if they differ in any respect, even a
2129saved point or mark.
b1b12a8e
RS
2130@end defun
2131
2132 Primitives to look inside of window configurations would make sense,
ca61e387
RS
2133but none are implemented. It is not clear they are useful enough to
2134be worth implementing. See the file @file{winner.el} for some more
2135operations on windows configurations.
f9f59935
RS
2136
2137@node Window Hooks
2138@section Hooks for Window Scrolling and Changes
2139
2140This section describes how a Lisp program can take action whenever a
2141window displays a different part of its buffer or a different buffer.
2142There are three actions that can change this: scrolling the window,
2143switching buffers in the window, and changing the size of the window.
2144The first two actions run @code{window-scroll-functions}; the last runs
2145@code{window-size-change-functions}. The paradigmatic use of these
333c5fc5 2146hooks is in the implementation of Lazy Lock mode; see @file{lazy-lock.el}.
f9f59935
RS
2147
2148@defvar window-scroll-functions
2149This variable holds a list of functions that Emacs should call before
2150redisplaying a window with scrolling. It is not a normal hook, because
2151each function is called with two arguments: the window, and its new
2152display-start position.
2153
2154Displaying a different buffer in the window also runs these functions.
2155
1911e6e5
RS
2156These functions must be careful in using @code{window-end}
2157(@pxref{Window Start}); if you need an up-to-date value, you must use
2158the @var{update} argument to ensure you get it.
f9f59935
RS
2159@end defvar
2160
2161@defvar window-size-change-functions
2162This variable holds a list of functions to be called if the size of any
2163window changes for any reason. The functions are called just once per
2164redisplay, and just once for each frame on which size changes have
2165occurred.
2166
2167Each function receives the frame as its sole argument. There is no
2168direct way to find out which windows on that frame have changed size, or
2169precisely how. However, if a size-change function records, at each
2170call, the existing windows and their sizes, it can also compare the
2171present sizes and the previous sizes.
2172
2173Creating or deleting windows counts as a size change, and therefore
2174causes these functions to be called. Changing the frame size also
2175counts, because it changes the sizes of the existing windows.
2176
2177It is not a good idea to use @code{save-window-excursion} (@pxref{Window
2178Configurations}) in these functions, because that always counts as a
2179size change, and it would cause these functions to be called over and
2180over. In most cases, @code{save-selected-window} (@pxref{Selecting
2181Windows}) is what you need here.
2182@end defvar
2183
f9f59935 2184@defvar redisplay-end-trigger-functions
1911e6e5 2185This abnormal hook is run whenever redisplay in a window uses text that
f9f59935
RS
2186extends past a specified end trigger position. You set the end trigger
2187position with the function @code{set-window-redisplay-end-trigger}. The
2188functions are called with two arguments: the window, and the end trigger
2189position. Storing @code{nil} for the end trigger position turns off the
2190feature, and the trigger value is automatically reset to @code{nil} just
2191after the hook is run.
2192@end defvar
2193
f9f59935
RS
2194@defun set-window-redisplay-end-trigger window position
2195This function sets @var{window}'s end trigger position at
2196@var{position}.
2197@end defun
2198
8241495d 2199@defun window-redisplay-end-trigger &optional window
f9f59935
RS
2200This function returns @var{window}'s current end trigger position.
2201@end defun
2202
f9f59935
RS
2203@defvar window-configuration-change-hook
2204A normal hook that is run every time you change the window configuration
2205of an existing frame. This includes splitting or deleting windows,
2206changing the sizes of windows, or displaying a different buffer in a
2207window. The frame whose window configuration has changed is the
2208selected frame when this hook runs.
2209@end defvar
ab5796a9
MB
2210
2211@ignore
2212 arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
2213@end ignore