windows.texi 80.3 KB
Newer Older
Richard M. Stallman's avatar
Richard M. Stallman committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
Gerd Moellmann's avatar
Gerd Moellmann committed
3 4
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
@c   Free Software Foundation, Inc.
Richard M. Stallman's avatar
Richard M. Stallman committed
5 6 7 8 9 10 11 12 13 14
@c See the file elisp.texi for copying conditions.
@setfilename ../info/windows
@node Windows, Frames, Buffers, Top
@chapter Windows

  This chapter describes most of the functions and variables related to
Emacs windows.  See @ref{Display}, for information on how text is
displayed in windows.

@menu
15 16 17 18 19 20 21 22 23 24 25 26
* Basic Windows::           Basic information on using windows.
* Splitting Windows::       Splitting one window into two windows.
* Deleting Windows::        Deleting a window gives its space to other windows.
* Selecting Windows::       The selected window is the one that you edit in.
* Cyclic Window Ordering::  Moving around the existing windows.
* Buffers and Windows::     Each window displays the contents of a buffer.
* Displaying Buffers::      Higher-lever functions for displaying a buffer
                              and choosing a window for it.
* Choosing Window::	    How to choose a window for displaying a buffer.
* Window Point::            Each window has its own location of point.
* Window Start::            The display-start position controls which text
                              is on-screen in the window.
27 28 29
* Textual Scrolling::       Moving text up and down through the window.
* Vertical Scrolling::      Moving the contents up and down on the window.
* Horizontal Scrolling::    Moving the contents sideways on the window.
30 31 32 33
* Size of Window::          Accessing the size of a window.
* Resizing Windows::        Changing the size of a window.
* Coordinates and Windows:: Converting coordinates to windows.
* Window Configurations::   Saving and restoring the state of the screen.
34 35 36
* Window Hooks::            Hooks for scrolling, window size changes,
                              redisplay going past a certain point,
                              or window configuration changes.
Richard M. Stallman's avatar
Richard M. Stallman committed
37 38 39 40 41 42 43
@end menu

@node Basic Windows
@section Basic Concepts of Emacs Windows
@cindex window
@cindex selected window

Karl Heuer's avatar
Karl Heuer committed
44 45
  A @dfn{window} in Emacs is the physical area of the screen in which a
buffer is displayed.  The term is also used to refer to a Lisp object that
Richard M. Stallman's avatar
Richard M. Stallman committed
46 47 48
represents that screen area in Emacs Lisp.  It should be
clear from the context which is meant.

Karl Heuer's avatar
Karl Heuer committed
49 50 51 52 53 54 55
  Emacs groups windows into frames.  A frame represents an area of
screen available for Emacs to use.  Each frame always contains at least
one window, but you can subdivide it vertically or horizontally into
multiple nonoverlapping Emacs windows.

  In each frame, at any time, one and only one window is designated as
@dfn{selected within the frame}.  The frame's cursor appears in that
56
window.  At any time, one frame is the selected frame; and the window
Karl Heuer's avatar
Karl Heuer committed
57 58 59 60 61 62 63 64 65 66
selected within that frame is @dfn{the selected window}.  The selected
window's buffer is usually the current buffer (except when
@code{set-buffer} has been used).  @xref{Current Buffer}.

  For practical purposes, a window exists only while it is displayed in
a frame.  Once removed from the frame, the window is effectively deleted
and should not be used, @emph{even though there may still be references
to it} from other Lisp objects.  Restoring a saved window configuration
is the only way for a window no longer on the screen to come back to
life.  (@xref{Deleting Windows}.)
Richard M. Stallman's avatar
Richard M. Stallman committed
67 68 69 70 71 72 73

  Each window has the following attributes:

@itemize @bullet
@item
containing frame

74
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
75 76
window height

77
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
78 79
window width

80
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
81 82
window edges with respect to the screen or frame

83
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
84 85
the buffer it displays

86
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
87 88
position within the buffer at the upper left of the window

89
@item
90
amount of horizontal scrolling, in columns
Richard M. Stallman's avatar
Richard M. Stallman committed
91

92
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
93 94
point

95
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
96 97
the mark

98
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
99 100 101 102 103 104
how recently the window was selected
@end itemize

@cindex multiple windows
  Users create multiple windows so they can look at several buffers at
once.  Lisp libraries use multiple windows for a variety of reasons, but
Karl Heuer's avatar
Karl Heuer committed
105 106 107
most often to display related information.  In Rmail, for example, you
can move through a summary buffer in one window while the other window
shows messages one at a time as they are reached.
Richard M. Stallman's avatar
Richard M. Stallman committed
108 109

  The meaning of ``window'' in Emacs is similar to what it means in the
110
context of general-purpose window systems such as X, but not identical.
Karl Heuer's avatar
Karl Heuer committed
111 112 113 114
The X Window System places X windows on the screen; Emacs uses one or
more X windows as frames, and subdivides them into
Emacs windows.  When you use Emacs on a character-only terminal, Emacs
treats the whole terminal screen as one frame.
Richard M. Stallman's avatar
Richard M. Stallman committed
115 116 117 118 119 120

@cindex terminal screen
@cindex screen of terminal
@cindex tiled windows
  Most window systems support arbitrarily located overlapping windows.
In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
121 122 123 124
together they fill the whole screen or frame.  Because of the way in
which Emacs creates new windows and resizes them, not all conceivable
tilings of windows on an Emacs frame are actually possible.
@xref{Splitting Windows}, and @ref{Size of Window}.
Richard M. Stallman's avatar
Richard M. Stallman committed
125 126 127 128 129

  @xref{Display}, for information on how the contents of the
window's buffer are displayed in the window.

@defun windowp object
130
This function returns @code{t} if @var{object} is a window.
Richard M. Stallman's avatar
Richard M. Stallman committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
@end defun

@node Splitting Windows
@section Splitting Windows
@cindex splitting windows
@cindex window splitting

  The functions described here are the primitives used to split a window
into two windows.  Two higher level functions sometimes split a window,
but not always: @code{pop-to-buffer} and @code{display-buffer}
(@pxref{Displaying Buffers}).

  The functions described here do not accept a buffer as an argument.
The two ``halves'' of the split window initially display the same buffer
previously visible in the window that was split.

@deffn Command split-window &optional window size horizontal
This function splits @var{window} into two windows.  The original
window @var{window} remains the selected window, but occupies only
part of its former screen area.  The rest is occupied by a newly created
window which is returned as the value of this function.

153
If @var{horizontal} is non-@code{nil}, then @var{window} splits into
Richard M. Stallman's avatar
Richard M. Stallman committed
154 155 156 157 158
two side by side windows.  The original window @var{window} keeps the
leftmost @var{size} columns, and gives the rest of the columns to the
new window.  Otherwise, it splits into windows one above the other, and
@var{window} keeps the upper @var{size} lines and gives the rest of the
lines to the new window.  The original window is therefore the
159
left-hand or upper of the two, and the new window is the right-hand or
Richard M. Stallman's avatar
Richard M. Stallman committed
160 161
lower.

162
If @var{window} is omitted or @code{nil}, then the selected window is
Richard M. Stallman's avatar
Richard M. Stallman committed
163 164 165 166 167
split.  If @var{size} is omitted or @code{nil}, then @var{window} is
divided evenly into two parts.  (If there is an odd line, it is
allocated to the new window.)  When @code{split-window} is called
interactively, all its arguments are @code{nil}.

168 169 170 171 172
If splitting would result in making a window that is smaller than
@code{window-min-height} or @code{window-min-width}, the function
signals an error and does not split the window at all.

The following example starts with one window on a screen that is 50
173
lines high by 80 columns wide; then it splits the window.
Richard M. Stallman's avatar
Richard M. Stallman committed
174 175 176 177 178 179 180 181 182 183 184

@smallexample
@group
(setq w (selected-window))
     @result{} #<window 8 on windows.texi>
(window-edges)          ; @r{Edges in order:}
     @result{} (0 0 80 50)     ;   @r{left--top--right--bottom}
@end group

@group
;; @r{Returns window created}
185
(setq w2 (split-window w 15))
Richard M. Stallman's avatar
Richard M. Stallman committed
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202
     @result{} #<window 28 on windows.texi>
@end group
@group
(window-edges w2)
     @result{} (0 15 80 50)    ; @r{Bottom window;}
                        ;   @r{top is line 15}
@end group
@group
(window-edges w)
     @result{} (0 0 80 15)     ; @r{Top window}
@end group
@end smallexample

The screen looks like this:

@smallexample
@group
203 204
         __________
        |          |  line 0
Richard M. Stallman's avatar
Richard M. Stallman committed
205 206 207 208 209 210 211 212 213 214
        |    w     |
        |__________|
        |          |  line 15
        |    w2    |
        |__________|
                      line 50
 column 0   column 80
@end group
@end smallexample

215
Next, split the top window horizontally:
Richard M. Stallman's avatar
Richard M. Stallman committed
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235

@smallexample
@group
(setq w3 (split-window w 35 t))
     @result{} #<window 32 on windows.texi>
@end group
@group
(window-edges w3)
     @result{} (35 0 80 15)  ; @r{Left edge at column 35}
@end group
@group
(window-edges w)
     @result{} (0 0 35 15)   ; @r{Right edge at column 35}
@end group
@group
(window-edges w2)
     @result{} (0 15 80 50)  ; @r{Bottom window unchanged}
@end group
@end smallexample

236
@need 3000
237
Now the screen looks like this:
Richard M. Stallman's avatar
Richard M. Stallman committed
238 239 240 241

@smallexample
@group
     column 35
242 243
         __________
        |   |      |  line 0
Richard M. Stallman's avatar
Richard M. Stallman committed
244 245 246 247 248 249 250 251 252
        | w |  w3  |
        |___|______|
        |          |  line 15
        |    w2    |
        |__________|
                      line 50
 column 0   column 80
@end group
@end smallexample
Jim Blandy's avatar
Jim Blandy committed
253 254

Normally, Emacs indicates the border between two side-by-side windows
255
with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
Jim Blandy's avatar
Jim Blandy committed
256 257
characters.  The display table can specify alternative border
characters; see @ref{Display Tables}.
Richard M. Stallman's avatar
Richard M. Stallman committed
258 259
@end deffn

260
@deffn Command split-window-vertically &optional size
261
This function splits the selected window into two windows, one above the
262
other, leaving the upper of the two windows selected, with @var{size}
263 264 265
lines.  (If @var{size} is negative, then the lower of the two windows
gets @minus{} @var{size} lines and the upper window gets the rest, but
the upper window is still the one selected.)
Richard M. Stallman's avatar
Richard M. Stallman committed
266 267
@end deffn

268
@deffn Command split-window-horizontally &optional size
Richard M. Stallman's avatar
Richard M. Stallman committed
269 270 271
This function splits the selected window into two windows
side-by-side, leaving the selected window with @var{size} columns.

272 273
This function is basically an interface to @code{split-window}.
You could define a simplified version of the function like this:
Richard M. Stallman's avatar
Richard M. Stallman committed
274 275 276 277 278 279

@smallexample
@group
(defun split-window-horizontally (&optional arg)
  "Split selected window into two windows, side by side..."
  (interactive "P")
Gerd Moellmann's avatar
Gerd Moellmann committed
280
@end group
281 282 283 284 285
@group
  (let ((size (and arg (prefix-numeric-value arg))))
    (and size (< size 0)
	 (setq size (+ (window-width) size)))
    (split-window nil size t)))
Richard M. Stallman's avatar
Richard M. Stallman committed
286 287 288 289 290 291 292 293
@end group
@end smallexample
@end deffn

@defun one-window-p &optional no-mini all-frames
This function returns non-@code{nil} if there is only one window.  The
argument @var{no-mini}, if non-@code{nil}, means don't count the
minibuffer even if it is active; otherwise, the minibuffer window is
Melissa Weisshaus's avatar
Melissa Weisshaus committed
294
included, if active, in the total number of windows, which is compared
Richard M. Stallman's avatar
Richard M. Stallman committed
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
against one.

The argument @var{all-frames} specifies which frames to consider.  Here
are the possible values and their meanings:

@table @asis
@item @code{nil}
Count the windows in the selected frame, plus the minibuffer used
by that frame even if it lies in some other frame.

@item @code{t}
Count all windows in all existing frames.

@item @code{visible}
Count all windows in all visible frames.

Karl Heuer's avatar
Karl Heuer committed
311 312 313
@item 0
Count all windows in all visible or iconified frames.

Richard M. Stallman's avatar
Richard M. Stallman committed
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
@item anything else
Count precisely the windows in the selected frame, and no others.
@end table
@end defun

@node Deleting Windows
@section Deleting Windows
@cindex deleting windows

A window remains visible on its frame unless you @dfn{delete} it by
calling certain functions that delete windows.  A deleted window cannot
appear on the screen, but continues to exist as a Lisp object until
there are no references to it.  There is no way to cancel the deletion
of a window aside from restoring a saved window configuration
(@pxref{Window Configurations}).  Restoring a window configuration also
deletes any windows that aren't part of that configuration.

  When you delete a window, the space it took up is given to one
332
adjacent sibling.
Richard M. Stallman's avatar
Richard M. Stallman committed
333 334 335 336 337 338

@c Emacs 19 feature
@defun window-live-p window
This function returns @code{nil} if @var{window} is deleted, and
@code{t} otherwise.

339
@strong{Warning:} Erroneous information or fatal errors may result from
Richard M. Stallman's avatar
Richard M. Stallman committed
340 341 342 343
using a deleted window as if it were live.
@end defun

@deffn Command delete-window &optional window
344 345 346 347
This function removes @var{window} from display, and returns @code{nil}.
If @var{window} is omitted, then the selected window is deleted.  An
error is signaled if there is only one window when @code{delete-window}
is called.
Richard M. Stallman's avatar
Richard M. Stallman committed
348 349 350 351 352 353 354
@end deffn

@deffn Command delete-other-windows &optional window
This function makes @var{window} the only window on its frame, by
deleting the other windows in that frame.  If @var{window} is omitted or
@code{nil}, then the selected window is used by default.

355
The return value is @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
356 357 358 359 360 361 362 363 364 365 366 367 368 369
@end deffn

@deffn Command delete-windows-on buffer &optional frame
This function deletes all windows showing @var{buffer}.  If there are
no windows showing @var{buffer}, it does nothing.

@code{delete-windows-on} operates frame by frame.  If a frame has
several windows showing different buffers, then those showing
@var{buffer} are removed, and the others expand to fill the space.  If
all windows in some frame are showing @var{buffer} (including the case
where there is only one window), then the frame reverts to having a
single window showing another buffer chosen with @code{other-buffer}.
@xref{The Buffer List}.

370 371 372 373 374
The argument @var{frame} controls which frames to operate on.  This
function does not use it in quite the same way as the other functions
which scan all windows; specifically, the values @code{t} and @code{nil}
have the opposite of their meanings in other functions.  Here are the
full details:
Richard M. Stallman's avatar
Richard M. Stallman committed
375 376 377

@itemize @bullet
@item
378
If it is @code{nil}, operate on all frames.
Richard M. Stallman's avatar
Richard M. Stallman committed
379
@item
380
If it is @code{t}, operate on the selected frame.
Richard M. Stallman's avatar
Richard M. Stallman committed
381 382
@item
If it is @code{visible}, operate on all visible frames.
383
@item
Karl Heuer's avatar
Karl Heuer committed
384
If it is 0, operate on all visible or iconified frames.
Richard M. Stallman's avatar
Richard M. Stallman committed
385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419
@item
If it is a frame, operate on that frame.
@end itemize

This function always returns @code{nil}.
@end deffn

@node Selecting Windows
@section Selecting Windows
@cindex selecting windows

  When a window is selected, the buffer in the window becomes the current
buffer, and the cursor will appear in it.

@defun selected-window
This function returns the selected window.  This is the window in
which the cursor appears and to which many commands apply.
@end defun

@defun select-window window
This function makes @var{window} the selected window.  The cursor then
appears in @var{window} (on redisplay).  The buffer being displayed in
@var{window} is immediately designated the current buffer.

The return value is @var{window}.

@example
@group
(setq w (next-window))
(select-window w)
     @result{} #<window 65 on windows.texi>
@end group
@end example
@end defun

Karl Heuer's avatar
Karl Heuer committed
420 421
@defmac save-selected-window forms@dots{}
This macro records the selected window, executes @var{forms}
422 423
in sequence, then restores the earlier selected window (unless that
window is no longer alive).
424 425

This macro does not save or restore anything about the sizes, arrangement
Karl Heuer's avatar
Karl Heuer committed
426
or contents of windows; therefore, if the @var{forms} change them,
427 428 429
the change persists.

Each frame, at any time, has a window selected within the frame.  This
430
macro saves only @emph{the} selected window; it does not save anything
431 432
about other frames.  If the @var{forms} select some other frame and
alter the window selected within it, the change persists.
Karl Heuer's avatar
Karl Heuer committed
433 434
@end defmac

Richard M. Stallman's avatar
Richard M. Stallman committed
435 436 437 438 439 440 441 442 443 444 445 446
@cindex finding windows
  The following functions choose one of the windows on the screen,
offering various criteria for the choice.

@defun get-lru-window &optional frame
This function returns the window least recently ``used'' (that is,
selected).  The selected window is always the most recently used window.

The selected window can be the least recently used window if it is the
only window.  A newly created window becomes the least recently used
window until it is selected.  A minibuffer window is never a candidate.

447
The argument @var{frame} controls which windows are considered.
Richard M. Stallman's avatar
Richard M. Stallman committed
448 449 450 451 452 453 454 455 456

@itemize @bullet
@item
If it is @code{nil}, consider windows on the selected frame.
@item
If it is @code{t}, consider windows on all frames.
@item
If it is @code{visible}, consider windows on all visible frames.
@item
Karl Heuer's avatar
Karl Heuer committed
457 458
If it is 0, consider windows on all visible or iconified frames.
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
459 460 461 462 463 464 465 466 467 468
If it is a frame, consider windows on that frame.
@end itemize
@end defun

@defun get-largest-window &optional frame
This function returns the window with the largest area (height times
width).  If there are no side-by-side windows, then this is the window
with the most lines.  A minibuffer window is never a candidate.

If there are two windows of the same size, then the function returns
469
the window that is first in the cyclic ordering of windows (see
Richard M. Stallman's avatar
Richard M. Stallman committed
470 471
following section), starting from the selected window.

472 473
The argument @var{frame} controls which set of windows to
consider.  See @code{get-lru-window}, above.
Richard M. Stallman's avatar
Richard M. Stallman committed
474 475
@end defun

476 477 478 479 480 481 482 483 484 485 486 487 488 489 490
@cindex window that satisfies a predicate
@cindex conditional selection of windows
@defun get-window-with-predicate predicate &optional minibuf all-frames default
This function returns a window satisfying @var{predicate}.  It cycles
through all visible windows using @code{walk-windows} (@pxref{Cyclic
Window Ordering}), calling @var{predicate} on each one one of them
with that window as its argument.  The function returns the first
window for which @var{predicate} returns a non-@code{nil} value; if
that never happens, it returns @var{default}.

The optional arguments @var{minibuf} and @var{all-frames} specify the
set of windows to include in the scan.  See the description of
@code{next-window} in @ref{Cyclic Window Ordering}, for details.
@end defun

Richard M. Stallman's avatar
Richard M. Stallman committed
491 492 493 494 495
@node Cyclic Window Ordering
@comment  node-name,  next,  previous,  up
@section Cyclic Ordering of Windows
@cindex cyclic ordering of windows
@cindex ordering of windows, cyclic
496
@cindex window ordering, cyclic
Richard M. Stallman's avatar
Richard M. Stallman committed
497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517

  When you use the command @kbd{C-x o} (@code{other-window}) to select
the next window, it moves through all the windows on the screen in a
specific cyclic order.  For any given configuration of windows, this
order never varies.  It is called the @dfn{cyclic ordering of windows}.

  This ordering generally goes from top to bottom, and from left to
right.  But it may go down first or go right first, depending on the
order in which the windows were split.

  If the first split was vertical (into windows one above each other),
and then the subwindows were split horizontally, then the ordering is
left to right in the top of the frame, and then left to right in the
next lower part of the frame, and so on.  If the first split was
horizontal, the ordering is top to bottom in the left part, and so on.
In general, within each set of siblings at any level in the window tree,
the order is left to right, or top to bottom.

@defun next-window &optional window minibuf all-frames
@cindex minibuffer window
This function returns the window following @var{window} in the cyclic
518 519
ordering of windows.  This is the window that @kbd{C-x o} would select
if typed when @var{window} is selected.  If @var{window} is the only
Richard M. Stallman's avatar
Richard M. Stallman committed
520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549
window visible, then this function returns @var{window}.  If omitted,
@var{window} defaults to the selected window.

The value of the argument @var{minibuf} determines whether the
minibuffer is included in the window order.  Normally, when
@var{minibuf} is @code{nil}, the minibuffer is included if it is
currently active; this is the behavior of @kbd{C-x o}.  (The minibuffer
window is active while the minibuffer is in use.  @xref{Minibuffers}.)

If @var{minibuf} is @code{t}, then the cyclic ordering includes the
minibuffer window even if it is not active.

If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
window is not included even if it is active.

The argument @var{all-frames} specifies which frames to consider.  Here
are the possible values and their meanings:

@table @asis
@item @code{nil}
Consider all the windows in @var{window}'s frame, plus the minibuffer
used by that frame even if it lies in some other frame.

@item @code{t}
Consider all windows in all existing frames.

@item @code{visible}
Consider all windows in all visible frames.  (To get useful results, you
must ensure @var{window} is in a visible frame.)

Karl Heuer's avatar
Karl Heuer committed
550
@item 0
Karl Heuer's avatar
Karl Heuer committed
551 552
Consider all windows in all visible or iconified frames.

Richard M. Stallman's avatar
Richard M. Stallman committed
553 554 555 556
@item anything else
Consider precisely the windows in @var{window}'s frame, and no others.
@end table

557
This example assumes there are two windows, both displaying the
Richard M. Stallman's avatar
Richard M. Stallman committed
558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581
buffer @samp{windows.texi}:

@example
@group
(selected-window)
     @result{} #<window 56 on windows.texi>
@end group
@group
(next-window (selected-window))
     @result{} #<window 52 on windows.texi>
@end group
@group
(next-window (next-window (selected-window)))
     @result{} #<window 56 on windows.texi>
@end group
@end example
@end defun

@defun previous-window &optional window minibuf all-frames
This function returns the window preceding @var{window} in the cyclic
ordering of windows.  The other arguments specify which windows to
include in the cycle, as in @code{next-window}.
@end defun

582
@deffn Command other-window count &optional all-frames
Richard M. Stallman's avatar
Richard M. Stallman committed
583
This function selects the @var{count}th following window in the cyclic
584 585
order.  If count is negative, then it moves back @minus{}@var{count}
windows in the cycle, rather than forward.  It returns @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
586

587
The argument @var{all-frames} has the same meaning as in
588 589 590
@code{next-window}, but the @var{minibuf} argument of @code{next-window}
is always effectively @code{nil}.

Richard M. Stallman's avatar
Richard M. Stallman committed
591 592 593 594 595 596 597 598 599 600 601 602 603
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn

@c Emacs 19 feature
@defun walk-windows proc &optional minibuf all-frames
This function cycles through all windows, calling @code{proc}
once for each window with the window as its sole argument.

The optional arguments @var{minibuf} and @var{all-frames} specify the
set of windows to include in the scan.  See @code{next-window}, above,
for details.
@end defun

604 605 606 607 608 609 610 611 612
@defun window-list &optional frame minibuf window
This function returns a list of the windows on @var{frame}, starting
with @var{window}.  If @var{frame} is @code{nil} or omitted, the
selected frame is used instead; if @var{window} is @code{nil} or
omitted, the selected window is used instead.

The value of @var{minibuf} determines if the minibuffer window will be
included in the result list.  If @var{minibuf} is @code{t}, the
minibuffer window will be included, even if it isn't active.  If
Dave Love's avatar
Dave Love committed
613
@var{minibuf} is @code{nil} or omitted, the minibuffer window will
614 615 616
only be included in the list if it is active.  If @var{minibuf} is
neither @code{nil} nor @code{t}, the minibuffer window is not
included, whether or not it is active.
Dave Love's avatar
Dave Love committed
617
@end defun
618

Richard M. Stallman's avatar
Richard M. Stallman committed
619 620 621 622 623 624 625 626 627 628 629
@node Buffers and Windows
@section Buffers and Windows
@cindex examining windows
@cindex windows, controlling precisely
@cindex buffers, controlled in windows

  This section describes low-level functions to examine windows or to
display buffers in windows in a precisely controlled fashion.
@iftex
See the following section for
@end iftex
Gerd Moellmann's avatar
Gerd Moellmann committed
630
@ifnottex
Richard M. Stallman's avatar
Richard M. Stallman committed
631
@xref{Displaying Buffers}, for
Gerd Moellmann's avatar
Gerd Moellmann committed
632
@end ifnottex
Richard M. Stallman's avatar
Richard M. Stallman committed
633 634 635 636 637 638 639
related functions that find a window to use and specify a buffer for it.
The functions described there are easier to use than these, but they
employ heuristics in choosing or creating a window; use these functions
when you need complete control.

@defun set-window-buffer window buffer-or-name
This function makes @var{window} display @var{buffer-or-name} as its
640 641 642
contents.  It returns @code{nil}.  This is the fundamental primitive
for changing which buffer is displayed in a window, and all ways
of doing that call this function.
Richard M. Stallman's avatar
Richard M. Stallman committed
643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681

@example
@group
(set-window-buffer (selected-window) "foo")
     @result{} nil
@end group
@end example
@end defun

@defun window-buffer &optional window
This function returns the buffer that @var{window} is displaying.  If
@var{window} is omitted, this function returns the buffer for the
selected window.

@example
@group
(window-buffer)
     @result{} #<buffer windows.texi>
@end group
@end example
@end defun

@defun get-buffer-window buffer-or-name &optional all-frames
This function returns a window currently displaying
@var{buffer-or-name}, or @code{nil} if there is none.  If there are
several such windows, then the function returns the first one in the
cyclic ordering of windows, starting from the selected window.
@xref{Cyclic Window Ordering}.

The argument @var{all-frames} controls which windows to consider.

@itemize @bullet
@item
If it is @code{nil}, consider windows on the selected frame.
@item
If it is @code{t}, consider windows on all frames.
@item
If it is @code{visible}, consider windows on all visible frames.
@item
Karl Heuer's avatar
Karl Heuer committed
682 683
If it is 0, consider windows on all visible or iconified frames.
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
684 685 686 687
If it is a frame, consider windows on that frame.
@end itemize
@end defun

688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713
@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
This function returns a list of all the windows currently displaying
@var{buffer-or-name}.

The two optional arguments work like the optional arguments of
@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
like the single optional argument of @code{get-buffer-window}.  Perhaps
we should change @code{get-buffer-window} in the future to make it
compatible with the other functions.

The argument @var{all-frames} controls which windows to consider.

@itemize @bullet
@item
If it is @code{nil}, consider windows on the selected frame.
@item
If it is @code{t}, consider windows on all frames.
@item
If it is @code{visible}, consider windows on all visible frames.
@item
If it is 0, consider windows on all visible or iconified frames.
@item
If it is a frame, consider windows on that frame.
@end itemize
@end defun

714 715 716 717 718
@defvar buffer-display-time
This variable records the time at which a buffer was last made visible
in a window.  It is always local in each buffer; each time
@code{set-window-buffer} is called, it sets this variable to
@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
719
When a buffer is first created, @code{buffer-display-time} starts out
720 721 722
with the value @code{nil}.
@end defvar

Richard M. Stallman's avatar
Richard M. Stallman committed
723 724 725 726 727 728 729 730 731 732 733 734 735
@node Displaying Buffers
@section Displaying Buffers in Windows
@cindex switching to a buffer
@cindex displaying a buffer

  In this section we describe convenient functions that choose a window
automatically and use it to display a specified buffer.  These functions
can also split an existing window in certain circumstances.  We also
describe variables that parameterize the heuristics used for choosing a
window.
@iftex
See the preceding section for
@end iftex
Gerd Moellmann's avatar
Gerd Moellmann committed
736
@ifnottex
Richard M. Stallman's avatar
Richard M. Stallman committed
737
@xref{Buffers and Windows}, for
Gerd Moellmann's avatar
Gerd Moellmann committed
738
@end ifnottex
739 740
low-level functions that give you more precise control.  All of these
functions work by calling @code{set-window-buffer}.
Richard M. Stallman's avatar
Richard M. Stallman committed
741 742 743 744

  Do not use the functions in this section in order to make a buffer
current so that a Lisp program can access or modify it; they are too
drastic for that purpose, since they change the display of buffers in
745
windows, which would be gratuitous and surprise the user.  Instead, use
746 747 748
@code{set-buffer} and @code{save-current-buffer} (@pxref{Current
Buffer}), which designate buffers as current for programmed access
without affecting the display of buffers in windows.
Richard M. Stallman's avatar
Richard M. Stallman committed
749 750 751 752 753 754 755 756 757

@deffn Command switch-to-buffer buffer-or-name &optional norecord
This function makes @var{buffer-or-name} the current buffer, and also
displays the buffer in the selected window.  This means that a human can
see the buffer and subsequent keyboard commands will apply to it.
Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
the current buffer but does not display it in the selected window.
@xref{Current Buffer}.

Karl Heuer's avatar
Karl Heuer committed
758 759 760 761
If @var{buffer-or-name} does not identify an existing buffer, then a new
buffer by that name is created.  The major mode for the new buffer is
set according to the variable @code{default-major-mode}.  @xref{Auto
Major Mode}.
Richard M. Stallman's avatar
Richard M. Stallman committed
762

763 764 765
Normally the specified buffer is put at the front of the buffer list
(both the selected frame's buffer list and the frame-independent buffer
list).  This affects the operation of @code{other-buffer}.  However, if
Richard M. Stallman's avatar
Richard M. Stallman committed
766 767 768 769 770
@var{norecord} is non-@code{nil}, this is not done.  @xref{The Buffer
List}.

The @code{switch-to-buffer} function is often used interactively, as
the binding of @kbd{C-x b}.  It is also used frequently in programs.  It
771
returns the buffer that it switched to.
Richard M. Stallman's avatar
Richard M. Stallman committed
772 773
@end deffn

774
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
Richard M. Stallman's avatar
Richard M. Stallman committed
775 776 777 778 779
This function makes @var{buffer-or-name} the current buffer and
displays it in a window not currently selected.  It then selects that
window.  The handling of the buffer is the same as in
@code{switch-to-buffer}.

780 781 782 783 784
The currently selected window is absolutely never used to do the job.
If it is the only window, then it is split to make a distinct window for
this purpose.  If the selected window is already displaying the buffer,
then it continues to do so, but another window is nonetheless found to
display it in as well.
785 786 787

This function updates the buffer list just like @code{switch-to-buffer}
unless @var{norecord} is non-@code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
788 789
@end deffn

790
@defun pop-to-buffer buffer-or-name &optional other-window norecord
Richard M. Stallman's avatar
Richard M. Stallman committed
791 792 793
This function makes @var{buffer-or-name} the current buffer and
switches to it in some window, preferably not the window previously
selected.  The ``popped-to'' window becomes the selected window within
794
its frame.  The return value is the buffer that was switched to.
Richard M. Stallman's avatar
Richard M. Stallman committed
795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818

If the variable @code{pop-up-frames} is non-@code{nil},
@code{pop-to-buffer} looks for a window in any visible frame already
displaying the buffer; if there is one, it returns that window and makes
it be selected within its frame.  If there is none, it creates a new
frame and displays the buffer in it.

If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
operates entirely within the selected frame.  (If the selected frame has
just a minibuffer, @code{pop-to-buffer} operates within the most
recently selected frame that was not just a minibuffer.)

If the variable @code{pop-up-windows} is non-@code{nil}, windows may
be split to create a new window that is different from the original
window.  For details, see @ref{Choosing Window}.

If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
creates another window even if @var{buffer-or-name} is already visible
in the selected window.  Thus @var{buffer-or-name} could end up
displayed in two windows.  On the other hand, if @var{buffer-or-name} is
already displayed in the selected window and @var{other-window} is
@code{nil}, then the selected window is considered sufficient display
for @var{buffer-or-name}, so that nothing needs to be done.

Karl Heuer's avatar
Karl Heuer committed
819 820 821
All the variables that affect @code{display-buffer} affect
@code{pop-to-buffer} as well.  @xref{Choosing Window}.

Richard M. Stallman's avatar
Richard M. Stallman committed
822
If @var{buffer-or-name} is a string that does not name an existing
Karl Heuer's avatar
Karl Heuer committed
823 824 825
buffer, a buffer by that name is created.  The major mode for the new
buffer is set according to the variable @code{default-major-mode}.
@xref{Auto Major Mode}.
826 827 828

This function updates the buffer list just like @code{switch-to-buffer}
unless @var{norecord} is non-@code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
829 830
@end defun

Karl Heuer's avatar
Karl Heuer committed
831 832 833 834 835 836 837 838 839 840
@deffn Command replace-buffer-in-windows buffer
This function replaces @var{buffer} with some other buffer in all
windows displaying it.  The other buffer used is chosen with
@code{other-buffer}.  In the usual applications of this function, you
don't care which other buffer is used; you just want to make sure that
@var{buffer} is no longer displayed.

This function returns @code{nil}.
@end deffn

Richard M. Stallman's avatar
Richard M. Stallman committed
841 842 843
@node Choosing Window
@section Choosing a Window for Display

844
  This section describes the basic facility that chooses a window to
Richard M. Stallman's avatar
Richard M. Stallman committed
845 846 847 848
display a buffer in---@code{display-buffer}.  All the higher-level
functions and commands use this subroutine.  Here we describe how to use
@code{display-buffer} and how to customize it.

849
@deffn Command display-buffer buffer-or-name &optional not-this-window frame
Richard M. Stallman's avatar
Richard M. Stallman committed
850 851 852 853 854 855 856 857 858 859 860 861 862 863 864
This command makes @var{buffer-or-name} appear in some window, like
@code{pop-to-buffer}, but it does not select that window and does not
make the buffer current.  The identity of the selected window is
unaltered by this function.

If @var{not-this-window} is non-@code{nil}, it means to display the
specified buffer in a window other than the selected one, even if it is
already on display in the selected window.  This can cause the buffer to
appear in two windows at once.  Otherwise, if @var{buffer-or-name} is
already being displayed in any window, that is good enough, so this
function does nothing.

@code{display-buffer} returns the window chosen to display
@var{buffer-or-name}.

865
If the argument @var{frame} is non-@code{nil}, it specifies which frames
866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882
to check when deciding whether the buffer is already displayed.  If the
buffer is already displayed in some window on one of these frames,
@code{display-buffer} simply returns that window.  Here are the possible
values of @var{frame}:

@itemize @bullet
@item
If it is @code{nil}, consider windows on the selected frame.
@item
If it is @code{t}, consider windows on all frames.
@item
If it is @code{visible}, consider windows on all visible frames.
@item
If it is 0, consider windows on all visible or iconified frames.
@item
If it is a frame, consider windows on that frame.
@end itemize
883

Richard M. Stallman's avatar
Richard M. Stallman committed
884 885 886 887
Precisely how @code{display-buffer} finds or creates a window depends on
the variables described below.
@end deffn

Gerd Moellmann's avatar
Gerd Moellmann committed
888 889 890 891 892 893 894 895 896 897
@defopt display-buffer-reuse-frames
If this variable is non-@code{nil}, @code{display-buffer} searches
existing frames for a window displaying the buffer.  If the buffer is
already displayed in a window in some frame, @code{display-buffer} makes
the frame visible and raises it, to use that window.  If the buffer is
not already displayed, or if @code{display-buffer-reuse-frames} is
@code{nil}, @code{display-buffer}'s behavior is determined by other
variables, described below.
@end defopt

Richard M. Stallman's avatar
Richard M. Stallman committed
898 899 900 901 902 903 904 905 906 907 908 909 910 911 912
@defopt pop-up-windows
This variable controls whether @code{display-buffer} makes new windows.
If it is non-@code{nil} and there is only one window, then that window
is split.  If it is @code{nil}, then @code{display-buffer} does not
split the single window, but uses it whole.
@end defopt

@defopt split-height-threshold
This variable determines when @code{display-buffer} may split a window,
if there are multiple windows.  @code{display-buffer} always splits the
largest window if it has at least this many lines.  If the largest
window is not this tall, it is split only if it is the sole window and
@code{pop-up-windows} is non-@code{nil}.
@end defopt

Gerd Moellmann's avatar
Gerd Moellmann committed
913 914 915 916 917 918 919
@defopt even-window-heights
This variable determines if @code{display-buffer} should even out window
heights if the buffer gets displayed in an existing window, above or
beneath another existing window.  If @code{even-window-heights} is
@code{t}, the default, window heights will be evened out.  If
@code{even-window-heights} is @code{nil}, the orginal window heights
will be left alone.
Dave Love's avatar
Dave Love committed
920
@end defopt
Gerd Moellmann's avatar
Gerd Moellmann committed
921

Richard M. Stallman's avatar
Richard M. Stallman committed
922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944
@c Emacs 19 feature
@defopt pop-up-frames
This variable controls whether @code{display-buffer} makes new frames.
If it is non-@code{nil}, @code{display-buffer} looks for an existing
window already displaying the desired buffer, on any visible frame.  If
it finds one, it returns that window.  Otherwise it makes a new frame.
The variables @code{pop-up-windows} and @code{split-height-threshold} do
not matter if @code{pop-up-frames} is non-@code{nil}.

If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
splits a window or reuses one.

@xref{Frames}, for more information.
@end defopt

@c Emacs 19 feature
@defvar pop-up-frame-function
This variable specifies how to make a new frame if @code{pop-up-frames}
is non-@code{nil}.

Its value should be a function of no arguments.  When
@code{display-buffer} makes a new frame, it does so by calling that
function, which should return a frame.  The default value of the
945
variable is a function that creates a frame using parameters from
Richard M. Stallman's avatar
Richard M. Stallman committed
946 947 948
@code{pop-up-frame-alist}.
@end defvar

949
@defopt pop-up-frame-alist
Richard M. Stallman's avatar
Richard M. Stallman committed
950 951 952
This variable holds an alist specifying frame parameters used when
@code{display-buffer} makes a new frame.  @xref{Frame Parameters}, for
more information about frame parameters.
953
@end defopt
Richard M. Stallman's avatar
Richard M. Stallman committed
954

955
@defopt special-display-buffer-names
956 957 958 959 960
A list of buffer names for buffers that should be displayed specially.
If the buffer's name is in this list, @code{display-buffer} handles the
buffer specially.

By default, special display means to give the buffer a dedicated frame.
Karl Heuer's avatar
Karl Heuer committed
961 962 963 964 965 966 967

If an element is a list, instead of a string, then the @sc{car} of the
list is the buffer name, and the rest of the list says how to create the
frame.  There are two possibilities for the rest of the list.  It can be
an alist, specifying frame parameters, or it can contain a function and
arguments to give to it.  (The function's first argument is always the
buffer to be displayed; the arguments from the list come after that.)
968
@end defopt
969

970
@defopt special-display-regexps
971 972 973 974 975 976
A list of regular expressions that specify buffers that should be
displayed specially.  If the buffer's name matches any of the regular
expressions in this list, @code{display-buffer} handles the buffer
specially.

By default, special display means to give the buffer a dedicated frame.
Karl Heuer's avatar
Karl Heuer committed
977 978 979 980

If an element is a list, instead of a string, then the @sc{car} of the
list is the regular expression, and the rest of the list says how to
create the frame.  See above, under @code{special-display-buffer-names}.
981
@end defopt
982 983 984 985 986 987 988 989 990 991

@defvar special-display-function
This variable holds the function to call to display a buffer specially.
It receives the buffer as an argument, and should return the window in
which it is displayed.

The default value of this variable is
@code{special-display-popup-frame}.
@end defvar

992
@defun special-display-popup-frame buffer &rest args
993 994 995 996
This function makes @var{buffer} visible in a frame of its own.  If
@var{buffer} is already displayed in a window in some frame, it makes
the frame visible and raises it, to use that window.  Otherwise, it
creates a frame that will be dedicated to @var{buffer}.
997

998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009
If @var{args} is an alist, it specifies frame parameters for the new
frame.

If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
@var{args})} is called as a function to actually create and set up the
frame; it is called with @var{buffer} as first argument, and @code{(cdr
@var{args})} as additional arguments.

This function always uses an existing window displaying @var{buffer},
whether or not it is in a frame of its own; but if you set up the above
variables in your init file, before @var{buffer} was created, then
presumably the window was previously made by this function.
1010 1011 1012 1013 1014 1015 1016
@end defun

@defopt special-display-frame-alist
This variable holds frame parameters for
@code{special-display-popup-frame} to use when it creates a frame.
@end defopt

1017
@defopt same-window-buffer-names
Karl Heuer's avatar
Karl Heuer committed
1018 1019 1020 1021
A list of buffer names for buffers that should be displayed in the
selected window.  If the buffer's name is in this list,
@code{display-buffer} handles the buffer by switching to it in the
selected window.
1022
@end defopt
Karl Heuer's avatar
Karl Heuer committed
1023

1024
@defopt same-window-regexps
Karl Heuer's avatar
Karl Heuer committed
1025 1026 1027 1028
A list of regular expressions that specify buffers that should be
displayed in the selected window.  If the buffer's name matches any of
the regular expressions in this list, @code{display-buffer} handles the
buffer by switching to it in the selected window.
1029
@end defopt
Karl Heuer's avatar
Karl Heuer committed
1030

Richard M. Stallman's avatar
Richard M. Stallman committed
1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046
@c Emacs 19 feature
@defvar display-buffer-function
This variable is the most flexible way to customize the behavior of
@code{display-buffer}.  If it is non-@code{nil}, it should be a function
that @code{display-buffer} calls to do the work.  The function should
accept two arguments, the same two arguments that @code{display-buffer}
received.  It should choose or create a window, display the specified
buffer, and then return the window.

This hook takes precedence over all the other options and hooks
described above.
@end defvar

@c Emacs 19 feature
@cindex dedicated window
A window can be marked as ``dedicated'' to its buffer.  Then
1047 1048
@code{display-buffer} will not try to use that window to display any
other buffer.
Richard M. Stallman's avatar
Richard M. Stallman committed
1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077

@defun window-dedicated-p window
This function returns @code{t} if @var{window} is marked as dedicated;
otherwise @code{nil}.
@end defun

@defun set-window-dedicated-p window flag
This function marks @var{window} as dedicated if @var{flag} is
non-@code{nil}, and nondedicated otherwise.
@end defun

@node Window Point
@section Windows and Point
@cindex window position
@cindex window point
@cindex position in window
@cindex point in window

  Each window has its own value of point, independent of the value of
point in other windows displaying the same buffer.  This makes it useful
to have multiple windows showing one buffer.

@itemize @bullet
@item
The window point is established when a window is first created; it is
initialized from the buffer's point, or from the window point of another
window opened on the buffer if such a window exists.

@item
1078 1079 1080 1081 1082 1083
Selecting a window sets the value of point in its buffer from the
window's value of point.  Conversely, deselecting a window sets the
window's value of point from that of the buffer.  Thus, when you switch
between windows that display a given buffer, the point value for the
selected window is in effect in the buffer, while the point values for
the other windows are stored in those windows.
Richard M. Stallman's avatar
Richard M. Stallman committed
1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096

@item
As long as the selected window displays the current buffer, the window's
point and the buffer's point always move together; they remain equal.

@item
@xref{Positions}, for more details on buffer positions.
@end itemize

  As far as the user is concerned, point is where the cursor is, and
when the user switches to another buffer, the cursor jumps to the
position of point in that buffer.

1097
@defun window-point &optional window
Richard M. Stallman's avatar
Richard M. Stallman committed
1098 1099
This function returns the current position of point in @var{window}.
For a nonselected window, this is the value point would have (in that
1100 1101
window's buffer) if that window were selected.  If @var{window} is
@code{nil}, the selected window is used.
Richard M. Stallman's avatar
Richard M. Stallman committed
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119

When @var{window} is the selected window and its buffer is also the
current buffer, the value returned is the same as point in that buffer.

Strictly speaking, it would be more correct to return the
``top-level'' value of point, outside of any @code{save-excursion}
forms.  But that value is hard to find.
@end defun

@defun set-window-point window position
This function positions point in @var{window} at position
@var{position} in @var{window}'s buffer.
@end defun

@node Window Start
@section The Window Start Position

  Each window contains a marker used to keep track of a buffer position
1120
that specifies where in the buffer display should start.  This position
Richard M. Stallman's avatar
Richard M. Stallman committed
1121 1122 1123 1124 1125 1126 1127 1128 1129
is called the @dfn{display-start} position of the window (or just the
@dfn{start}).  The character after this position is the one that appears
at the upper left corner of the window.  It is usually, but not
inevitably, at the beginning of a text line.

@defun window-start &optional window
@cindex window top line
This function returns the display-start position of window
@var{window}.  If @var{window} is @code{nil}, the selected window is
1130
used.  For example,
Richard M. Stallman's avatar
Richard M. Stallman committed
1131 1132 1133 1134 1135 1136 1137 1138

@example
@group
(window-start)
     @result{} 7058
@end group
@end example

1139
When you create a window, or display a different buffer in it, the
Richard M. Stallman's avatar
Richard M. Stallman committed
1140 1141 1142
display-start position is set to a display-start position recently used
for the same buffer, or 1 if the buffer doesn't have any.

1143
Redisplay updates the window-start position (if you have not specified
1144 1145 1146 1147 1148
it explicitly since the previous redisplay)---for example, to make sure
point appears on the screen.  Nothing except redisplay automatically
changes the window-start position; if you move point, do not expect the
window-start position to change in response until after the next
redisplay.
1149 1150 1151

For a realistic example of using @code{window-start}, see the
description of @code{count-lines} in @ref{Text Lines}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1152 1153
@end defun

1154
@defun window-end &optional window update
Richard M. Stallman's avatar
Richard M. Stallman committed
1155 1156 1157
This function returns the position of the end of the display in window
@var{window}.  If @var{window} is @code{nil}, the selected window is
used.
1158

1159 1160
Simply changing the buffer text or moving point does not update the
value that @code{window-end} returns.  The value is updated only when
1161
Emacs redisplays and redisplay completes without being preempted.
1162

1163
If the last redisplay of @var{window} was preempted, and did not finish,
1164
Emacs does not know the position of the end of display in that window.
1165
In that case, this function returns @code{nil}.
1166

1167 1168 1169 1170
If @var{update} is non-@code{nil}, @code{window-end} always returns an
up-to-date value for where the window ends, based on the current
@code{window-start} value.  If the saved value is valid,
@code{window-end} returns that; otherwise it computes the correct
1171
value by scanning the buffer text.
1172 1173 1174 1175 1176 1177

Even if @var{update} is non-@code{nil}, @code{window-end} does not
attempt to scroll the display if point has moved off the screen, the
way real redisplay would do.  It does not alter the
@code{window-start} value.  In effect, it reports where the displayed
text will end if scrolling is not required.
Richard M. Stallman's avatar
Richard M. Stallman committed
1178 1179 1180 1181
@end defun

@defun set-window-start window position &optional noforce
This function sets the display-start position of @var{window} to
1182
@var{position} in @var{window}'s buffer.  It returns @var{position}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240

The display routines insist that the position of point be visible when a
buffer is displayed.  Normally, they change the display-start position
(that is, scroll the window) whenever necessary to make point visible.
However, if you specify the start position with this function using
@code{nil} for @var{noforce}, it means you want display to start at
@var{position} even if that would put the location of point off the
screen.  If this does place point off screen, the display routines move
point to the left margin on the middle line in the window.

For example, if point @w{is 1} and you set the start of the window @w{to
2}, then point would be ``above'' the top of the window.  The display
routines will automatically move point if it is still 1 when redisplay
occurs.  Here is an example:

@example
@group
;; @r{Here is what @samp{foo} looks like before executing}
;;   @r{the @code{set-window-start} expression.}
@end group

@group
---------- Buffer: foo ----------
@point{}This is the contents of buffer foo.
2
3
4
5
6
---------- Buffer: foo ----------
@end group

@group
(set-window-start
 (selected-window)
 (1+ (window-start)))
@result{} 2
@end group

@group
;; @r{Here is what @samp{foo} looks like after executing}
;;   @r{the @code{set-window-start} expression.}
---------- Buffer: foo ----------
his is the contents of buffer foo.
2
3
@point{}4
5
6
---------- Buffer: foo ----------
@end group
@end example

If @var{noforce} is non-@code{nil}, and @var{position} would place point
off screen at the next redisplay, then redisplay computes a new window-start
position that works well with point, and thus @var{position} is not used.
@end defun

1241
@defun pos-visible-in-window-p &optional position window partially
Dave Love's avatar
Dave Love committed
1242
This function returns @code{t} if @var{position} is within the range of
1243 1244 1245 1246 1247 1248 1249 1250
text currently visible on the screen in @var{window}.  It returns
@code{nil} if @var{position} is scrolled vertically or horizontally out
of view.  Locations that are partially obscured are not considered
visible unless @var{partially} is non-@code{nil}.  The argument
@var{position} defaults to the current position of point in
@var{window}; @var{window}, to the selected window.

Here is an example:
Richard M. Stallman's avatar
Richard M. Stallman committed
1251 1252 1253 1254 1255 1256 1257 1258 1259 1260

@example
@group
(or (pos-visible-in-window-p
     (point) (selected-window))
    (recenter 0))
@end group
@end example
@end defun

1261 1262 1263 1264 1265 1266 1267 1268 1269
@node Textual Scrolling
@section Textual Scrolling
@cindex textual scrolling
@cindex scrolling textually

  @dfn{Textual scrolling} means moving the text up or down though a
window.  It works by changing the value of the window's display-start
location.  It may also change the value of @code{window-point} to keep
point on the screen.
Richard M. Stallman's avatar
Richard M. Stallman committed
1270

1271 1272 1273
  Textual scrolling was formerly called ``vertical scrolling,'' but we
changed its name to distinguish it from the new vertical fractional
scrolling feature (@pxref{Vertical Scrolling}).
Richard M. Stallman's avatar
Richard M. Stallman committed
1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291

  In the commands @code{scroll-up} and @code{scroll-down}, the directions
``up'' and ``down'' refer to the motion of the text in the buffer at which
you are looking through the window.  Imagine that the text is
written on a long roll of paper and that the scrolling commands move the
paper up and down.  Thus, if you are looking at text in the middle of a
buffer and repeatedly call @code{scroll-down}, you will eventually see
the beginning of the buffer.

  Some people have urged that the opposite convention be used: they
imagine that the window moves over text that remains in place.  Then
``down'' commands would take you to the end of the buffer.  This view is
more consistent with the actual relationship between windows and the
text in the buffer, but it is less like what the user sees.  The
position of a window on the terminal does not move, and short scrolling
commands clearly move the text up or down on the screen.  We have chosen
names that fit the user's point of view.

1292 1293 1294 1295
  The textual scrolling functions (aside from
@code{scroll-other-window}) have unpredictable results if the current
buffer is different from the buffer that is displayed in the selected
window.  @xref{Current Buffer}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315

@deffn Command scroll-up &optional count
This function scrolls the text in the selected window upward
@var{count} lines.  If @var{count} is negative, scrolling is actually
downward.

If @var{count} is @code{nil} (or omitted), then the length of scroll
is @code{next-screen-context-lines} lines less than the usable height of
the window (not counting its mode line).

@code{scroll-up} returns @code{nil}.
@end deffn

@deffn Command scroll-down &optional count
This function scrolls the text in the selected window downward
@var{count} lines.  If @var{count} is negative, scrolling is actually
upward.

If @var{count} is omitted or @code{nil}, then the length of the scroll
is @code{next-screen-context-lines} lines less than the usable height of
1316
the window (not counting its mode line).
Richard M. Stallman's avatar
Richard M. Stallman committed
1317 1318 1319 1320 1321 1322 1323 1324 1325

@code{scroll-down} returns @code{nil}.
@end deffn

@deffn Command scroll-other-window &optional count
This function scrolls the text in another window upward @var{count}
lines.  Negative values of @var{count}, or @code{nil}, are handled
as in @code{scroll-up}.

1326 1327 1328 1329 1330 1331 1332 1333
You can specify which buffer to scroll by setting the variable
@code{other-window-scroll-buffer} to a buffer.  If that buffer isn't
already displayed, @code{scroll-other-window} displays it in some
window.

When the selected window is the minibuffer, the next window is normally
the one at the top left corner.  You can specify a different window to
scroll, when the minibuffer is selected, by setting the variable
Richard M. Stallman's avatar
Richard M. Stallman committed
1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350
@code{minibuffer-scroll-window}.  This variable has no effect when any
other window is selected.  @xref{Minibuffer Misc}.

When the minibuffer is active, it is the next window if the selected
window is the one at the bottom right corner.  In this case,
@code{scroll-other-window} attempts to scroll the minibuffer.  If the
minibuffer contains just one line, it has nowhere to scroll to, so the
line reappears after the echo area momentarily displays the message
``Beginning of buffer''.
@end deffn

@c Emacs 19 feature
@defvar other-window-scroll-buffer
If this variable is non-@code{nil}, it tells @code{scroll-other-window}
which buffer to scroll.
@end defvar

1351 1352 1353 1354
@defopt scroll-margin
This option specifies the size of the scroll margin---a minimum number
of lines between point and the top or bottom of a window.  Whenever
point gets within this many lines of the top or bottom of the window,
Richard M. Stallman's avatar
Richard M. Stallman committed
1355 1356
redisplay scrolls the text automatically (if possible) to move point
out of the margin, closer to the center of the window.
1357 1358 1359
@end defopt

@defopt scroll-conservatively
Richard M. Stallman's avatar
Richard M. Stallman committed
1360
This variable controls how scrolling is done automatically when point
Richard M. Stallman's avatar
Richard M. Stallman committed
1361 1362 1363 1364 1365 1366 1367 1368 1369 1370
moves off the screen (or into the scroll margin).  If the value is a
positive integer @var{n}, then redisplay scrolls the text up to
@var{n} lines in either direction, if that will bring point back into
proper view.  This action is called @dfn{conservative scrolling}.
Otherwise, scrolling happens in the usual way, under the control of
other variables such as @code{scroll-up-aggressively} and
@code{scroll-down-aggressively}.

The default value is zero, which means that conservative scrolling
never happens.
1371 1372
@end defopt

1373 1374
@defopt scroll-down-aggressively
@tindex scroll-down-aggressively
Gerd Moellmann's avatar
Gerd Moellmann committed
1375 1376
The value of this variable should be either @code{nil} or a fraction
@var{f} between 0 and 1.  If it is a fraction, that specifies where on
1377 1378 1379 1380 1381
the screen to put point when scrolling down.  More precisely, when a
window scrolls down because point is above the window start, the new
start position is chosen to put point @var{f} part of the window
height from the top.  The larger @var{f}, the more aggressive the
scrolling.
Gerd Moellmann's avatar
Gerd Moellmann committed
1382

1383 1384 1385
A value of @code{nil} is equivalent to .5, since its effect is to center
point.  This variable automatically becomes buffer-local when set in any
fashion.
Gerd Moellmann's avatar
Gerd Moellmann committed
1386 1387
@end defopt

1388 1389 1390
@defopt scroll-up-aggressively
@tindex scroll-up-aggressively
Likewise, for scrolling up.  The value, @var{f}, specifies how far
Gerd Moellmann's avatar
Gerd Moellmann committed
1391 1392 1393 1394
point should be placed from the bottom of the window; thus, as with
@code{scroll-up-aggressively}, a larger value scrolls more aggressively.
@end defopt

1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405
@defopt scroll-step
This variable is an older variant of @code{scroll-conservatively}.  The
difference is that it if its value is @var{n}, that permits scrolling
only by precisely @var{n} lines, not a smaller number.  This feature
does not work with @code{scroll-margin}.  The default value is zero.
@end defopt

@defopt scroll-preserve-screen-position
If this option is non-@code{nil}, the scroll functions move point so
that the vertical position of the cursor is unchanged, when that is
possible.
Richard M. Stallman's avatar
Richard M. Stallman committed
1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417
@end defopt

@defopt next-screen-context-lines
The value of this variable is the number of lines of continuity to
retain when scrolling by full screens.  For example, @code{scroll-up}
with an argument of @code{nil} scrolls so that this many lines at the
bottom of the window appear instead at the top.  The default value is
@code{2}.
@end defopt

@deffn Command recenter &optional count
@cindex centering point
Richard M. Stallman's avatar
Richard M. Stallman committed
1418 1419 1420 1421 1422 1423 1424 1425 1426 1427
This function scrolls the text in the selected window so that point is
displayed at a specified vertical position within the window.  It does
not ``move point'' with respect to the text.

If @var{count} is a nonnegative number, that puts the line containing
point @var{count} lines down from the top of the window.  If
@var{count} is a negative number, then it counts upward from the
bottom of the window, so that @minus{}1 stands for the last usable
line in the window.  If @var{count} is a non-@code{nil} list, then it
stands for the line in the middle of the window.
Richard M. Stallman's avatar
Richard M. Stallman committed
1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438

If @var{count} is @code{nil}, @code{recenter} puts the line containing
point in the middle of the window, then clears and redisplays the entire
selected frame.

When @code{recenter} is called interactively, @var{count} is the raw
prefix argument.  Thus, typing @kbd{C-u} as the prefix sets the
@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
@var{count} to 4, which positions the current line four lines from the
top.

1439 1440 1441
With an argument of zero, @code{recenter} positions the current line at
the top of the window.  This action is so handy that some people make a
separate key binding to do this.  For example,
Richard M. Stallman's avatar
Richard M. Stallman committed
1442 1443 1444 1445 1446 1447

@example
@group
(defun line-to-top-of-window ()
  "Scroll current line to top of window.
Replaces three keystroke sequence C-u 0 C-l."
1448
  (interactive)
Richard M. Stallman's avatar
Richard M. Stallman committed
1449 1450
  (recenter 0))

1451
(global-set-key [kp-multiply] 'line-to-top-of-window)