windows.texi 89 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.
Luc Teirlinck's avatar
Luc Teirlinck committed
3
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004
Gerd Moellmann's avatar
Gerd Moellmann committed
4
@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
* 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.
Richard M. Stallman's avatar
Richard M. Stallman committed
21
* Displaying Buffers::      Higher-level functions for displaying a buffer
22 23 24 25 26
                              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 57 58 59
window, but the other windows have ``non-selected'' cursors, normally
less visible.  At any time, one frame is the selected frame; and the
window selected within that frame is @dfn{the selected window}.  The
selected window's buffer is usually the current buffer (except when
Karl Heuer's avatar
Karl Heuer committed
60 61
@code{set-buffer} has been used).  @xref{Current Buffer}.

62 63 64 65 66
@defvar cursor-in-non-selected-windows
If this variable is @code{nil}, Emacs displays only one cursor,
in the selected window.  Other windows have no cursor at all.
@end defvar

Karl Heuer's avatar
Karl Heuer committed
67 68 69 70 71 72
  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
73 74 75 76 77 78 79

  Each window has the following attributes:

@itemize @bullet
@item
containing frame

80
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
81 82
window height

83
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
84 85
window width

86
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
87 88
window edges with respect to the screen or frame

89
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
90 91
the buffer it displays

92
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
93 94
position within the buffer at the upper left of the window

95
@item
96
amount of horizontal scrolling, in columns
Richard M. Stallman's avatar
Richard M. Stallman committed
97

98
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
99 100
point

101
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
102 103
the mark

104
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
105
how recently the window was selected
106 107 108 109 110 111 112 113 114

@item
fringe settings

@item
display margins

@item
scroll-bar settings
Richard M. Stallman's avatar
Richard M. Stallman committed
115 116 117 118 119
@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
120 121 122
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
123 124

  The meaning of ``window'' in Emacs is similar to what it means in the
125
context of general-purpose window systems such as X, but not identical.
Karl Heuer's avatar
Karl Heuer committed
126 127 128 129
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
130 131 132 133 134 135

@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
136 137 138 139
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
140 141 142 143 144

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

@defun windowp object
145
This function returns @code{t} if @var{object} is a window.
Richard M. Stallman's avatar
Richard M. Stallman committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
@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.

168
If @var{horizontal} is non-@code{nil}, then @var{window} splits into
Richard M. Stallman's avatar
Richard M. Stallman committed
169 170 171 172 173
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
174
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
175 176
lower.

177
If @var{window} is omitted or @code{nil}, then the selected window is
Richard M. Stallman's avatar
Richard M. Stallman committed
178 179 180 181 182
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}.

183 184 185 186 187
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
188
lines high by 80 columns wide; then it splits the window.
Richard M. Stallman's avatar
Richard M. Stallman committed
189 190 191 192 193 194 195 196 197 198 199

@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}
200
(setq w2 (split-window w 15))
Richard M. Stallman's avatar
Richard M. Stallman committed
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
     @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
218 219
         __________
        |          |  line 0
Richard M. Stallman's avatar
Richard M. Stallman committed
220 221 222 223 224 225 226 227 228 229
        |    w     |
        |__________|
        |          |  line 15
        |    w2    |
        |__________|
                      line 50
 column 0   column 80
@end group
@end smallexample

230
Next, split the top window horizontally:
Richard M. Stallman's avatar
Richard M. Stallman committed
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250

@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

251
@need 3000
252
Now the screen looks like this:
Richard M. Stallman's avatar
Richard M. Stallman committed
253 254 255 256

@smallexample
@group
     column 35
257 258
         __________
        |   |      |  line 0
Richard M. Stallman's avatar
Richard M. Stallman committed
259 260 261 262 263 264 265 266 267
        | w |  w3  |
        |___|______|
        |          |  line 15
        |    w2    |
        |__________|
                      line 50
 column 0   column 80
@end group
@end smallexample
Jim Blandy's avatar
Jim Blandy committed
268 269

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

275
@deffn Command split-window-vertically &optional size
276
This function splits the selected window into two windows, one above the
277
other, leaving the upper of the two windows selected, with @var{size}
278 279
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
280 281 282 283 284 285 286
the upper window is still the one selected.)  However, if
@code{split-window-keep-point} (see below) is @code{nil}, then either
window can be selected.

In other respects, this function is similar to @code{split-window}.
In particular, the upper window is the original one and the return
value is the new, lower window.
Richard M. Stallman's avatar
Richard M. Stallman committed
287 288
@end deffn

289 290 291 292 293 294 295 296 297 298 299 300 301
@defopt split-window-keep-point
If this variable is non-@code{nil} (the default), then
@code{split-window-vertically} behaves as described above.

If it is @code{nil}, then @code{split-window-vertically} adjusts point
in each of the two windows to avoid scrolling.  (This is useful on
slow terminals.)  It selects whichever window contains the screen line
that point was previously on.

This variable only affects the behavior of @code{split-window-vertically}.
It has no effect on the other functions described here.
@end defopt

302
@deffn Command split-window-horizontally &optional size
Richard M. Stallman's avatar
Richard M. Stallman committed
303
This function splits the selected window into two windows
304 305 306 307
side-by-side, leaving the selected window on the left with @var{size}
columns.  If @var{size} is negative, the rightmost window gets
@minus{} @var{size} columns, but the leftmost window still remains
selected.
Richard M. Stallman's avatar
Richard M. Stallman committed
308

309 310
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
311 312 313 314 315 316

@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
317
@end group
318 319 320 321 322
@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
323 324 325 326 327 328 329 330
@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
331
counted when it is active.
Richard M. Stallman's avatar
Richard M. Stallman committed
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346

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
347 348 349
@item 0
Count all windows in all visible or iconified frames.

Richard M. Stallman's avatar
Richard M. Stallman committed
350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367
@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
368
adjacent sibling.
Richard M. Stallman's avatar
Richard M. Stallman committed
369 370 371 372 373 374

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

375
@strong{Warning:} Erroneous information or fatal errors may result from
Richard M. Stallman's avatar
Richard M. Stallman committed
376 377 378 379
using a deleted window as if it were live.
@end defun

@deffn Command delete-window &optional window
380 381 382 383
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
384 385 386 387 388 389 390
@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.

391
The return value is @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
392 393
@end deffn

394 395 396 397 398
@deffn Command delete-windows-on buffer-or-name &optional frame
This function deletes all windows showing @var{buffer-or-name}.  If
there are no windows showing @var{buffer-or-name}, it does nothing.
@var{buffer-or-name} must be a buffer or the name of an existing
buffer.
Richard M. Stallman's avatar
Richard M. Stallman committed
399 400 401

@code{delete-windows-on} operates frame by frame.  If a frame has
several windows showing different buffers, then those showing
402 403 404 405 406
@var{buffer-or-name} are removed, and the others expand to fill the
space.  If all windows in some frame are showing @var{buffer-or-name}
(including the case where there is only one window), then the frame
winds up with a single window showing another buffer chosen with
@code{other-buffer}.  @xref{The Buffer List}.
Richard M. Stallman's avatar
Richard M. Stallman committed
407

408 409 410 411 412
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
413 414 415

@itemize @bullet
@item
416
If it is @code{nil}, operate on all frames.
Richard M. Stallman's avatar
Richard M. Stallman committed
417
@item
418
If it is @code{t}, operate on the selected frame.
Richard M. Stallman's avatar
Richard M. Stallman committed
419 420
@item
If it is @code{visible}, operate on all visible frames.
421
@item
Karl Heuer's avatar
Karl Heuer committed
422
If it is 0, operate on all visible or iconified frames.
Richard M. Stallman's avatar
Richard M. Stallman committed
423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441
@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

442
@defun select-window window &optional norecord
Richard M. Stallman's avatar
Richard M. Stallman committed
443
This function makes @var{window} the selected window.  The cursor then
444 445 446
appears in @var{window} (on redisplay).  Unless @var{window} was
already selected, @code{select-window} makes @var{window}'s buffer the
current buffer.
Richard M. Stallman's avatar
Richard M. Stallman committed
447

448 449 450 451
Normally @var{window}'s selected buffer is moved to the front of the
buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
order is unchanged.

Richard M. Stallman's avatar
Richard M. Stallman committed
452 453 454 455 456 457 458 459 460 461 462
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
463
@defmac save-selected-window forms@dots{}
464
This macro records the selected frame, as well as the selected window
465
of each frame, executes @var{forms} in sequence, then restores the
466 467
earlier selected frame and windows.  It also saves and restores the
current buffer.  It returns the value of the last form in @var{forms}.
468 469 470 471

This macro does not save or restore anything about the sizes,
arrangement or contents of windows; therefore, if the @var{forms}
change them, the change persists.  If the previously selected window
472 473 474 475
of some frame is no longer live at the time of exit from @var{forms},
that frame's selected window is left alone.  If the previously
selected window is no longer live, then whatever window is selected at
the end of @var{forms} remains selected.
Karl Heuer's avatar
Karl Heuer committed
476 477
@end defmac

478 479 480
@defmac with-selected-window window forms@dots{}
This macro selects @var{window} (without changing the buffer list),
executes @var{forms} in sequence, then restores the previously
481 482 483
selected window and current buffer.  It is just like
@code{save-selected-window}, except that it explicitly selects
@var{window}, also without altering the buffer list sequence.
484 485
@end defmac

Richard M. Stallman's avatar
Richard M. Stallman committed
486 487 488 489 490 491
@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,
492 493
selected).  If any full-width windows are present, it only considers
these.  The selected window is always the most recently used window.
Richard M. Stallman's avatar
Richard M. Stallman committed
494 495 496

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
497 498 499
window until it is selected.  A minibuffer window is never a
candidate.  Dedicated windows are never candidates, and if all
existing windows are dedicated, the value is @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
500

501
The argument @var{frame} controls which windows are considered.
Richard M. Stallman's avatar
Richard M. Stallman committed
502 503 504 505 506 507 508 509 510

@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
511 512
If it is 0, consider windows on all visible or iconified frames.
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
513 514 515 516 517 518 519 520
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.
521 522
Dedicated windows are never candidates, and if all existing windows
are dedicated, the value is @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
523

524 525 526
If there are two candidate windows of the same size, this function
prefers the one that comes first in the cyclic ordering of windows
(see following section), starting from the selected window.
Richard M. Stallman's avatar
Richard M. Stallman committed
527

528 529
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
530 531
@end defun

532 533 534 535 536
@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
Richard M. Stallman's avatar
Richard M. Stallman committed
537
Window Ordering}), calling @var{predicate} on each one of them
538 539 540 541 542 543 544 545 546
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
547 548 549 550 551
@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
552
@cindex window ordering, cyclic
Richard M. Stallman's avatar
Richard M. Stallman committed
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573

  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
574 575
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
576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596
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
597 598 599
used by that frame even if it lies in some other frame.  If the
minibuffer counts (as determined by @var{minibuf}), then all windows on
all frames that share that minibuffer count too.
Richard M. Stallman's avatar
Richard M. Stallman committed
600 601 602 603 604 605 606 607

@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
608
@item 0
Karl Heuer's avatar
Karl Heuer committed
609 610
Consider all windows in all visible or iconified frames.

611 612 613
@item a frame
Consider all windows on that frame.

Richard M. Stallman's avatar
Richard M. Stallman committed
614 615 616 617
@item anything else
Consider precisely the windows in @var{window}'s frame, and no others.
@end table

618
This example assumes there are two windows, both displaying the
Richard M. Stallman's avatar
Richard M. Stallman committed
619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642
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

643
@deffn Command other-window count &optional all-frames
Richard M. Stallman's avatar
Richard M. Stallman committed
644
This function selects the @var{count}th following window in the cyclic
645 646
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
647

648
The argument @var{all-frames} has the same meaning as in
649 650 651
@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
652 653 654 655 656
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
657 658 659
This function cycles through all windows.  It calls the function
@code{proc} once for each window, with the window as its sole
argument.
Richard M. Stallman's avatar
Richard M. Stallman committed
660 661 662 663 664 665

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

666 667
@defun window-list &optional frame minibuf window
This function returns a list of the windows on @var{frame}, starting
668 669 670 671 672 673 674 675 676 677
with @var{window}.  If @var{frame} is @code{nil} or omitted,
@code{window-list} uses the selected frame instead; if @var{window} is
@code{nil} or omitted, it uses the selected window.

The value of @var{minibuf} determines if the minibuffer window is
included in the result list.  If @var{minibuf} is @code{t}, the result
always includes the minibuffer window.  If @var{minibuf} is @code{nil}
or omitted, that includes the minibuffer window if it is active.  If
@var{minibuf} is neither @code{nil} nor @code{t}, the result never
includes the minibuffer window.
Dave Love's avatar
Dave Love committed
678
@end defun
679

Richard M. Stallman's avatar
Richard M. Stallman committed
680 681 682 683 684 685 686 687 688 689 690
@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
691
@ifnottex
Richard M. Stallman's avatar
Richard M. Stallman committed
692
@xref{Displaying Buffers}, for
Gerd Moellmann's avatar
Gerd Moellmann committed
693
@end ifnottex
Richard M. Stallman's avatar
Richard M. Stallman committed
694 695 696 697 698
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.

699
@defun set-window-buffer window buffer-or-name &optional keep-margins
Richard M. Stallman's avatar
Richard M. Stallman committed
700
This function makes @var{window} display @var{buffer-or-name} as its
701 702 703 704
contents.  It returns @code{nil}.  @var{buffer-or-name} must be a
buffer, or the name of an existing buffer.  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
705 706 707 708 709 710 711

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

Normally, displaying @var{buffer} in @var{window} resets the window's
714 715 716 717
display margins, fringe widths, scroll bar settings, and position
based on the local variables of @var{buffer}.  However, if
@var{keep-margins} is non-@code{nil}, the display margins and fringe
widths of @var{window} remain unchanged.  @xref{Fringes}.
Richard M. Stallman's avatar
Richard M. Stallman committed
718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749
@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
750 751
If it is 0, consider windows on all visible or iconified frames.
@item
Richard M. Stallman's avatar
Richard M. Stallman committed
752 753 754 755
If it is a frame, consider windows on that frame.
@end itemize
@end defun

756 757 758 759 760 761 762 763 764 765 766
@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.
@end defun

767 768 769 770 771
@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}).
772
When a buffer is first created, @code{buffer-display-time} starts out
773 774 775
with the value @code{nil}.
@end defvar

Richard M. Stallman's avatar
Richard M. Stallman committed
776 777 778 779 780 781 782 783 784 785 786 787 788
@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
789
@ifnottex
Richard M. Stallman's avatar
Richard M. Stallman committed
790
@xref{Buffers and Windows}, for
Gerd Moellmann's avatar
Gerd Moellmann committed
791
@end ifnottex
792 793
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
794 795 796 797

  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
798
windows, which would be gratuitous and surprise the user.  Instead, use
799 800 801
@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
802 803 804 805 806 807 808 809 810

@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
811 812 813
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
814 815
Major Mode}.  If @var{buffer-or-name} is @code{nil},
@code{switch-to-buffer} chooses a buffer using @code{other-buffer}.
Richard M. Stallman's avatar
Richard M. Stallman committed
816

817 818 819
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
820 821 822 823 824
@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
825
returns the buffer that it switched to.
Richard M. Stallman's avatar
Richard M. Stallman committed
826 827
@end deffn

828 829 830
The next two functions are similar to @code{switch-to-buffer}, except
for the described features.

831
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
Richard M. Stallman's avatar
Richard M. Stallman committed
832 833 834 835 836
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}.

837 838 839 840 841
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.
842 843 844

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
845 846
@end deffn

847
@defun pop-to-buffer buffer-or-name &optional other-window norecord
Richard M. Stallman's avatar
Richard M. Stallman committed
848 849 850
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
851
its frame.  The return value is the buffer that was switched to.
852 853
If @var{buffer-or-name} is @code{nil}, that means to choose some
other buffer, but you don't specify which.
Richard M. Stallman's avatar
Richard M. Stallman committed
854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877

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
878 879 880
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
881
If @var{buffer-or-name} is a string that does not name an existing
Karl Heuer's avatar
Karl Heuer committed
882 883 884
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}.
885 886 887

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
888 889
@end defun

890 891 892
@deffn Command replace-buffer-in-windows buffer-or-name
This function replaces @var{buffer-or-name} with some other buffer in all
windows displaying it.  It chooses the other buffer with
Karl Heuer's avatar
Karl Heuer committed
893 894
@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
895
@var{buffer-or-name} is no longer displayed.
Karl Heuer's avatar
Karl Heuer committed
896 897 898 899

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

Richard M. Stallman's avatar
Richard M. Stallman committed
900 901 902
@node Choosing Window
@section Choosing a Window for Display

903
  This section describes the basic facility that chooses a window to
Richard M. Stallman's avatar
Richard M. Stallman committed
904 905 906 907
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.

908
@deffn Command display-buffer buffer-or-name &optional not-this-window frame
Richard M. Stallman's avatar
Richard M. Stallman committed
909 910 911
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
912 913
unaltered by this function.  @var{buffer-or-name} must be a buffer, or
the name of an existing buffer.
Richard M. Stallman's avatar
Richard M. Stallman committed
914 915 916 917 918 919 920 921 922 923 924

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}.

925
If the argument @var{frame} is non-@code{nil}, it specifies which frames
926 927 928 929 930 931 932 933
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.
934
(Actually, the last non-minibuffer frame.)
935 936 937 938 939 940 941 942 943
@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
944

Richard M. Stallman's avatar
Richard M. Stallman committed
945 946 947 948
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
949 950 951 952 953 954 955 956 957 958
@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
959 960 961 962 963 964 965 966 967 968 969 970 971 972 973
@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
974 975 976 977 978
@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
Pavel Janík's avatar
Pavel Janík committed
979
@code{even-window-heights} is @code{nil}, the original window heights
Gerd Moellmann's avatar
Gerd Moellmann committed
980
will be left alone.
Dave Love's avatar
Dave Love committed
981
@end defopt
Gerd Moellmann's avatar
Gerd Moellmann committed
982

Richard M. Stallman's avatar
Richard M. Stallman committed
983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998
@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
999
@defopt pop-up-frame-function
Richard M. Stallman's avatar
Richard M. Stallman committed
1000 1001 1002 1003 1004 1005
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
1006
variable is a function that creates a frame using parameters from
Richard M. Stallman's avatar
Richard M. Stallman committed
1007
@code{pop-up-frame-alist}.
Luc Teirlinck's avatar
Luc Teirlinck committed
1008
@end defopt
Richard M. Stallman's avatar
Richard M. Stallman committed
1009

1010
@defopt pop-up-frame-alist
Richard M. Stallman's avatar
Richard M. Stallman committed
1011 1012 1013
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.
1014
@end defopt
Richard M. Stallman's avatar
Richard M. Stallman committed
1015

1016
@defopt special-display-buffer-names
1017 1018 1019 1020 1021
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
1022 1023

If an element is a list, instead of a string, then the @sc{car} of the
1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039
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 (its
@sc{cdr}).  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.)

For example:

@example
(("myfile" (minibuffer) (menu-bar-lines . 0)))
@end example

@noindent
specifies to display a buffer named @samp{myfile} in a dedicated frame
with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
1040 1041 1042 1043 1044 1045 1046 1047

The list of frame parameters can also use the phony frame parameters
@code{same-frame} and @code{same-window}.  If the specified frame
parameters include @code{(same-window . @var{value})} and @var{value}
is non-@code{nil}, that means to display the buffer in the current
selected window.  Otherwise, if they include @code{(same-frame .
@var{value})} and @var{value} is non-@code{nil}, that means to display
the buffer in a new window in the currently selected frame.
1048
@end defopt
1049

1050
@defopt special-display-regexps
1051 1052 1053 1054 1055 1056
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
1057 1058 1059 1060

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}.
1061
@end defopt
1062

1063 1064 1065 1066
@defun special-display-p buffer-name
This function returns non-@code{nil} if displaying a buffer
named @var{buffer-name} with @code{display-buffer} would
create a special frame.  The value is @code{t} if it would
1067
use the default frame parameters, or else the specified list
1068 1069 1070
of frame parameters.
@end defun

1071 1072 1073 1074 1075 1076 1077 1078 1079
@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

1080
@defun special-display-popup-frame buffer &optional args
1081 1082 1083
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
1084 1085
creates a frame that will be dedicated to @var{buffer}.  This
function returns the window it used.
1086

1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098
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.
1099 1100 1101
@end defun

@defopt special-display-frame-alist
Luc Teirlinck's avatar
Luc Teirlinck committed
1102
@anchor{Definition of special-display-frame-alist}
1103 1104 1105 1106
This variable holds frame parameters for
@code{special-display-popup-frame} to use when it creates a frame.
@end defopt

1107
@defopt same-window-buffer-names
Karl Heuer's avatar
Karl Heuer committed
1108 1109 1110 1111
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.
1112
@end defopt
Karl Heuer's avatar
Karl Heuer committed
1113

1114
@defopt same-window-regexps
Karl Heuer's avatar
Karl Heuer committed
1115 1116 1117 1118
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.
1119
@end defopt
Karl Heuer's avatar
Karl Heuer committed
1120

1121 1122 1123 1124 1125 1126
@defun same-window-p buffer-name
This function returns @code{t} if displaying a buffer
named @var{buffer-name} with @code{display-buffer} would
put it in the selected window.
@end defun

Richard M. Stallman's avatar
Richard M. Stallman committed
1127 1128 1129 1130 1131
@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
1132
accept two arguments, the first two arguments that @code{display-buffer}
Richard M. Stallman's avatar
Richard M. Stallman committed
1133
received.  It should choose or create a window, display the specified
1134
buffer in it, and then return the window.
Richard M. Stallman's avatar
Richard M. Stallman committed
1135 1136 1137 1138 1139 1140 1141 1142

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
1143 1144
@code{display-buffer} will not try to use that window to display any
other buffer.
Richard M. Stallman's avatar
Richard M. Stallman committed
1145 1146

@defun window-dedicated-p window
1147 1148
This function returns non-@code{nil} if @var{window} is marked as
dedicated; otherwise @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173
@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
1174 1175 1176 1177 1178 1179
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
1180 1181 1182 1183

@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.
1184
@end itemize
Richard M. Stallman's avatar
Richard M. Stallman committed
1185

1186
@noindent
Richard M. Stallman's avatar
Richard M. Stallman committed
1187 1188 1189 1190 1191 1192
@xref{Positions}, for more details on buffer positions.

  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.

1193
@defun window-point &optional window
Richard M. Stallman's avatar
Richard M. Stallman committed
1194 1195
This function returns the current position of point in @var{window}.
For a nonselected window, this is the value point would have (in that
1196 1197
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
1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208

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
1209
@var{position} in @var{window}'s buffer.  It returns @var{position}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1210 1211 1212 1213 1214 1215
@end defun

@node Window Start
@section The Window Start Position

  Each window contains a marker used to keep track of a buffer position
1216
that specifies where in the buffer display should start.  This position
Richard M. Stallman's avatar
Richard M. Stallman committed
1217 1218 1219 1220 1221 1222 1223 1224 1225
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
1226
used.  For example,
Richard M. Stallman's avatar
Richard M. Stallman committed
1227 1228 1229 1230 1231 1232 1233 1234

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

1235
When you create a window, or display a different buffer in it, the
Richard M. Stallman's avatar
Richard M. Stallman committed
1236 1237 1238
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.

1239
Redisplay updates the window-start position (if you have not specified
1240 1241 1242 1243 1244
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.
1245 1246

For a realistic example of using @code{window-start}, see the
1247
description of @code{count-lines}.  @xref{Definition of count-lines}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1248 1249
@end defun

1250
@defun window-end &optional window update
Richard M. Stallman's avatar
Richard M. Stallman committed
1251 1252 1253
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.
1254

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

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

1263 1264 1265 1266
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
1267
value by scanning the buffer text.
1268 1269 1270 1271 1272 1273

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
1274 1275 1276 1277
@end defun

@defun set-window-start window position &optional noforce
This function sets the display-start position of @var{window} to
1278
@var{position} in @var{window}'s buffer.  It returns @var{position}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293